NSConnection

NSConnection $Revision$ $Date$ NSConnection Foundation/NSConnection.h NSObject NSConnection objects are used to manage communications between objects in different processes, in different machines, or in different threads. allConnections Returns an array containing all the NSConnection objects known to the system. These connections will be valid at the time that the array was created, but may be invalidated by other threads before you get to examine the array. connectionWithReceivePort: receivePort Returns a connection created using initWithReceivePort:sendPort: connectionWithRegisteredName: name host: hostName

Returns an NSConnection object whose send port is that of the NSConnection registered under name on the host hostName.

This method calls connectionWithRegisteredName:host:usingNameServer: using the default system name server.

connectionWithRegisteredName: name host: host usingNameServer: server

Returns an NSConnection object whose send port is that of the NSConnection registered under name on host.

The nameserver server is used to look up the send port to be used for the connection.

If host is nil or an empty string, the host is taken to be the local machine. If it is an asterisk ('*') then the nameserver checks all hosts on the local subnet (unless the nameserver is one that only manages local ports). In the GNUstep implementation, the local host is searched before any other hosts.

If no NSConnection can be found for name and hosthost, the method returns nil.

The returned object has the default NSConnection of the current thread as its parent (it has the same receive port as the default connection).

currentConversation Not implemented defaultConnection Returns the default NSConnection for the current thread.
Creates a new instance if necessary.
The default connection has a single NSPort object used for both sending and receiving - this it can't be used to connect to a remote process, but can be used to vend objects. newRegisteringAtName: name withRootObject: anObject This used to be the preferred mechanism for creating a GNUstep server NSConnection ... it is now deprecated.
This is a convenience method for - NSConnection *conn; conn = [[NSConnection alloc] initWithReceivePort: [NSPort port] sendPort: nil]; [conn setRootObject: anObject]; if ([conn registerName: name] == NO) { DESTROY(conn); } return conn;

rootProxyForConnectionWithRegisteredName: name host: host This method calls rootProxyForConnectionWithRegisteredName:host:usingNameServer: to return a proxy for a root object on the remote connection with the send port registered under name on host rootProxyForConnectionWithRegisteredName: name host: host usingNameServer: server This method calls connectionWithRegisteredName:host:usingNameServer: to get a connection, then sends it a rootProxy message to get a proxy for the root object being vended by the remote connection. Returns the proxy or nil if it couldn't find a connection or if the root object for the connection has not been set.

addRequestMode: mode Adds mode to the run loop modes that the NSConnection will listen to for incoming messages. addRunLoop: loop Adds loop to the set of run loops that the NSConnection will listen to for incoming messages. delegate Returns the delegate of the NSConnection. enableMultipleThreads Sets the NSConnection configuration so that multiple threads may use the connection to send requests to the remote connection.
This option is inherited by child connections. independentConversationQueueing Returns YES if the NSConnection is configured to handle remote messages atomically, NO otherwise.
This option is inherited by child connections. initWithReceivePort: recv sendPort: send Initialises an NSConnection with recv and send.
Behavior varies with the port values as follows - recv is nil The NSConnection is released and the method returns nil. send is nil The NSConnection uses recv as the send port as well as the receive port. send is the same as recv The NSConnection is usable only for vending objects. A connection with the same ports exists The new connection is released and the old connection is retained and returned. A connection with the same ports (swapped) exists The new connection is initialised as normal, and will communicate with the old connection.

If a connection exists whose send and receive ports are both the same as the new connections receive port, that existing connection is deemed to be the parent of the new connection. The new connection inherits configuration information from the parent, and the delegate of the parent has a chance to adjust ythe configuration of the new connection or veto its creation.
NSConnectionDidInitializeNotification is posted once a new connection is initialised.

invalidate Marks the receiving NSConnection as invalid.
Removes the NSConnections ports from any run loops.
Posts an NSConnectionDidDieNotification.
Invalidates all remote objects and local proxies. isValid Returns YES if the connection is invalid, NO otherwise. localObjects Returns an array of all the local proxies to objects that are retained by the remote connection. multipleThreadsEnabled Returns YES if the connection permits multiple threads to use it to send requests, NO otherwise. receivePort Returns the NSPort object on which incoming messages are recieved. registerName: name Simply invokes registerName:usingNameServer: passing it the default system nameserver. registerName: name withNameServer: server Registers the recieve port of the NSConnection as name and unregisters the previous name (if any).
Returns YES on success, NO on failure.
On failure, the connection remains registered under the previous name.
Supply nil as name to unregister the NSConnection.

remoteObjects Returns an array of proxies to all the remote objects known to the NSConnection. removeRequestMode: mode Removes mode from the run loop modes used to recieve incoming messages. removeRunLoop: loop Removes loop from the run loops used to recieve incoming messages. replyTimeout Returns the timeout interval used when waiting for a reply to a request sent on the NSConnection. This value is inherited from the parent connection or may be set using the setReplyTimeout: method. The default value is the maximum delay (effectively infinite). requestModes Returns an array of all the run loop modes that the NSConnection uses when waiting for an incoming request. requestTimeout Returns the timeout interval used when waiting for a send operation to complete. This value is inherited from the parent connection or may be set using the setRequestTimeout: method. The default value is the maximum delay (effectively infinite). rootObject Returns the object that is made available by this connection or by its parent (the object is associated with the receive port).
Returns nil if no root object has been set. rootProxy Returns the proxy for the root object of the remote NSConnection. runInNewThread Removes the NSConnection from the current threads default run loop, then creates a new thread and runs the NSConnection in it. sendPort Returns the port on which the NSConnection sends messages. setDelegate: delegate Sets the NSConnection's delegate (without retaining it).
The delegate is able to control some of the NSConnection's behavior by implementing methods in an informal protocol. setIndependentConversationQueueing: flag Sets whether or not the NSConnection should handle requests arriving from the remote NSConnection atomically.
By default, this is set to NO ... if set to YES then any messages arriving while one message is being dealt with, will be queued.
NB. careful - use of this option can cause deadlocks. setReplyTimeout: seconds Sets the time interval that the NSConnection will wait for a reply to one of its requests before raising an NSPortTimeoutException. setRequestTimeout: seconds Sets the time interval that the NSConnection will wait to send one of its requests before raising an NSPortTimeoutException. setRootObject: anObject Sets the root object that is vended by the connection. statistics Returns an object containing various statistics for the NSConnection.
On GNUstep the dictionary contains - NSConnectionRepliesReceived The number of messages replied to by the remote NSConnection NSConnectionRepliesSent The number of replies sent to the remote NSConnection NSConnectionRequestsReceived The number of messages recieved from the remote NSConnection NSConnectionRequestsSent The number of messages sent to the remote NSConnection NSConnectionLocalCount The number of local objects currently vended NSConnectionProxyCount The number of remote objects currently in use authenticateComponents: components withData: authentication

This is not an NSConnection method, but is a method that may be implemented by the delegate of an NSConnection object.

If the delegate implements this method, the NSConnection will invoke the method for every message request or reply it receives from the remote NSConnection. The delegate should use the authentication data to check all the NSData objects in the components array (ignoring NSPort objects), and return YES if they are valid, NO otherwise.

If the method returns NO then an NSFailedAuthentication exception will be raised.

In GNUstep the components array is mutable, allowing you to replace the NSData objects with your own version.

authenticationDataForComponents: components

This is not an NSConnection method, but is a method that may be implemented by the delegate of an NSConnection object.

If the delegate implements this method, the NSConnection will invoke the method for every message request ro reply it sends to the remote NSConnection. The delegate should generate authentication data by examining all the NSData objects in the components array (ignoring NSPort objects), and return the authentication data that can be used by the remote NSConnection.

If the method returns nil then an NSGenericException exception will be raised.

In GNUstep the components array is mutable, allowing you to replace the NSData objects with your own version.

connection: parentConnection shouldMakeNewConnection: newConnnection

This is not an NSConnection method, but is a method that may be implemented by the delegate of an NSConnection object.

If the delegate implements this method, it will be called whenever a new NSConnection is created that has this NSConnection as its parent. The delegate may take this opportunity to adjust the configuration of the new connection and may return a boolean value to tell the parent whether the creation of the new connection is to be permitted or not.

makeNewConnection: newConnection

This is not an NSConnection method, but is a method that may be implemented by the delegate of an NSConnection object.

This is the old equivalent of connection:shouldMakeNewConnection and its use is now deprecated.