[Previous]
[Up]
[Next]
NSConnection
Authors
- Richard Frith-Macdonald
-
Version: $Revision$
Date: $Date$
Declared in: Foundation/NSConnection.h
Inherits from: NSObject
Conforms to: NSObject
NSConnection objects are used to manage communications between
objects in different processes, in different machines, or in
different threads.
Instance Variables
Methods
Class Methods
+ (NSArray*) allConnections;
Returns an array containing all the NSConnection objects known to
the system. These connections will be valid at the time that the
array was created, but may be invalidated by other threads
before you get to examine the array.
+ (NSConnection*) connectionWithReceivePort: (NSPort*)receivePort;
Returns a connection created using
initWithReceivePort:sendPort:
+ (NSConnection*) connectionWithRegisteredName: (NSString*)name host: (NSString*)hostName;
Returns an NSConnection object whose send port is that of the
NSConnection registered under name on the host
hostName.
This method calls
connectionWithRegisteredName:host:usingNameServer: using
the default system name server.
+ (NSConnection*) connectionWithRegisteredName: (NSString*)name host: (NSString*)host usingNameServer: (NSPortNameServer*)server;
Returns an NSConnection object whose send port is that of the
NSConnection registered under name on host.
The nameserver server is used to look up the send
port to be used for the connection.
If host is nil or an empty string,
the host is taken to be the local machine.
If it is an asterisk ('*') then the nameserver checks all
hosts on the local subnet (unless the nameserver is one
that only manages local ports).
In the GNUstep implementation, the local host is searched before
any other hosts.
If no NSConnection can be found for name and
hosthost, the method returns nil.
The returned object has the default NSConnection of the
current thread as its parent (it has the same receive port
as the default connection).
+ (id) currentConversation;
Not implemented
+ (NSConnection*) defaultConnection;
Returns the default NSConnection for the current thread.
Creates a new instance if necessary.
The default connection has a single NSPort object used for
both sending and receiving - this it can't be used to
connect to a remote process, but can be used to vend objects.
+ (NSConnection*) newRegisteringAtName: (NSString*)name withRootObject: (id)anObject;
Standards: GNUstep NotMacOS-X NotOpenStep
This used to be the preferred mechanism for creating a GNUstep
server NSConnection ... it is now deprecated.
This is a convenience method for -
example
NSConnection *conn;
conn = [[NSConnection alloc] initWithReceivePort: [NSPort port]
sendPort: nil];
[conn setRootObject: anObject];
if ([conn registerName: name] == NO)
{
DESTROY(conn);
}
return conn;
+ (NSDistantObject*) rootProxyForConnectionWithRegisteredName: (NSString*)name host: (NSString*)host;
This method calls
rootProxyForConnectionWithRegisteredName:host:usingNameServer:
to return a proxy for a root object on the remote connection with
the send port registered under name on host
+ (NSDistantObject*) rootProxyForConnectionWithRegisteredName: (NSString*)name host: (NSString*)host usingNameServer: (NSPortNameServer*)server;
Standards: GNUstep MacOS-X NotOpenStep
This method calls
connectionWithRegisteredName:host:usingNameServer:
to get a connection, then sends it a
rootProxy message to get a proxy for
the root object being vended by the remote connection.
Returns the proxy or nil if it couldn't find
a connection or if the root object for the connection has
not been set.
Instances Methods
- (void) addRequestMode: (NSString*)mode;
Adds mode to the run loop modes that the NSConnection
will listen to for incoming messages.
- (void) addRunLoop: (NSRunLoop*)loop;
Adds loop to the set of run loops that the NSConnection
will listen to for incoming messages.
- (id) delegate;
Returns the delegate of the NSConnection.
- (void) enableMultipleThreads;
Sets the NSConnection configuration so that multiple threads may
use the connection to send requests to the remote connection.
This option is inherited by child connections.
- (BOOL) independentConversationQueueing;
Returns YES if the NSConnection is configured to
handle remote messages atomically, NO otherwise.
This option is inherited by child connections.
This is the designated initialiser
- (id) initWithReceivePort: (NSPort*)recv sendPort: (NSPort*)send;
Initialises an NSConnection with recv and send.
Behavior varies with the port values as follows -
- recv is
nil
-
The NSConnection is released and the method returns
nil.
- send is
nil
-
The NSConnection uses recv as the send port as
well as the receive port.
- send is the same as recv
-
The NSConnection is usable only for vending objects.
- A connection with the same ports exists
-
The new connection is released and the old connection
is retained and returned.
- A connection with the same ports (swapped) exists
-
The new connection is initialised as normal, and will
communicate with the old connection.
If a connection exists whose send and receive ports are
both the same as the new connections receive port, that
existing connection is deemed to be the parent of the
new connection. The new connection inherits configuration
information from the parent, and the delegate of the
parent has a chance to adjust ythe configuration of the
new connection or veto its creation.
NSConnectionDidInitializeNotification is posted once a new
connection is initialised.
- (void) invalidate;
Marks the receiving NSConnection as invalid.
Removes the NSConnections ports from any run loops.
Posts an NSConnectionDidDieNotification.
Invalidates all remote objects and local proxies.
- (BOOL) isValid;
Returns YES if the connection is invalid,
NO otherwise.
- (NSArray*) localObjects;
Returns an array of all the local proxies to objects that
are retained by the remote connection.
- (BOOL) multipleThreadsEnabled;
Returns YES if the connection permits
multiple threads to use it to send requests,
NO otherwise.
- (NSPort*) receivePort;
Returns the NSPort object on which incoming messages are
recieved.
- (BOOL) registerName: (NSString*)name;
Simply invokes
registerName:usingNameServer: passing it the default
system nameserver.
- (BOOL) registerName: (NSString*)name withNameServer: (NSPortNameServer*)server;
Standards: GNUstep MacOS-X NotOpenStep
Registers the recieve port of the NSConnection as name and
unregisters the previous name (if any).
Returns YES on success, NO on failure.
On failure, the connection remains registered under the
previous name.
Supply nil as name to unregister the
NSConnection.
- (NSArray*) remoteObjects;
Returns an array of proxies to all the remote objects known to
the NSConnection.
- (void) removeRequestMode: (NSString*)mode;
Removes mode from the run loop modes used to recieve
incoming messages.
- (void) removeRunLoop: (NSRunLoop*)loop;
Removes loop from the run loops used to recieve
incoming messages.
- (NSTimeInterval) replyTimeout;
Returns the timeout interval used when waiting for a reply to
a request sent on the NSConnection. This value is inherited
from the parent connection or may be set using the
setReplyTimeout: method. The default value is the maximum
delay (effectively infinite).
- (NSArray*) requestModes;
Returns an array of all the run loop modes that the NSConnection
uses when waiting for an incoming request.
- (NSTimeInterval) requestTimeout;
Returns the timeout interval used when waiting for a send
operation to complete. This value is inherited
from the parent connection or may be set using the
setRequestTimeout: method. The default value is the maximum
delay (effectively infinite).
- (id) rootObject;
Returns the object that is made available by this connection
or by its parent (the object is associated with the receive
port).
Returns nil if no root object has been set.
- (NSDistantObject*) rootProxy;
Returns the proxy for the root object of the remote NSConnection.
- (void) runInNewThread;
Removes the NSConnection from the current threads default
run loop, then creates a new thread and runs the NSConnection
in it.
- (NSPort*) sendPort;
Returns the port on which the NSConnection sends messages.
- (void) setDelegate: (id)delegate;
Sets the NSConnection's delegate (without retaining it).
The delegate is able to control some of the NSConnection's
behavior by implementing methods in an informal protocol.
- (void) setIndependentConversationQueueing: (BOOL)flag;
Sets whether or not the NSConnection should handle requests
arriving from the remote NSConnection atomically.
By default, this is set to NO ... if set to
YES then any messages arriving while one message
is being dealt with, will be queued.
NB. careful - use of this option can cause deadlocks.
- (void) setReplyTimeout: (NSTimeInterval)seconds;
Sets the time interval that the NSConnection will wait for a
reply to one of its requests before raising an
NSPortTimeoutException.
- (void) setRequestTimeout: (NSTimeInterval)seconds;
Sets the time interval that the NSConnection will wait to send
one of its requests before raising an NSPortTimeoutException.
- (void) setRootObject: (id)anObject;
Sets the root object that is vended by the connection.
- (NSDictionary*) statistics;
Returns an object containing various statistics for the
NSConnection.
On GNUstep the dictionary contains -
- NSConnectionRepliesReceived
-
The number of messages replied to by the remote NSConnection
- NSConnectionRepliesSent
-
The number of replies sent to the remote NSConnection
- NSConnectionRequestsReceived
-
The number of messages recieved from the remote NSConnection
- NSConnectionRequestsSent
-
The number of messages sent to the remote NSConnection
- NSConnectionLocalCount
-
The number of local objects currently vended
- NSConnectionProxyCount
-
The number of remote objects currently in use
- (BOOL) authenticateComponents: (NSMutableArray*)components withData: (NSData*)authentication;
Standards: GNUstep MacOS-X NotOpenStep
This is not an NSConnection method, but is a method that may
be implemented by the delegate of an NSConnection object.
If the delegate implements this method, the NSConnection will
invoke the method for every message request or reply it receives
from the remote NSConnection. The delegate should use the
authentication data to check all the NSData objects
in the components array (ignoring NSPort objects),
and return YES if they are valid, NO
otherwise.
If the method returns NO then an
NSFailedAuthentication exception will be raised.
In GNUstep the components array is mutable, allowing
you to replace the NSData objects with your own version.
- (NSData*) authenticationDataForComponents: (NSMutableArray*)components;
Standards: GNUstep MacOS-X NotOpenStep
This is not an NSConnection method, but is a method that may
be implemented by the delegate of an NSConnection object.
If the delegate implements this method, the NSConnection will
invoke the method for every message request ro reply it sends
to the remote NSConnection. The delegate should generate
authentication data by examining all the NSData objects
in the components array (ignoring NSPort objects),
and return the authentication data that can be used by the
remote NSConnection.
If the method returns nil then an
NSGenericException exception will be raised.
In GNUstep the components array is mutable, allowing
you to replace the NSData objects with your own version.
- (BOOL) connection: (NSConnection*)parentConnection shouldMakeNewConnection: (NSConnection*)newConnnection;
Standards: GNUstep MacOS-X NotOpenStep
This is not an NSConnection method, but is a method that may
be implemented by the delegate of an NSConnection object.
If the delegate implements this method, it will be called
whenever a new NSConnection is created that has this
NSConnection as its parent. The delegate may take this
opportunity to adjust the configuration of the new
connection and may return a boolean value to tell the
parent whether the creation of the new connection is to
be permitted or not.
- (BOOL) makeNewConnection: (NSConnection*)newConnection;
Standards: OpenStep
This is not an NSConnection method, but is a method that may
be implemented by the delegate of an NSConnection object.
This is the old equivalent of
connection:shouldMakeNewConnection
and its use is now deprecated.