Class

NSConnection

An object that manages the communication between objects in different threads or between a thread and a process running on a local or remote system.

Declaration

@interface NSConnection : NSObject

Overview

Connection objects form the backbone of the distributed objects mechanism and normally operate in the background. You use the methods of NSConnection explicitly when vending an object to other applications, when accessing such a vended object through a proxy, and when altering default communication parameters. At other times, you simply interact with a vended object or its proxy.

A single connection object may be shared by multiple threads and used to access a vended object.

Topics

Getting the Default Instance

+ defaultConnection

Returns the default NSConnection object for the current thread.

Creating Instances

+ connectionWithReceivePort:sendPort:

Returns an NSConnection object that communicates using given send and receive ports.

- initWithReceivePort:sendPort:

Returns an NSConnection object initialized with given send and receive ports.

Running the Connection in a New Thread

- runInNewThread

Creates and starts a new NSThread object and then runs the receiving connection in the new thread.

- enableMultipleThreads

Configures the receiver to allow requests from multiple threads to the remote object, without requiring each thread to each maintain its own connection.

multipleThreadsEnabled

A Boolean value that indicates whether the receiver supports requests from multiple threads.

- addRunLoop:

Adds the specified run loop to the list of run loops the receiver monitors and from which it responds to requests.

- removeRunLoop:

Removes a given NSRunLoop object from the list of run loops the receiver monitors and from which it responds to requests.

Vending a Service

+ serviceConnectionWithName:rootObject:usingNameServer:

Creates and returns a new connection object representing a vended service on the specified port name server.

+ serviceConnectionWithName:rootObject:

Creates and returns a new connection object representing a vended service on the default system port name server.

- registerName:

Registers the specified service using with the default system port name server.

- registerName:withNameServer:

Registers a service with the specified port name server.

rootObject

The object that the receiver (or its parent) makes available to other applications or threads.

Getting a Remote Object

+ connectionWithRegisteredName:host:

Returns the NSConnection object whose send port links it to the NSConnection object registered with the default NSPortNameServer under a given name on a given host.

+ connectionWithRegisteredName:host:usingNameServer:

Returns the NSConnection object whose send port links it to the NSConnection object registered under a given name with a given server on a given host.

rootProxy

The proxy for the root object of the receiver’s peer in another application or thread.

+ rootProxyForConnectionWithRegisteredName:host:

Returns a proxy for the root object of the NSConnection object registered with the default NSPortNameServer under a given name on a given host.

+ rootProxyForConnectionWithRegisteredName:host:usingNameServer:

Returns a proxy for the root object of the NSConnection object registered with server under name on a given host.

remoteObjects

The local proxies for remote objects that have been received over the connection but not deallocated yet.

localObjects

The local objects that have been sent over the connection and still have proxies at the other end.

Getting a Conversation

+ currentConversation

Returns a token object representing any conversation in progress in the current thread.

Getting All NSConnection Objects

+ allConnections

Returns all valid NSConnection objects in the process.

Configuring Instances

requestTimeout

The timeout interval for outgoing remote messages.

replyTimeout

The timeout interval for replies to outgoing remote messages.

independentConversationQueueing

A Boolean value that indicates whether the receiver handles remote messages atomically.

- addRequestMode:

Adds mode to the set of run-loop input modes that the receiver uses for connection requests.

- removeRequestMode:

Removes mode from the set of run-loop input modes the receiver uses for connection requests.

requestModes

The set of request modes the receiver’s receive port is registered for with its NSRunLoop object.

- invalidate

Invalidates the receiver.

valid

A Boolean value that indicates whether the receiver is known to be valid.

Getting Ports

receivePort

The port on which the receiver receives incoming network messages.

sendPort

The port that the connection sends outgoing network messages through.

- dispatchWithComponents:

Allows subclasses to ask a connection object to dispatch component data.

Getting Statistics

statistics

A dictionary containing various statistics for the receiver.

Setting the Delegate

delegate

The receiver’s delegate.

Constants

NSConnection run loop mode

NSConnection defines the following run loop mode—see NSRunLoop for more details.

Connection Exception Names

The name of an exception raised in case of authentication failure.

Notifications

NSConnectionDidDieNotification

Posted when an NSConnection object is deallocated or when it’s notified that its NSPort object has become invalid. The notification object is the NSConnection object. This notification does not contain a userInfo dictionary.

NSConnectionDidInitializeNotification

Posted when an NSConnection object is initialized using initWithReceivePort:sendPort: (the designated initializer for NSConnection). The notification object is the NSConnection object. This notification does not contain a userInfo dictionary.

Relationships

Inherits From

NSObject