NSConnection Class Reference

Inherits from
NSObject
Conforms to
NSObject (NSObject)
Framework
/System/Library/Frameworks/Foundation.framework
Availability
Available in OS X v10.0 and later.
Companion guide
Distributed Objects Programming Topics
Declared in
NSConnection.h
Related sample code

Overview

An NSConnection object manages the communication between objects in different threads or between a thread and a process running on a local or remote system. 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.

Tasks

Getting the Default Instance

Creating Instances

Running the Connection in a New Thread

Vending a Service

Getting a Remote Object

Getting a Conversation

Getting All NSConnection Objects

Configuring Instances

Getting Ports

Getting Statistics

Setting the Delegate

Class Methods

allConnections

Returns all valid NSConnection objects in the process.

+ (NSArray *)allConnections
Return Value

An array containing all valid NSConnection objects in the process.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

connectionWithReceivePort:sendPort:

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

+ (id)connectionWithReceivePort:(NSPort *)receivePort sendPort:(NSPort *)sendPort
Parameters
receivePort

A receive port.

sendPort

A send port.

Return Value

An NSConnection object that communicates using receivePort and sendPort.

Discussion

See initWithReceivePort:sendPort: for more information.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

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.

+ (id)connectionWithRegisteredName:(NSString *)name host:(NSString *)hostName
Parameters
name

The name of an NSConnection object.

hostName

The name of the host. The domain name hostName is an Internet domain name (for example, “sales.anycorp.com”). If hostName is nil or empty, then only the local host is searched for the named NSConnection object.

Return Value

The NSConnection object whose send port links it to the NSConnection object registered with the default NSPortNameServer under name on the host named hostName. Returns nil if no NSConnection object can be found for name and hostName.

The returned NSConnection object is a child of the default NSConnection object for the current thread (that is, it shares the default NSConnection object's receive port).

Discussion

To get the object vended by the NSConnection object, use the rootProxy instance method. The rootProxyForConnectionWithRegisteredName:host: class method immediately returns this object.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSConnection.h

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.

+ (id)connectionWithRegisteredName:(NSString *)name host:(NSString *)hostName usingNameServer:(NSPortNameServer *)server
Parameters
name

The connection name.

hostName

The host name.

server

The name server.

Return Value

The NSConnection object whose send port links it to the NSConnection object registered with server under name on the host named hostName.

Discussion

See connectionWithRegisteredName:host: for more information.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSConnection.h

currentConversation

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

+ (id)currentConversation
Return Value

A token object representing any conversation in progress in the current thread, or nil if there is no conversation in progress.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

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.

+ (NSDistantObject *)rootProxyForConnectionWithRegisteredName:(NSString *)name host:(NSString *)hostName
Parameters
name

The name under which the connection is registered.

hostName

The host name. The domain name hostName is an Internet domain name (for example, "sales.anycorp.com"). If hostName is nil or empty, then only the local host is searched for the named NSConnection object.

Return Value

a proxy for the root object of the NSConnection object registered with the default NSPortNameServer under name on the host named hostName, or nil if that NSConnection object has no root object set. Also returns nil if no NSConnection object can be found for name and hostName.

Discussion

The NSConnection object of the returned proxy is a child of the default NSConnection object for the current thread (that is, it shares the default NSConnection object's receive port).

This method invokes connectionWithRegisteredName:host: and sends the resulting NSConnection object a rootProxy message.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

rootProxyForConnectionWithRegisteredName:host:usingNameServer:

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

+ (NSDistantObject *)rootProxyForConnectionWithRegisteredName:(NSString *)name host:(NSString *)hostName usingNameServer:(NSPortNameServer *)server
Parameters
name

The name of an NSConnection object .

hostName

A host name.

server

The server.

Return Value

A proxy for the root object of the NSConnection object registered with server under name on the host named hostName, or nil if that NSConnection object has no root object set.

Discussion

See rootProxyForConnectionWithRegisteredName:host: for more information.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSConnection.h

serviceConnectionWithName:rootObject:

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

+ (id)serviceConnectionWithName:(NSString *)name rootObject:(id)root
Parameters
name

The name of the service you want to publish.

root

The object to use as the root object for the published service. This is the object vended by the connection.

Return Value

An NSConnection object representing the vended service or nil if there was a problem setting up the connection object.

Discussion

This method creates the server-side of a connection object and registers it with the default system port name server. Clients wishing to connect to this service can request a communications port from the same port server and use that port to to communicate.

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSConnection.h

serviceConnectionWithName:rootObject:usingNameServer:

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

+ (id)serviceConnectionWithName:(NSString *)name rootObject:(id)root usingNameServer:(NSPortNameServer *)server
Parameters
name

The name of the service you want to publish.

root

The object to use as the root object for the published service. This is the object vended by the connection.

server

The port name server with which to register your service.

Return Value

An NSConnection object representing the vended service or nil if there was a problem setting up the connection object.

Discussion

This method creates the server-side of a connection object and registers it with the specified port name server. Clients wishing to connect to this service can request a communications port from the same port server and use that port to communicate.

If the specified service name corresponds to a service that is autolaunched by launchd, this method allows the service to check in with the launchd process. If the service is not autolaunched by launchd, this method registers the new connection with the specified name. For more information about launchd and its role in launching services, see Daemons and Services Programming Guide

Availability
  • Available in OS X v10.5 and later.
See Also
Declared In
NSConnection.h

Instance Methods

addRequestMode:

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

- (void)addRequestMode:(NSString *)mode
Parameters
mode

The mode to add to the receiver.

Discussion

The default input mode is NSDefaultRunLoopMode. See the NSRunLoop class specification for more information on input modes.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

addRunLoop:

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

- (void)addRunLoop:(NSRunLoop *)runloop
Parameters
runloop

The run loop to add to the receiver.

Discussion

This method is invoked automatically when a request comes in from a new run loop if enableMultipleThreads has been set.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

delegate

Returns the receiver’s delegate.

- (id < NSConnectionDelegate >)delegate
Return Value

The receiver’s delegate.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSConnection.h

dispatchWithComponents:

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

- (void)dispatchWithComponents:(NSArray *)components
Parameters
components

Distributed Objects component data.

Discussion

NSPort subclasses should use this method to ask a connection object to dispatch Distributed Objects component data received over the wire. This will decode the data, authenticate, and send the message.

Availability
  • Available in OS X v10.7 and later.
Declared In
NSConnection.h

enableMultipleThreads

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

- (void)enableMultipleThreads
Discussion

In OS X v10.5 and later, multiple thread support is enabled by default and this method does nothing.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

independentConversationQueueing

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

- (BOOL)independentConversationQueueing
Return Value

YES if the receiver handles remote messages atomically, otherwise NO.

Discussion

See “Configuring a Connection” for more information on independent conversation queueing.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

initWithReceivePort:sendPort:

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

- (id)initWithReceivePort:(NSPort *)receivePort sendPort:(NSPort *)sendPort
Parameters
receivePort

The receive port for the new connection.

sendPort

The send port for the new connection.

Return Value

An NSConnection object initialized with receivePort and sendPort. The returned object might be different than the original receiver.

Discussion

The new NSConnection object adds receivePort to the current NSRunLoop object with NSDefaultRunLoopMode as the mode. If the application doesn’t use an NSApplication object to handle events, it needs to run the NSRunLoop object with one of its various run... messages.

This method posts an NSConnectionDidInitializeNotification once the connection is initialized.

The receivePort and sendPort parameters affect initialization as follows:

  • If an NSConnection object with the same ports already exists, returns it and discards the original receiver.

  • If an NSConnection object exists that uses the same ports, but switched in role, then the new NSConnection object communicates with it. Messages sent to a proxy held by either connection are forwarded through the other NSConnection object. This rule applies both within and across address spaces.

    This behavior is useful for setting up distributed object connections between threads within an application. See Distributed Objects Programming Topics for more information.

  • If receivePort and sendPort are nil, deallocates the receiver and returns nil.

  • If receivePort is nil, the NSConnection object allocates and uses a new port of the same class as sendPort.

  • If sendPort is nil or if both ports are the same, the NSConnection object uses receivePort for both sending and receiving and is useful only for vending an object. Use the registerName: and setRootObject: instance methods to vend an object.

  • If an NSConnection object exists that uses receivePort as both of its ports, it’s treated as the parent of the new NSConnection object, and its root object and all its configuration settings are applied to the new NSConnection object. You should neither register a name for nor set the root object of the new NSConnection object. See “Configuring a Connection” for more information.

  • If receivePort and sendPort are different and neither is shared with another NSConnection object, the receiver can be used to vend an object as well as to communicate with other NSConnection objects. However, it has no other NSConnection object to communicate with until one is set up.

  • The receivePort parameter can’t be shared by NSConnection objects in different threads.

This method is the designated initializer for the NSConnection class.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

invalidate

Invalidates the receiver.

- (void)invalidate
Discussion

After withdrawing the ports the receiver has registered with the current run loop, invalidate posts an NSConnectionDidDieNotification and then invalidates all remote objects and exported local proxies.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

isValid

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

- (BOOL)isValid
Return Value

YES if the receiver is known to be valid, otherwise NO.

Discussion

An NSConnection object becomes invalid when either of its ports becomes invalid, but only notes that it has become invalid when it tries to send or receive a message. When this happens it posts an NSConnectionDidDieNotification to the default notification center.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

localObjects

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

- (NSArray *)localObjects
Return Value

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

Discussion

When an object’s remote proxy is deallocated, a message is sent back to the receiver to notify it that the local object is no longer shared over the connection.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

multipleThreadsEnabled

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

- (BOOL)multipleThreadsEnabled
Return Value

YES if the receiver supports requests from multiple threads.

Discussion

In OS X v10.5 and later, multiple threads are enabled by default.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

receivePort

Returns the NSPort object on which the receiver receives incoming network messages.

- (NSPort *)receivePort
Return Value

The NSPort object on which the receiver receives incoming network messages.

Discussion

You can inspect this object for debugging purposes or use it to create another NSConnection object, but shouldn’t use it to send or receive messages explicitly. Don’t set the delegate of the receive port; it already has a delegate established by the NSConnection object.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

registerName:

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

- (BOOL)registerName:(NSString *)name
Parameters
name

The name under which to register the receiver.

Return Value

YES if the operation was successful, otherwise NO (for example, if another NSConnection object on the same host is already registered under name).

Discussion

This method connects the receive port of the receiving NSConnection object with the specified service name. It registers the name using the port name server returned by the systemDefaultPortNameServer method of NSPortNameServer. If the operation is successful, other NSConnection objects can contact the receiver using the connectionWithRegisteredName:host: and rootProxyForConnectionWithRegisteredName:host: class methods.

If the receiver was already registered under a name and this method returns NO, the old name remains in effect. If this method is successful, it also unregisters the old name.

To unregister an NSConnection object, simply invoke registerName: and supply nil as the connection name. Unregistering is currently only supported for NSSocketPort-based connections.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

registerName:withNameServer:

Registers a service with the specified port name server.

- (BOOL)registerName:(NSString *)name withNameServer:(NSPortNameServer *)server
Parameters
name

The name under which to register the receiver.

server

The name server.

Return Value

YES if the operation was successful, otherwise NO (for example, if another NSConnection object on the same host is already registered under name).

Discussion

This method connects the receive port of the receiving NSConnection object with the specified service name. If the operation is successful, other NSConnection objects can contact the receiver using the connectionWithRegisteredName:host: and rootProxyForConnectionWithRegisteredName:host: class methods.

If the receiver was already registered under a name and this method returns NO, the old name remains in effect. If this method is successful, it also unregisters the old name.

To unregister an NSConnection object, simply invoke registerName: and supply nil as the connection name.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSConnection.h

remoteObjects

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

- (NSArray *)remoteObjects
Return Value

An array containing all the local proxies for remote objects that have been received over the connection but not deallocated yet.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

removeRequestMode:

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

- (void)removeRequestMode:(NSString *)mode
Parameters
mode

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

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

removeRunLoop:

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

- (void)removeRunLoop:(NSRunLoop *)runloop
Parameters
runloop

The run loop to remove from the receiver.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

replyTimeout

Returns the timeout interval for replies to outgoing remote messages.

- (NSTimeInterval)replyTimeout
Return Value

The timeout interval for replies to outgoing remote messages.

Discussion

If a non-oneway remote message is sent and no reply is received by the timeout, an NSPortTimeoutException is raised.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

requestModes

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

- (NSArray *)requestModes
Return Value

An array of NSString objects that represents the set of request modes the receiver’s receive port is registered for with its NSRunLoop object.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

requestTimeout

Returns the timeout interval for outgoing remote messages.

- (NSTimeInterval)requestTimeout
Return Value

The timeout interval for outgoing remote messages.

Discussion

If a remote message can’t be sent before the timeout, an NSPortTimeoutException is raised.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

rootObject

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

- (id)rootObject
Return Value

The object that the receiver (or its parent) makes available to other applications or threads, or nil if there is no root object.

Discussion

To get a proxy to this object in another application or thread, invoke the rootProxyForConnectionWithRegisteredName:host: class method with the appropriate arguments.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

rootProxy

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

- (NSDistantObject *)rootProxy
Return Value

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

Discussion

The proxy returned can change between invocations if the peer NSConnection object's root object is changed.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSConnection.h

runInNewThread

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

- (void)runInNewThread
Discussion

If the newly created thread is the first to be detached from the current thread, this method posts an NSWillBecomeMultiThreadedNotification with nil to the default notification center.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSConnection.h

sendPort

Returns the NSPort object that the receiver sends outgoing network messages through.

- (NSPort *)sendPort
Return Value

The NSPort object that the receiver sends outgoing network messages through.

Discussion

You can inspect this object for debugging purposes or use it to create another NSConnection object, but shouldn’t use it to send or receive messages explicitly. Don’t set the delegate of the send port; it already has a delegate established by the NSConnection object.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

setDelegate:

Sets the receiver’s delegate.

- (void)setDelegate:(id < NSConnectionDelegate >)anObject
Parameters
anObject

The receiver’s delegate.

Discussion

A connection’s delegate can process incoming messages itself instead of letting NSConnection object handle them. The delegate can also authenticate messages and accept, deny, or modify new connections.

Availability
  • Available in OS X v10.0 and later.
Related Sample Code
Declared In
NSConnection.h

setIndependentConversationQueueing:

Sets a Boolean value that specifies whether the receiver handles remote messages atomically.

- (void)setIndependentConversationQueueing:(BOOL)flag
Parameters
flag

YES if the receiver handles remote messages atomically, otherwise NO.

Discussion

The default is NO. An NSConnection object normally forwards remote message to the intended recipients as they come in. See “Configuring a Connection” for more information.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

setReplyTimeout:

Sets the timeout interval for replies to outgoing remote messages

- (void)setReplyTimeout:(NSTimeInterval)seconds
Parameters
seconds

The timeout interval for replies to outgoing remote messages.

Discussion

If a non-oneway remote message is sent and no reply is received by the timeout, an NSPortTimeoutException is raised. The default timeout is the maximum possible value.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

setRequestTimeout:

Sets the timeout interval for outgoing remote messages.

- (void)setRequestTimeout:(NSTimeInterval)seconds
Parameters
seconds

The timeout interval for outgoing remote messages.

Discussion

If a remote message can’t be sent before the timeout, an NSPortTimeoutException is raised. The default timeout is the maximum possible value.

Availability
  • Available in OS X v10.0 and later.
See Also
Declared In
NSConnection.h

setRootObject:

Sets the object that the receiver makes available to other applications or threads.

- (void)setRootObject:(id)anObject
Parameters
anObject

The root object for the receiver.

Discussion

This only affects new connection requests and rootProxy messages to established NSConnection objects; applications that have proxies to the old root object can still send messages through it.

Availability
  • Available in OS X v10.0 and later.
See Also
Related Sample Code
Declared In
NSConnection.h

statistics

Returns an NSDictionary object containing various statistics for the receiver.

- (NSDictionary *)statistics
Return Value

An NSDictionary object containing various statistics for the receiver, such as the number of vended objects, the number of requests and replies, and so on.

Discussion

The statistics dictionary should be used only for debugging purposes.

Availability
  • Available in OS X v10.0 and later.
Declared In
NSConnection.h

Constants

NSConnection run loop mode

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

extern NSString *NSConnectionReplyMode;
Constants
NSConnectionReplyMode

The mode to indicate an NSConnection object waiting for replies.

You should rarely need to use this mode.

Available in OS X v10.0 and later.

Declared in NSConnection.h.

Connection Exception Names

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

extern NSString *NSFailedAuthenticationException;
Constants
NSFailedAuthenticationException

Raised by NSConnection on receipt of a remote message the delegate doesn’t authenticate.

Available in OS X v10.0 and later.

Declared in NSConnection.h.

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.

An NSConnection object attached to a remote NSSocketPort object cannot detect when the remote port becomes invalid, even if the remote port is on the same machine. Therefore, it cannot post this notification when the connection is lost. Instead, you must detect the timeout error when the next message is sent.

The NSConnection object posting this notification is no longer useful, so all receivers should unregister themselves for any notifications involving the NSConnection object.

Availability
See Also
Declared In
NSConnection.h

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.

Availability
See Also
Declared In
NSConnection.h


© 2013 Apple Inc. All Rights Reserved. (Last updated: 2013-01-28)

Did this document help you? Yes It's good, but... Not helpful...