update for current api

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

ChangeLog

@@ -1,3 +1,7 @@
+2006-10-19  Richard Frith-Macdonald <rfm@gnu.org>
+
+        * Documentation/manual/DistributedObjects.texi: Update for current API
+
 2006-10-19  Matt Rice  <ratmice@yahoo.com>
 	
 	* Source/NSBundle.m (_find_framework): initialize file_name variable.

Documentation/manual/DistributedObjects.texi

@@ -177,9 +177,7 @@ at the server.
 
   /* Get the proxy */
   id proxy = [NSConnection
-                rootProxyForConnectionWithRegisteredName:
-	          @i{registeredServerName}
-	        host: @i{hostName}]; 
+    rootProxyForConnectionWithRegisteredName: @i{registeredServerName}];
 	
   /* The rest of your program code goes here */
 
@@ -189,8 +187,81 @@ at the server.
 
 The code that obtains the proxy automatically creates an NSConnection
 object for managing the inter-process communication, so there is no need
-to create one yourself. If the @i{hostName} in this statement is 'nil',
-then only the local host will be searched to find the
+to create one yourself.
+
+The above example serves to establish a secure connection between processes
+which are run by the same person and are both on the same host.
+
+If you want your connections to work between different host or between
+programs being run by different people, you do this slightly differently,
+telling the system that you want to use 'socket' ports, which make TCP/IP
+connections over the network.
+
+@example
+int main(void)
+@{
+  CREATE_AUTORELEASE_POOL(pool);
+
+  /*
+   * Create a new socket port for your connection.
+   */
+  NSSocketPort *port = [NSSocketPort port];
+
+  /*
+   * Create a connection using the socket port.
+   */
+  NSConnection *connXion = [NSConnection connectionWithReceivePort: port
+							  sendPort: port];
+
+  /*
+   * Set the responding server object as
+   * the root object for this connection.
+   */
+  [connXion setRootObject: telephoneDirectory];
+
+  /*
+   * Try to register a name for the NSConnection,
+   * and report an error if this is not possible.
+   */
+  if ([connXion registerName: @@"DirectoryServer"
+    withNameServer: [NSSocketPortNameServer sharedInstance]] == NO)
+  @{
+    NSLog(@@"Unable to register as 'DirectoryServer'");
+    NSLog(@@"Perhaps another copy of this program is running?");
+    exit(1);
+  @}
+
+  [[NSRunLoop currentRunLoop] run];
+
+  RELEASE(pool);
+  return 0;
+@}
+@end example
+
+In the above example, we specify that the socket port name server is used
+to register the name for the connection ... this makes the connection name
+visible to processes running on other machines.
+
+The client side code is as follows
+
+@example
+  /* Create an instance of the NSAutoreleasePool class */
+  CREATE_AUTORELEASE_POOL(pool);
+
+  /* Get the proxy */
+  id proxy = [NSConnection
+    rootProxyForConnectionWithRegisteredName: @i{registeredServerName}
+    host: @i{hostName}
+    usingNameServer: [NSSocketPortNameServer sharedInstance]];
+	
+  /* The rest of your program code goes here */
+
+  /* Release the pool */
+  RELEASE(pool);
+@end example
+
+If the @i{hostName} in this statement is 'nil'
+or an empty string, then only the local host will be searched to find the
 @i{registeredServerName}. If @i{hostName} is "*", then all hosts on the
 local network will be searched.
 
@@ -199,9 +270,9 @@ any host on the network would be:
 
 @example
   id proxyForDirectory = [NSConnection
-                            rootProxyForConnectionWithRegisteredName: 
-                              @@"DirectoryServer" 
-			    host: "*"]; 
+    rootProxyForConnectionWithRegisteredName: @@"DirectoryServer"
+    host: @@"*"
+    usingNameServer: [NSSocketPortNameServer sharedInstance]];
 @end example
 
 With this additional line of code in the client program, you can now
@@ -252,9 +323,8 @@ In the telephone directory example, if the declared protocol was
 
   /* Cast the returned proxy object to the extended type */
   proxyForDirectory = (id<TelephoneDirectory>) [NSConnection
-                       rootProxyForConnectionWithRegisteredName: 
-                       @@"DirectoryServer" 
-		       host: "*"]; 
+    rootProxyForConnectionWithRegisteredName: @@"DirectoryServer"
+    usingNameServer: [NSSocketPortNameServer sharedInstance]];
 @end example
 Since class names and protocol names do not share the same 'address
 space' in a process, the declared protocol and the class of the
@@ -325,9 +395,9 @@ int main(int argc, char *argv[])
 
   /* Acquire the remote reference. */
   proxyForDirectory = (id<TelephoneDirectory>) [NSConnection
-                       rootProxyForConnectionWithRegisteredName: 
-                       @@"DirectoryServer" 
-		       host: @@"*"];	       
+    rootProxyForConnectionWithRegisteredName: @@"DirectoryServer"
+    host: @@"*"
+    usingNameServer: [NSSocketPortNameServer sharedInstance]];
 
   if (proxyForDirectory == nil)
     printf("\n** WARNING: NO CONNECTION TO SERVER **\n");
@@ -361,7 +431,14 @@ you display a "No Server Connection" warning at the client?
 @cindex Distributed Objects Name Server, GNUstep
 
 You might wonder how the client finds the server, or, rather, how it finds the
-directory the server lists itself in.  In fact an auxiliary process will
+directory the server lists itself in.
+
+For the default connection type (a connection only usable on the local host
+between processes run by the same person), a private file (or the registry
+on ms-windows) is used to hold the name registration information.
+
+For connections using socket ports to communicate between hosts,
+an auxiliary process will
 automatically be started on each machine, if it isn't running already, that
 handles this, allowing the server to register and the client to send a query
 behind the scenes.  This @i{GNUstep Distributed Objects Name Server} runs as
@@ -539,8 +616,9 @@ int main(int argc, char **argv)
    * is '*', we can connect to any server on the local network.
    */
   server = (id<GameServer>)[NSConnection
-                            rootProxyForConnectionWithRegisteredName: 
-                            @@"JoinGame" host: @@"*"];
+    rootProxyForConnectionWithRegisteredName: @@"JoinGame"
+    host: @@"*"
+    usingNameServer: [NSSocketPortNameServer sharedInstance]];
   if (server == nil)
     @{
       printf("\n** No Connection to GameServer **\n");
@@ -807,12 +885,15 @@ int main(int argc, char** argv)
 @{
   CREATE_AUTORELEASE_POOL(pool);
   GameServer	*server;
+  NSSocketPort	*port;
   NSConnection	*connXion;
 
   server = AUTORELEASE([GameServer new]);
-  connXion = [NSConnection defaultConnection];
+  port = [NSSocketPort port];
+  connXion = [NSConnection connectionWithReceivePort: port sendPort: port];
   [connXion setRootObject: server];
-  [connXion registerName: @@"JoinGame"];
+  [connXion registerName: @@"JoinGame"
+    withNameServer: [NSSocketPortNameServer sharedInstance]];
   [[NSRunLoop currentRunLoop] run];
   RELEASE(pool);
   return 0;