Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

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.

Establishing a Connection

+ (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.

Determining Connections

+ (NSArray *)allConnections	Returns an array describing all existing valid connections.

- (BOOL)isValid	Identifies that the receiver is a valid connection.

Registering a Connection

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

Assigning a Delegate

- (id)delegate	Returns the connection's delegate.

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

Getting and Setting the Root Object

- (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. 

Request Mode

- (NSString *)requestMode	Returns the mode in which requests are honored.

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

Conversation Queueing

-(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.

Get Statistics

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

Implemented by the Delegate

- (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.