Mac Developer Library

Developer

Foundation Framework Reference NSConnection Class Reference

Options
Deployment Target:

On This Page
Language:

NSConnection

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

Inheritance


Conforms To


Import Statement


Not Applicable @import Foundation;

Availability


Available in OS X v10.0 and later.
  • Returns the default NSConnection object for the current thread.

    Deprecation Statement

    Create individual connection instances as needed instead.

    Declaration

    Objective-C

    + (NSConnection *)defaultConnection

    Return Value

    The default NSConnection object for the current thread, creating it if necessary.

    Discussion

    The default NSConnection object uses a single NSPort object for both receiving and sending and is useful only for vending an object; use the rootObject and registerName: methods to do this.

    Special Considerations

    The singleton method of NSConnection has been deprecated. It was difficult to ensure that the shared connection wasn’t being used by other operations on the thread on which the default connection was requested. Using [NSConnection new] ensures that you get a unique connection object, preventing such collisions.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    Deprecated in OS X v10.6.

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

    Declaration

    Objective-C

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    - (instancetype)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 registerName: and rootObject 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 in Distributed Objects Programming Topics 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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    - (void)enableMultipleThreads

    Discussion

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • A Boolean value that indicates whether the receiver supports requests from multiple threads. (read-only)

    Declaration

    Objective-C

    @property(readonly) BOOL multipleThreadsEnabled

    Discussion

    YEStrue if the receiver supports requests from multiple threads, otherwise NOfalse.

    The default is YEStrue.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    - (void)removeRunLoop:(NSRunLoop *)runloop

    Parameters

    runloop

    The run loop to remove from the receiver.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    – addRunLoop:

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

    Declaration

    Objective-C

    + (instancetype)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

    Import Statement

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

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

    Import Statement

    Availability

    Available in OS X v10.5 and later.

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

    Declaration

    Objective-C

    - (BOOL)registerName:(NSString *)name

    Parameters

    name

    The name under which to register the receiver.

    Return Value

    YEStrue if the operation was successful, otherwise NOfalse (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 NOfalse, 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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Registers a service with the specified port name server.

    Declaration

    Objective-C

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

    Parameters

    name

    The name under which to register the receiver.

    server

    The name server.

    Return Value

    YEStrue if the operation was successful, otherwise NOfalse (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 NOfalse, 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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    @property(retain) id rootObject

    Discussion

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

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

    Changing the root object 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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    – rootProxy

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

    Declaration

    Objective-C

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • rootProxy rootProxy Property

    The proxy for the root object of the receiver’s peer in another application or thread. (read-only)

    Declaration

    Objective-C

    @property(readonly, retain) NSDistantObject *rootProxy

    Discussion

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    – rootObject

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

    Declaration

    Objective-C

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • The local proxies for remote objects that have been received over the connection but not deallocated yet. (read-only)

    Declaration

    Objective-C

    @property(readonly, copy) NSArray *remoteObjects

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • The local objects that have been sent over the connection and still have proxies at the other end. (read-only)

    Declaration

    Objective-C

    @property(readonly, copy) NSArray *localObjects

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    – createConversationForConnection: (NSConnectionDelegate)

  • Returns all valid NSConnection objects in the process.

    Declaration

    Objective-C

    + (NSArray *)allConnections

    Return Value

    An array containing all valid NSConnection objects in the process.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    – isValid

  • The timeout interval for outgoing remote messages.

    Declaration

    Objective-C

    @property NSTimeInterval requestTimeout

    Discussion

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • The timeout interval for replies to outgoing remote messages.

    Declaration

    Objective-C

    @property NSTimeInterval replyTimeout

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    @property BOOL independentConversationQueueing

    Discussion

    YEStrue if the receiver handles remote messages atomically, otherwise NOfalse.

    The default is NOfalse. An NSConnection object normally forwards remote message to the intended recipients as they come in. See Configuring a Connection in Distributed Objects Programming Topics for more information.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

    See Also

    addPort:forMode: (NSRunLoop)

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

    Declaration

    Objective-C

    - (void)removeRequestMode:(NSString *)mode

    Parameters

    mode

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • The set of request modes the receiver’s receive port is registered for with its NSRunLoop object. (read-only)

    Declaration

    Objective-C

    @property(readonly, copy) NSArray *requestModes

    Discussion

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Invalidates the receiver.

    Declaration

    Objective-C

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • valid valid Property

    A Boolean value that indicates whether the receiver is known to be valid. (read-only)

    Declaration

    Objective-C

    @property(readonly, getter=isValid) BOOL valid

    Discussion

    YEStrue if the receiver is known to be valid, otherwise NOfalse.

    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.

    Import Statement

    Availability

    Available in OS X v10.10 and later.

    See Also

    – invalidate
    isValid (NSPort)

  • The port on which the receiver receives incoming network messages. (read-only)

    Declaration

    Objective-C

    @property(readonly, retain) NSPort *receivePort

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • sendPort sendPort Property

    The port that the connection sends outgoing network messages through. (read-only)

    Declaration

    Objective-C

    @property(readonly, retain) NSPort *sendPort

    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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

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

    Import Statement

    Availability

    Available in OS X v10.7 and later.

  • A dictionary containing various statistics for the receiver. (read-only)

    Declaration

    Objective-C

    @property(readonly, copy) NSDictionary *statistics

    Discussion

    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.

    The statistics dictionary should be used only for debugging purposes.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • delegate delegate Property

    The receiver’s delegate.

    Declaration

    Objective-C

    @property(assign) id< NSConnectionDelegate > 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.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Declaration

    Objective-C

    extern NSString *NSConnectionReplyMode;

    Constants

    • NSConnectionReplyMode

      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.

    Import Statement

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

    Declaration

    Objective-C

    extern NSString *NSFailedAuthenticationException;

    Constants

    • NSFailedAuthenticationException

      NSFailedAuthenticationException

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

      Available in OS X v10.0 and later.

    Import Statement

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.

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

    Import Statement

    Availability

    Available in OS X v10.0 and later.