Mac Developer Library

Developer

Foundation Framework Reference NSDistantObject Class Reference

Options
Deployment Target:

On This Page

NSDistantObject

NSDistantObject is a concrete subclass of NSProxy that defines proxies for objects in other applications or threads. When a distant object receives a message, in most cases it forwards the message through its NSConnection object to the real object in another application, supplying the return value to the sender of the message if one is received, and propagating any exception back to the invoker of the method that raised it. More...

Inheritance


Conforms To


Import Statement


Not Applicable @import Foundation;

Availability


Available in OS X v10.0 and later.
  • Returns a local proxy for a given object and connection, creating the proxy if necessary.

    Declaration

    Objective-C

    + (id)proxyWithLocal:(id)anObject connection:(NSConnection *)aConnection

    Parameters

    anObject

    An object in the receiver’s address space.

    aConnection

    The connection for the returned proxy.

    Return Value

    A local proxy for anObject and aConnection, creating it if necessary.

    Discussion

    Other applications connect to the proxy using the NSConnection connectionWithRegisteredName:host: class method.

    Local proxies should be considered private to their NSConnection objects. Only an NSConnection object should use this method to create them, and your code shouldn’t retain or otherwise use local proxies.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Initializes an NSDistantObject object as a local proxy for a given object.

    Declaration

    Objective-C

    - (instancetype)initWithLocal:(id)anObject connection:(NSConnection *)aConnection

    Parameters

    anObject

    An object in the receiver’s address space.

    aConnection

    The connection for the returned proxy.

    Return Value

    An initialized NSDistantObject object that serves as a local proxy for anObject. If a proxy for anObject and aConnection already exists, the receiver is released and the existing proxy is retained and returned.

    Discussion

    Other applications connect to the proxy using the NSConnectionconnectionWithRegisteredName:host: class method.

    Local proxies should be considered private to their NSConnection objects. Only an NSConnection object should use this method to create them, and your code shouldn’t retain or otherwise use local proxies.

    This is the designated initializer for local proxies. It returns an initialized object, which might be different than the original receiver

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Returns a remote proxy for a given object and connection, creating the proxy if necessary.

    Declaration

    Objective-C

    + (id)proxyWithTarget:(id)remoteObject connection:(NSConnection *)aConnection

    Parameters

    remoteObject

    An object in another thread or another application’s address space.

    aConnection

    The connection to set as the NSConnection object for the returned proxy—it should have been created using the NSConnection connectionWithRegisteredName:host: class method.

    Return Value

    A remote proxy for remoteObject and aConnection, creating the proxy if necessary

    Discussion

    A remote proxy cannot be used until its connection's peer has a local proxy representing remoteObject in the other application.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Initializes a newly allocated NSDistantObject as a remote proxy for remoteObject, which is an id in another thread or another application’s address space.

    Declaration

    Objective-C

    - (instancetype)initWithTarget:(id)remoteObject connection:(NSConnection *)aConnection

    Parameters

    remoteObject

    An object in another thread or another application’s address space.

    aConnection

    The connection to set as the NSConnection object for the returned proxy—it should have been created using the NSConnectionconnectionWithRegisteredName:host: class method.

    Return Value

    An NSDistantObject object initialized as a remote proxy for remoteObject. If a proxy for remoteObject and aConnection already exists, the receiver is released and the existing proxy is retained and returned.

    Discussion

    A remote proxy can’t be used until its connection’s peer has a local proxy representing remoteObject in the other application.

    This is the designated initializer for remote proxies. It returns an initialized object, which might be different than the original receiver.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Returns the connection used by the receiver.

    Declaration

    Objective-C

    @property(readonly, retain) NSConnection *connectionForProxy

    Return Value

    The connection used by the receiver.

    Import Statement

    Availability

    Available in OS X v10.0 and later.

  • Sets the methods known to be handled by the receiver to those in a given protocol.

    Declaration

    Objective-C

    - (void)setProtocolForProxy:(Protocol *)aProtocol

    Parameters

    aProtocol

    The protocol for the receiver.

    Discussion

    Setting a protocol for a remote proxy reduces network traffic needed to determine method argument and return types.

    In order to encode a message’s arguments for transmission over the network, the types of those arguments must be known in advance. When they’re not known, the distributed objects system must send an initial message just to get those types, doubling the network traffic for every new message sent. Setting a protocol alleviates this need for methods defined by the protocol. You can still send messages that aren’t declared in aProtocol—in this case the initial message is sent to determine the types, and then the real message is sent.

    Import Statement

    Availability

    Available in OS X v10.0 and later.