Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/Foundation.framework |
Availability | Available in Mac OS X v10.0 and later. |
Companion guide | |
Declared in | NSDistantObject.h |
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.
NSDistantObject
adds two useful instance methods to those defined by NSProxy
: connectionForProxy
returns the NSConnection
object that handles the receiver; setProtocolForProxy:
establishes the set of methods the real object is known to respond to, saving the network traffic required to determine the argument and return types the first time a particular selector is forwarded to the remote proxy.
There are two kinds of distant object: local proxies and remote proxies. A local proxy is created by an NSConnection
object the first time an object is sent to another application. It is used by the connection for bookkeeping purposes and should be considered private. The local proxy is transmitted over the network using the NSCoding
protocol to create the remote proxy, which is the object that the other application uses. NSDistantObject
defines methods for an NSConnection
object to create instances, but they’re intended only for subclasses to override—you should never invoke them directly. Use the rootProxyForConnectionWithRegisteredName:host:
method of NSConnection
, which sets up all the required state for an object-proxy pair.
Important: NSDistantObject
conforms to the NSCoding
protocol, but only supports coding by an NSPortCoder
. NSDistantObject
and its subclasses do not support archiving.
Returns a local proxy for a given object and connection, creating the proxy if necessary.
+ (NSDistantObject *)proxyWithLocal:(id)anObject connection:(NSConnection *)aConnection
An object in the receiver’s address space.
The connection for the returned proxy.
A local proxy for anObject and aConnection, creating it if necessary.
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.
NSDistantObject.h
Returns a remote proxy for a given object and connection, creating the proxy if necessary.
+ (NSDistantObject *)proxyWithTarget:(id)remoteObject connection:(NSConnection *)aConnection
An object in another thread or another application’s address space.
The connection to set as the NSConnection
object for the returned proxy—it should have been created using the NSConnection
connectionWithRegisteredName:host:
class method.
A remote proxy for remoteObject and aConnection, creating the proxy if necessary
A remote proxy cannot be used until its connection's peer has a local proxy representing remoteObject in the other application.
NSDistantObject.h
Returns the connection used by the receiver.
- (NSConnection *)connectionForProxy
The connection used by the receiver.
NSDistantObject.h
Initializes an NSDistantObject
object as a local proxy for a given object.
- (id)initWithLocal:(id)anObject connection:(NSConnection *)aConnection
An object in the receiver’s address space.
The connection for the returned proxy.
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.
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.
This is the designated initializer for local proxies. It returns an initialized object, which might be different than the original receiver
NSDistantObject.h
Initializes a newly allocated NSDistantObject as a remote proxy for remoteObject, which is an id in another thread or another application’s address space.
- (id)initWithTarget:(id)remoteObject connection:(NSConnection *)aConnection
An object in another thread or another application’s address space.
The connection to set as the NSConnection
object for the returned proxy—it should have been created using the NSConnection
connectionWithRegisteredName:host:
class method.
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.
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.
NSDistantObject.h
Sets the methods known to be handled by the receiver to those in a given protocol.
- (void)setProtocolForProxy:(Protocol *)aProtocol
The protocol for the receiver.
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.
NSDistantObject.h
© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-01-19)