Merge from viewer-experience

1 files changed, 60 insertions, 47 deletions

diff --git a/indra/llmessage/llproxy.h b/indra/llmessage/llproxy.h
index 621debb61d..a919370540 100644
--- a/indra/llmessage/llproxy.h
+++ b/indra/llmessage/llproxy.h
@@ -36,7 +36,6 @@
 #include <string>
 
 // SOCKS error codes returned from the StartProxy method
-
 #define SOCKS_OK 0
 #define SOCKS_CONNECT_ERROR (-1)
 #define SOCKS_NOT_PERMITTED (-2)
@@ -46,7 +45,6 @@
 #define SOCKS_HOST_CONNECT_FAILED (-6)
 #define SOCKS_INVALID_HOST (-7)
 
-
 #ifndef MAXHOSTNAMELEN
 #define	MAXHOSTNAMELEN (255 + 1) /* socks5: 255, +1 for len. */
 #endif
@@ -225,62 +223,71 @@ class LLProxy: public LLSingleton<LLProxy>
 {
 	LOG_CLASS(LLProxy);
 public:
-	// METHODS THAT DO NOT LOCK mProxyMutex!
-
+	/*###########################################################################################
+	METHODS THAT DO NOT LOCK mProxyMutex!
+	###########################################################################################*/
+	// Constructor, cannot have parameters due to LLSingleton parent class. Call from main thread only.
 	LLProxy();
 
-	// static check for enabled status for UDP packets
+	// Static check for enabled status for UDP packets. Call from main thread only.
 	static bool isSOCKSProxyEnabled() { return sUDPProxyEnabled; }
 
-	// check for enabled status for HTTP packets
-	// mHTTPProxyEnabled is atomic, so no locking is required for thread safety.
-	bool isHTTPProxyEnabled() const { return mHTTPProxyEnabled; }
-
-	// Get the UDP proxy address and port
+	// Get the UDP proxy address and port. Call from main thread only.
 	LLHost getUDPProxy() const { return mUDPProxy; }
 
-	// Get the SOCKS 5 TCP control channel address and port
-	LLHost getTCPProxy() const { return mTCPProxy; }
+	/*###########################################################################################
+	END OF NON-LOCKING METHODS
+	###########################################################################################*/
 
-	// END OF NON-LOCKING METHODS
+	/*###########################################################################################
+	METHODS THAT LOCK mProxyMutex! DO NOT CALL WHILE mProxyMutex IS LOCKED!
+	###########################################################################################*/
+	// Destructor, closes open connections. Do not call directly, use cleanupClass().
+	~LLProxy();
 
-	// METHODS THAT DO LOCK mProxyMutex! DO NOT CALL WHILE mProxyMutex IS LOCKED!
+	// Delete LLProxy singleton. Allows the apr_socket used in the SOCKS 5 control channel to be
+	// destroyed before the call to apr_terminate. Call from main thread only.
+	static void cleanupClass();
 
-	~LLProxy();
+	// Apply the current proxy settings to a curl request. Doesn't do anything if mHTTPProxyEnabled is false.
+	// Safe to call from any thread.
+	void applyProxySettings(CURL* handle);
+	void applyProxySettings(LLCurl::Easy* handle);
+	void applyProxySettings(LLCurlEasyRequest* handle);
 
-	// Start a connection to the SOCKS 5 proxy
+	// Start a connection to the SOCKS 5 proxy. Call from main thread only.
 	S32 startSOCKSProxy(LLHost host);
 
-	// Disconnect and clean up any connection to the SOCKS 5 proxy
+	// Disconnect and clean up any connection to the SOCKS 5 proxy. Call from main thread only.
 	void stopSOCKSProxy();
 
-	// Delete LLProxy singleton, destroying the APR pool used by the control channel.
-	static void cleanupClass();
-
-	// Set up to use Password auth when connecting to the SOCKS proxy
+	// Use Password auth when connecting to the SOCKS proxy. Call from main thread only.
 	bool setAuthPassword(const std::string &username, const std::string &password);
 
-	// Set up to use No Auth when connecting to the SOCKS proxy
+	// Disable authentication when connecting to the SOCKS proxy. Call from main thread only.
 	void setAuthNone();
 
-	// Get the currently selected auth method.
-	LLSocks5AuthType getSelectedAuthMethod() const;
-
-	// Proxy HTTP packets via httpHost, which can be a SOCKS 5 or a HTTP proxy
-	// as specified in type
+	// Proxy HTTP packets via httpHost, which can be a SOCKS 5 or a HTTP proxy.
+	// as specified in type. Call from main thread only.
 	bool enableHTTPProxy(LLHost httpHost, LLHttpProxyType type);
 	bool enableHTTPProxy();
 
-	// Stop proxying HTTP packets
+	// Stop proxying HTTP packets. Call from main thread only.
 	void disableHTTPProxy();
 
-	// Apply the current proxy settings to a curl request. Doesn't do anything if mHTTPProxyEnabled is false.
-	void applyProxySettings(CURL* handle);
-	void applyProxySettings(LLCurl::Easy* handle);
-	void applyProxySettings(LLCurlEasyRequest* handle);
+	/*###########################################################################################
+	END OF LOCKING METHODS
+	###########################################################################################*/
+private:
+	/*###########################################################################################
+	METHODS THAT LOCK mProxyMutex! DO NOT CALL WHILE mProxyMutex IS LOCKED!
+	###########################################################################################*/
 
-	// Get the HTTP proxy address and port
-	LLHost getHTTPProxy() const;
+	// Perform a SOCKS 5 authentication and UDP association with the proxy server.
+	S32 proxyHandshake(LLHost proxy);
+
+	// Get the currently selected auth method.
+	LLSocks5AuthType getSelectedAuthMethod() const;
 
 	// Get the currently selected HTTP proxy type
 	LLHttpProxyType getHTTPProxyType() const;
@@ -288,21 +295,21 @@ public:
 	std::string getSocksPwd() const;
 	std::string getSocksUser() const;
 
-	// END OF LOCKING METHODS
-private:
-	// Open a communication channel to the SOCKS 5 proxy proxy, at port messagePort
-	S32 proxyHandshake(LLHost proxy);
+	/*###########################################################################################
+	END OF LOCKING METHODS
+	###########################################################################################*/
 
 private:
-	// Is the HTTP proxy enabled?
-	// Safe to read in any thread, do not write directly,
-	// use enableHTTPProxy() and disableHTTPProxy() instead.
+	// Is the HTTP proxy enabled? Safe to read in any thread, but do not write directly.
+	// Instead use enableHTTPProxy() and disableHTTPProxy() instead.
 	mutable LLAtomic32<bool> mHTTPProxyEnabled;
 
-	// Mutex to protect shared members in non-main thread calls to applyProxySettings()
+	// Mutex to protect shared members in non-main thread calls to applyProxySettings().
 	mutable LLMutex mProxyMutex;
 
-	// MEMBERS READ AND WRITTEN ONLY IN THE MAIN THREAD. DO NOT SHARE!
+	/*###########################################################################################
+	MEMBERS READ AND WRITTEN ONLY IN THE MAIN THREAD. DO NOT SHARE!
+	###########################################################################################*/
 
 	// Is the UDP proxy enabled?
 	static bool sUDPProxyEnabled;
@@ -315,9 +322,13 @@ private:
 	// socket handle to proxy TCP control channel
 	LLSocket::ptr_t mProxyControlChannel;
 
-	// END OF UNSHARED MEMBERS
+	/*###########################################################################################
+	END OF UNSHARED MEMBERS
+	###########################################################################################*/
 
-	// MEMBERS WRITTEN IN MAIN THREAD AND READ IN ANY THREAD. ONLY READ OR WRITE AFTER LOCKING mProxyMutex!
+	/*###########################################################################################
+	MEMBERS WRITTEN IN MAIN THREAD AND READ IN ANY THREAD. ONLY READ OR WRITE AFTER LOCKING mProxyMutex!
+	###########################################################################################*/
 
 	// HTTP proxy address and port
 	LLHost mHTTPProxy;
@@ -325,7 +336,7 @@ private:
 	// Currently selected HTTP proxy type. Can be web or socks.
 	LLHttpProxyType mProxyType;
 
-	// SOCKS 5 auth method selected
+	// SOCKS 5 selected authentication method.
 	LLSocks5AuthType mAuthMethodSelected;
 
 	// SOCKS 5 username
@@ -333,7 +344,9 @@ private:
 	// SOCKS 5 password
 	std::string mSocksPassword;
 
-	// END OF SHARED MEMBERS
+	/*###########################################################################################
+	END OF SHARED MEMBERS
+	###########################################################################################*/
 };
 
 #endif