Added socks5 support for outgoing connections.

git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@13846 72102866-910b-0410-8b05-ffd578937521

ChangeLog

@@ -3,6 +3,11 @@
 	* Source/NSObject.m: Fix a few errors which crept in to the map
 	table based reference counting.
 	* Examples/GNUmakefile: Permit local makefile to be missing.
+	* Source/UnixFileHandle.m: Added outgoing SOCKS5 support.
+	* Source/NSFileHandle.m: Added SOCKS5 documentation.
+	* Source/Base/gsdoc: Dopcumented SOCKS enironemnet variables and defs.
+	* Source/NSNotification.m: Made -description more informative.
+	* Testing/call.m: Trivial test program for tcp connections.
 
 2002-06-10  Richard Frith-Macdonald <rfm@gnu.org>
 

Headers/gnustep/base/UnixFileHandle.h

@@ -48,7 +48,7 @@
   BOOL			readOK;
   BOOL			writeOK;
   NSMutableDictionary	*readInfo;
-  int			readPos;
+  int			readMax;
   NSMutableArray	*writeInfo;
   int			writePos;
   NSString		*address;

Source/Base.gsdoc

@@ -96,6 +96,17 @@
 		should cope with both cases anyway.
 	      </p>
 	    </desc>
+	    <term>GSSOCKS</term>
+	    <desc>
+	      <p>
+		May be used to specify a default SOCKS5 server (and optionally
+		a port separated from the server by a colon) to which tcp/ip
+	        connections made using the NSFileHandle extension methods
+		should be directed.<br />
+		This default overrides the SOCKS5_SERVER and SOCKS_SERVER
+		environment variables.
+	      </p>
+	    </desc>
 	    <term>NSWriteOldStylePropertyLists</term>
 	    <desc>
 	      <p>
@@ -305,6 +316,25 @@
 		allocated for objects will be leaked!
 	      </p>
 	    </desc>
+	    <term>SOCKS5_SERVER</term>
+	    <desc>
+	      <p>
+		Specifies the default socks server to be used when making
+		outgoing tcp/ip connections using NSFileHandle.  This may
+		also specify a port after the host name (and spearated
+		from it by a colon).<br />
+		This environment variable is used only if the GSSOCKS
+		user default is not set.
+	      </p>
+	    </desc>
+	    <term>SOCKS_SERVER</term>
+	    <desc>
+	      <p>
+		Equivalent to SOCKS5_SERVER, but used only if that is not
+		defined.
+	      </p>
+	    </desc>
+
 	    <term>TZ</term>
 	    <desc>
 	      <p>

Source/NSFileHandle.m

@@ -309,6 +309,12 @@ NSString * const NSFileHandleOperationException
 
 @implementation NSFileHandle (GNUstepExtensions)
 
+/**
+ * Opens an outgoing network connection by initiating an asynchronous
+ * connection (see
+ * [+fileHandleAsClientInBackgroundAtAddress:service:protocol:forModes:])
+ * and waiting for it to succeed, fail, or time out.
+ */
 + (id) fileHandleAsClientAtAddress: (NSString*)address
 			   service: (NSString*)service
 			  protocol: (NSString*)protocol
@@ -320,6 +326,10 @@ NSString * const NSFileHandleOperationException
 				     protocol: protocol]);
 }
 
+/**
+ * Opens an outgoing network connection asynchronously using
+ * [+fileHandleAsClientInBackgroundAtAddress:service:protocol:forModes:]
+ */
 + (id) fileHandleAsClientInBackgroundAtAddress: (NSString*)address
 				       service: (NSString*)service
 				      protocol: (NSString*)protocol
@@ -332,6 +342,44 @@ NSString * const NSFileHandleOperationException
 						 forModes: nil]);
 }
 
+/**
+ * <p>
+ *   Opens an outgoing network connection asynchronously.
+ * </p>
+ * <list>
+ *   <item>
+ *     The address is the name (or IP dotted quad) of the machine to
+ *     which the connection should be made.
+ *   </item>
+ *   <item>
+ *     The service is the name (or number) of the port to
+ *     which the connection should be made.
+ *   </item>
+ *   <item>
+ *     The protocol is provided so support different network protocols,
+ *     but at present only 'tcp' is supported.  However, a protocol
+ *     specification of the form 'socks-...' can be used to control socks5
+ *     support.<br />
+ *     If '...' is empty (ie the string is just 'socks-' then the connection
+ *     is <em>not</em> made via a socks server.<br />
+ *     Otherwise, the text '...' must be the name of the host on which the
+ *     socks5 server is running, with an optional port number separated
+ *     from the host name by a colon.
+ *   </item>
+ *   <item>
+ *     If modes is nil or empty, uses NSDefaultRunLoopMode.
+ *   </item>
+ * </list>
+ * <p>
+ *   This method supports connection through a firewall via socks5.  The
+ *   socks5 connection may be controlled via the protocol argument, but if
+ *   no socks infromation is supplied here, the <em>GSSOCKS</em> user default
+ *   will be used, and failing that, the <em>SOCKS5_SERVER</em> or
+ *   <em>SOCKS_SERVER</em> environment variables will be used to set the
+ *   socks server.  If none of these mechanisms specify a socks server, the
+ *   connection will be made directly rather than through socks.
+ * </p>
+ */
 + (id) fileHandleAsClientInBackgroundAtAddress: (NSString*)address
 				       service: (NSString*)service
 				      protocol: (NSString*)protocol

Source/NSNotification.m

@@ -47,16 +47,6 @@
 
 @implementation NSNotification
 
-- (void) dealloc
-{
-  RELEASE(_name);
-  TEST_RELEASE(_object);
-  TEST_RELEASE(_info);
-  [super dealloc];
-}
-
-
-/* Creating autoreleased Notification objects. */
 
 + (NSNotification*) notificationWithName: (NSString*)name
 				  object: (id)object
@@ -72,8 +62,31 @@
   return [self notificationWithName: name object: object userInfo: nil];
 }
 
-
-/* Querying a Notification object. */
+
+- (id) copyWithZone: (NSZone*)zone
+{
+  if (NSShouldRetainWithZone (self, zone))
+    {
+      return [self retain];
+    }
+  return [[[self class] allocWithZone: zone] initWithName: _name
+						   object: _object
+						 userInfo: _info];
+}
+
+- (void) dealloc
+{
+  RELEASE(_name);
+  TEST_RELEASE(_object);
+  TEST_RELEASE(_info);
+  [super dealloc];
+}
+
+- (NSString*) description
+{
+  return [[super description] stringByAppendingFormat:
+    @" Name: %@ Object: %@ Info: %@", _name, _object, _info];
+}
 
 - (NSString*) name
 {
@@ -90,20 +103,6 @@
   return _info;
 }
 
-
-/* NSCopying protocol. */
-
-- (id) copyWithZone: (NSZone*)zone
-{
-  if (NSShouldRetainWithZone (self, zone))
-    return [self retain];
-
-  return [[[self class] allocWithZone: zone]
-    initWithName: _name
-	  object: _object
-	userInfo: _info];
-}
-
 /*
  * NSCoding protocol - the MacOS-X documentation says it should conform,
  * but how can we meaningfully encode/decode the object and userInfo.