Up

# NSConnection class reference

### Authors

Andrew Kachites McCallum (`mccallum@gnu.ai.mit.edu`)
Richard Frith-Macdonald (`rfm@gnu.org`)

Date: Generated at 2025-02-13 06:02:40 +0000

Copyright: (C) 1994-2017 Free Software Foundation, Inc.

### Contents -

1. Software documentation for the NSConnection class
2. Software documentation for the NSObject(NSConnectionDelegate) informal protocol

# Software documentation for the NSConnection class

## NSConnection : NSObject

> Declared in:
>   Foundation/NSConnection.h

Availability: OpenStep
NSConnection objects are used to manage communications between objects in different processes, in different machines, or in different threads.
Method summary

- +allConnections
- +connectionWithReceivePort:sendPort:
- +connectionWithRegisteredName:host:
- +connectionWithRegisteredName:host:usingNameServer:
- +currentConversation
- +defaultConnection
- +rootProxyForConnectionWithRegisteredName:host:
- +rootProxyForConnectionWithRegisteredName:host:usingNameServer:
- +serviceConnectionWithName:rootObject:
- +serviceConnectionWithName:rootObject:usingNameServer:
- -addRequestMode:
- -addRunLoop:
- -delegate
- -enableMultipleThreads
- -independentConversationQueueing
- -initWithReceivePort:sendPort:
- -invalidate
- -isValid
- -localObjects
- -multipleThreadsEnabled
- -receivePort
- -registerName:
- -registerName:withNameServer:
- -remoteObjects
- -removeRequestMode:
- -removeRunLoop:
- -replyTimeout
- -requestModes
- -requestTimeout
- -rootObject
- -rootProxy
- -runInNewThread
- -sendPort
- -setDelegate:
- -setIndependentConversationQueueing:
- -setReplyTimeout:
- -setRequestMode:
- -setRequestTimeout:
- -setRootObject:
- -statistics

### allConnections

+ (NSArray*) allConnections;
Availability: OpenStep
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: sendPort:

+ (NSConnection*) connectionWithReceivePort: (NSPort*)r sendPort: (NSPort*)s;
Availability: OpenStep
Returns a connection initialised using -initWithReceivePort:sendPort:
Both ports must be of the same type.

### connectionWithRegisteredName: host:

+ (NSConnection*) connectionWithRegisteredName: (NSString*)n host: (NSString*)h;
Availability: OpenStep

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

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

Use NSSocketPortNameServer for connections to remote hosts.

### connectionWithRegisteredName: host: usingNameServer:

+ (NSConnection*) connectionWithRegisteredName: (NSString*)n host: (NSString*)h usingNameServer: (NSPortNameServer*)s;
Availability: OpenStep

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.
Use [NSSocketPortNameServer +sharedInstance] for connections to remote hosts.

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.
NB. if the nameserver does not support connections to remote hosts (the default situation) the host argeument should be omitted.

If no NSConnection can be found for name and host host, 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

+ (id) currentConversation;
Availability: OpenStep
Return the current conversation... not implemented in GNUstep

### defaultConnection

+ (NSConnection*) defaultConnection;
Availability: OpenStep
Returns the default connection for a 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.
Possible problem - if the connection is invalidated, it won't be cleaned up until this thread calls this method again. The connection and it's ports could hang around for a very long time.

### rootProxyForConnectionWithRegisteredName: host:

+ (NSDistantObject*) rootProxyForConnectionWithRegisteredName: (NSString*)n host: (NSString*)h;
Availability: OpenStep
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 n on host h.

### rootProxyForConnectionWithRegisteredName: host: usingNameServer:

+ (NSDistantObject*) rootProxyForConnectionWithRegisteredName: (NSString*)n host: (NSString*)h usingNameServer: (NSPortNameServer*)s;
Availability: OpenStep
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.
Use [NSSocketPortNameServer +sharedInstance] for connections to remote hosts.

### serviceConnectionWithName: rootObject:

+ (id) serviceConnectionWithName: (NSString*)name rootObject: (id)root;
Availability: MacOS-X 10.5.0
Description forthcoming.

### serviceConnectionWithName: rootObject: usingNameServer:

+ (id) serviceConnectionWithName: (NSString*)name rootObject: (id)root usingNameServer: (NSPortNameServer*)server;
Availability: MacOS-X 10.5.0
Description forthcoming.

### addRequestMode:

- (void) addRequestMode: (NSString*)mode;
Availability: OpenStep
Adds mode to the run loop modes that the NSConnection will listen to for incoming messages.

### addRunLoop:

- (void) addRunLoop: (NSRunLoop*)loop;
Availability: OpenStep
Adds loop to the set of run loops that the NSConnection will listen to for incoming messages.

### delegate

- (id) delegate;
Availability: OpenStep
Returns the delegate of the NSConnection.

### enableMultipleThreads

- (void) enableMultipleThreads;
Availability: OpenStep
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.
NB. A connection with multiple threads enabled will run slower than a normal connection.

### independentConversationQueueing

- (BOOL) independentConversationQueueing;
Availability: OpenStep
Returns `YES` if the NSConnection is configured to handle remote messages atomically, `NO` otherwise.
This option is inherited by child connections.

### initWithReceivePort: sendPort:

- (id) initWithReceivePort: (NSPort*)r sendPort: (NSPort*)s;
Availability: OpenStep
This is a designated initialiser for the class.
Initialises an NSConnection with the receive port r and the send port s.
Behavior varies with the port values as follows -

r is `nil`
  The NSConnection is released and the method returns `nil`.
s is `nil`
  The NSConnection uses r as the send port as well as the receive port.
s is the same as r
  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 the configuration of the new connection or veto its creation.
NSConnectionDidInitializeNotification is posted once a new connection is initialised.

### invalidate

- (void) invalidate;
Availability: OpenStep
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

- (BOOL) isValid;
Availability: OpenStep
Returns `YES` if the connection is valid, `NO` otherwise. A connection is valid until it has been sent an -invalidate message.

### localObjects

- (NSArray*) localObjects;
Availability: OpenStep
Returns an array of all the local objects that have proxies at the remote end of the connection because they have been sent over the connection and not yet released by the far end.

### multipleThreadsEnabled

- (BOOL) multipleThreadsEnabled;
Availability: OpenStep
Returns `YES` if the connection permits multiple threads to use it to send requests, `NO` otherwise.
See the -enableMultipleThreads method.

### receivePort

- (NSPort*) receivePort;
Availability: OpenStep
Returns the NSPort object on which incoming messages are received.

### registerName:

- (BOOL) registerName: (NSString*)name;
Availability: OpenStep
Simply invokes -registerName:withNameServer: passing it the default system nameserver.

### registerName: withNameServer:

- (BOOL) registerName: (NSString*)name withNameServer: (NSPortNameServer*)svr;
Availability: OpenStep
Registers the receive port of the NSConnection as name and unregisters the previous value (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

- (NSArray*) remoteObjects;
Availability: OpenStep
Returns an array of proxies to all the remote objects known to the NSConnection.

### removeRequestMode:

- (void) removeRequestMode: (NSString*)mode;
Availability: OpenStep
Removes mode from the run loop modes used to receive incoming messages.

### removeRunLoop:

- (void) removeRunLoop: (NSRunLoop*)loop;
Availability: OpenStep
Removes loop from the run loops used to receive incoming messages.

### replyTimeout

- (NSTimeInterval) replyTimeout;
Availability: OpenStep
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

- (NSArray*) requestModes;
Availability: OpenStep
Returns an array of all the run loop modes that the NSConnection uses when waiting for an incoming request.

### requestTimeout

- (NSTimeInterval) requestTimeout;
Availability: OpenStep
Returns the timeout interval used when trying to send a request on the NSConnection. 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

- (id) rootObject;
Availability: OpenStep
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

- (NSDistantObject*) rootProxy;
Availability: OpenStep
Returns the proxy for the root object of the remote NSConnection.
Generally you will wish to call [NSDistantObject -setProtocolForProxy:] immediately after obtaining such a root proxy.

### runInNewThread

- (void) runInNewThread;
Availability: OpenStep
Removes the NSConnection from the current threads default run loop, then creates a new thread and runs the NSConnection in it.

### sendPort

- (NSPort*) sendPort;
Availability: OpenStep
Returns the port on which the NSConnection sends messages.

### setDelegate:

- (void) setDelegate: (id)anObj;
Availability: OpenStep
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:

- (void) setIndependentConversationQueueing: (BOOL)flag;
Availability: OpenStep
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:

- (void) setReplyTimeout: (NSTimeInterval)to;
Availability: OpenStep
Sets the time interval that the NSConnection will wait for a reply for one of its requests before raising an NSPortTimeoutException.
NB. In GNUstep you may also get such an exception if the connection becomes invalidated while waiting for a reply to a request.

### setRequestMode:

- (void) setRequestMode: (NSString*)mode;
Availability: OpenStep
Sets the runloop mode in which requests will be sent to the remote end of the connection. Normally this is NSDefaultRunloopMode

### setRequestTimeout:

- (void) setRequestTimeout: (NSTimeInterval)to;
Availability: OpenStep
Sets the time interval that the NSConnection will wait to send one of its requests before raising an NSPortTimeoutException.

### setRootObject:

- (void) setRootObject: (id)anObj;
Availability: OpenStep
Sets the root object that is vended by the connection.

### statistics

- (NSDictionary*) statistics;
Availability: OpenStep
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 received 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.

# Software documentation for the NSObject(NSConnectionDelegate) informal protocol

## NSObject(NSConnectionDelegate)

> Declared in:
>   Foundation/NSConnection.h

Availability: OpenStep
This category represents an informal protocol to which NSConnection delegates may conform... These methods are not actually implemented by NSObject, so implementing these methods in your class has the effect documented.
Method summary

- -authenticateComponents:withData:
- -authenticationDataForComponents:
- -connection:didConnect:
- -connection:shouldMakeNewConnection:
- -makeNewConnection:sender:

### authenticateComponents: withData:

- (BOOL) authenticateComponents: (NSMutableArray*)components withData: (NSData*)authenticationData;
Availability: OpenStep

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:

- (NSData*) authenticationDataForComponents: (NSMutableArray*)components;
Availability: OpenStep

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 to 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: didConnect:

- (NSConnection*) connection: (NSConnection*)ancestorConn didConnect: (NSConnection*)newConn;
Availability: OpenStep
Description forthcoming.

### connection: shouldMakeNewConnection:

- (BOOL) connection: (NSConnection*)parent shouldMakeNewConnection: (NSConnection*)newConnection;
Availability: OpenStep

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: sender:

- (BOOL) makeNewConnection: (NSConnection*)newConnection sender: (NSConnection*)parent;
Availability: OpenStep
An old fashioned synonym for -connection:shouldMakeNewConnection: - don't use this.

Up