NSConnection

Inherits From: NSObject

Conforms To: NSObject (NSObject)

Declared In: Foundation/NSConnection.h

Class Description

The NSConnection class declares the programmatic interface to objects that manage a connection such that objects in one thread can send messages to objects in another thread (typically, in another process, and it defines instances that manage each side of such a connection.

Each distinct thread of execution has one default connection defined. Any given thread can have as many connections as desired, but a given connection can be served by only one thread.

To set up a connection, some object in your application must be established as what is known as a root object and registered with a name in the Network Name Server. Such root objects can then be connected to by other threads, and can receive messages sent to them from other threads. An easy way to establish an object as a root object is to send the defaultConnection method to the NSConnection class object to obtain a connection object. Then use setRootObject: to establish the desired object as the object that will be registered, followed by registerName: to make that object available to the Network Name Server under the specified name.

To obtain a connection to an object registered elsewhere, you will generally send the rootProxyForConnectionWithRegisteredName:host: method to the NSConnection class object. This method returns a proxy to the remote object. You should then inform the proxy of the protocol(s) the remote object responds to using setProtocolForProxy:. To obtain the actual connection object instead of the proxy, use the connectionWithRegisteredName:host: method.

If the string @"*" is used where a hostname is required, it implies a lookup for any server registered with the specified name on the local subnet. If nil is supplied where a hostname is required, the name lookup occurs only on the local host.

When an NSConnection object is deallocated, the notification NSConnectionDeath is posted to the default notification center with that NSConnection object.

Exceptions

NSConnection can raise NSInternalInconsistencyException for a variety of reasons when it detects impossible situations. In addition, NSConnection can raise NSInvalidArgumentException when a remote method invocation sends an unknown selector.

Initializing a Connection

• - (id)init Initialize a newly allocated NSConnection suitable for a new registry and new name.

• + (NSConnection *)connectionWithRegisteredName:(NSString *)name host:(NSString *)hostName Registers and returns a connection with name on hostName.
• + (NSConnection *)defaultConnection Establishes and returns a default per-thread connection.
• + (NSDistantObject *)rootProxyForConnectionWithRegisteredName:(NSString *)name host:(NSString *)hostName Registers a connection with name on hostName and returns its root proxy.

• + (NSArray *)allConnections Returns an array describing all existing valid connections.
• - (BOOL)isValid Identifies that the receiver is a valid connection.

• - (BOOL)registerName:(NSString *)name Registers the connection with name on the local system and returns YES if the registration was successful, NO otherwise.

• - (id)delegate Returns the connection's delegate.
• - (void)setDelegate:(id)anObject Sets the connection's delegate.

• - (id)rootObject Returns the root object served.
• - (NSDistantObject *)rootProxy Returns an NSDistantObject proxy to the root object served by this connection.
• - (void)setRootObject:(id)anObject Sets the root object being served to anObject; if the root object already exists, replaces it with anObject. Be aware that if the root object is replaced while a connection is active, existing root proxies on the client side of the connection will continue to communicate with the previous root object, while new proxies will communicate with the newly established root object.

• - (NSString *)requestMode Returns the mode in which requests are honored.
• - (void)setRequestMode:(NSString *)mode Sets the mode in which requests are honored to mode.

-(BOOL)independentConversationQueueing Returns conversationQueuing mode. The default value is NO.

-(void)setIndependentConversationQueueing:(BOOL)flag

If flag is YES, unrelated requests are queued for later processing. This allows a server to use distributed objects freely in its implementation without concern for the consistency of its internal state. Note that this can cause deadlocks among peers.

Timeouts

• - (NSTimeInterval)replyTimeout Returns the reply timeout time interval.
• - (NSTimeInterval)requestTimeout Returns the request timeout time interval.
• - (void)setReplyTimeout:(NSTimeInterval)interval Sets the reply timeout to the time interval interval.
• - (void)setRequestTimeout:(NSTimeInterval)interval Sets the request timeout to the time interval interval.

• - (NSDictionary *)statistics Returns statistics for this connection.

• - (BOOL)makeNewConnection:(NSConnection *)connection sender:(NSConnection *)ancestor Asks permission to create a new connection connection where ancestor is the ancestral connection; returns YES if connection allowed.