mccallum@gnu.ai.mit.edu
)rfm@gnu.org
)Version: 1.131
Date: 2004/09/21 14:20:34
Copyright: (C) 1994, 1995, 1996, 1997, 2000 Free Software Foundation, Inc.
- Declared in:
- Foundation/NSConnection.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
NSConnection objects are used to manage communications between objects in different processes, in different machines, or in different threads.
Method summaryReturns 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.
Returns a connection initialised using -initWithReceivePort:sendPort:
Returns an NSConnection object whose send port is that of the NSConnection registered under the name n on the host h
This method calls +connectionWithRegisteredName:host:usingNameServer: using the default system name 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
host host, 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).
Return the current conversation... not implemented in GNUstep
Returns the default connection for a 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.
Possible problem - if the
connection is invalidated, it won't be cleaned
up until this thread calls this method again. The
connection and it's ports could hang around for
a very long time.
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 n on host h.
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.
Adds mode to the run loop modes that the NSConnection will listen to for incoming messages.
Adds loop to the set of run loops that the NSConnection will listen to for incoming messages.
Returns the delegate of the NSConnection.
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.
NB. A connection with
multiple threads enabled will run slower than a
normal connection.
Returns YES
if the NSConnection is
configured to handle remote messages atomically,
NO
otherwise.
This option is
inherited by child connections.
Initialises an NSConnection with the receive
port r and the send port s.
Behavior varies with the port values as
follows -
nil
nil
.
nil
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.
Marks the receiving NSConnection as invalid.
Removes the NSConnections ports from any run loops.
Posts an NSConnectionDidDieNotification.
Invalidates all remote objects and local
proxies.
Returns YES
if the connection is
valid, NO
otherwise. A connection is
valid until it has been sent an
-invalidate
message.
Returns an array of all the local objects that have proxies at the remote end of the connection because they have been sent over the connection and not yet released by the far end.
Returns YES
if the connection permits
multiple threads to use it to send requests,
NO
otherwise.
See the
-enableMultipleThreads
method.
Returns the NSPort object on which incoming messages are recieved.
Simply invokes -registerName:withNameServer: passing it the default system nameserver.
Registers the recieve port of the NSConnection as
name and unregisters the previous value
(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.
Returns an array of proxies to all the remote objects known to the NSConnection.
Removes mode from the run loop modes used to receive incoming messages.
Removes loop from the run loops used to recieve incoming messages.
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.
Under MacOS-X the default value is
documented as the maximum delay (effectively
infinite), but under GNUstep it is set to a more
useful 300 seconds.
Returns an array of all the run loop modes that the NSConnection uses when waiting for an incoming request.
Returns the timeout interval used when trying to
send a request on the NSConnection. This value is
inherited from the parent connection or may be
set using the
-setRequestTimeout:
method.
Under MacOS-X the default value is
documented as the maximum delay (effectively
infinite), but under GNUstep it is set to a more
useful 300 seconds.
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.
Returns the proxy for the root object of the remote
NSConnection.
Generally you will wish
to call
[NSDistantObject -setProtocolForProxy:]
immediately after obtaining such a root proxy.
Removes the NSConnection from the current threads default run loop, then creates a new thread and runs the NSConnection in it.
Returns the port on which the NSConnection sends messages.
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.
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.
Sets the time interval that the NSConnection will wait
for a reply for one of its requests before raising an
NSPortTimeoutException.
NB.
In GNUstep you may also get such an exception if the
connection becomes invalidated while waiting for
a reply to a request.
Sets the runloop mode in which requests will be sent to the remote end of the connection. Normally this is NSDefaultRunloopMode
Sets the time interval that the NSConnection will wait to send one of its requests before raising an NSPortTimeoutException.
Sets the root object that is vended by the connection.
Returns an object containing various statistics for
the NSConnection.
On GNUstep the dictionary
contains -
- Declared in:
- Foundation/NSConnection.h
- Conforms to:
- GCFinalization
Standards:
- MacOS-X
- OpenStep
- GNUstep
This category contains legacy methods from the original GNU 'Connection' class, and useful extensions to NSConnection .
Method summaryAlternative convenience constructor, not specified in OpenStep, where you registe root anObject under given name in one step.
[NSDistantObject -forward::] calls this to send the message over the wire.
[NSDistantObject -forwardInvocation:] calls this to send the message over the wire.
Performs local and remote cleanup.
Returns type code (@encode()-compatible) for given remote method.
- Declared in:
- Foundation/NSConnection.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
This category represents an informal protocol to which NSConnection delegates may conform... implementing these methods has the effect documented.
Method summary
These are like the MacOS-X delegate methods, except
that we provide the components in mutable
arrays, so that the delegate can alter the data
items in the array. Of course, you must do that WITH
CARE.
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.
These are like the MacOS-X delegate methods, except
that we provide the components in mutable
arrays, so that the delegate can alter the data
items in the array. Of course, you must do that WITH
CARE.
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.
If the delegate responds to this method, it will be used to ask the delegate's permission to establish a new connection from the old one. Often this is used so that the delegate can register for invalidation notification on new child connections. This is a GNUstep extension Normally return newConn.
This method may be used to ask a delegate's permission
to create a new connection from the old one. This method
should be implemented in preference to the
[makeNewConnection:sender:]
which is obsolete.
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.
This is the old way of doing the same thing as
[connection:shouldMakeNewConnection:]
It is obsolete - don't use it.
An old fashioned
synonym for
-connection:shouldMakeNewConnection:
- don't use this.
- Declared in:
- Foundation/NSConnection.h
Standards:
- MacOS-X
- OpenStep
- GNUstep
This informal protocol allows an object to control the details of how an object is sent over the wire in distributed objects Port communications.
Method summaryMust return the class that will be created on the remote side of the connection. If the class to be created is not the same as that of the object returned by replacementObjectForPortCoder: then the class must be capable of recognising the object it actually gets in its initWithCoder: method. The default operation is to return NSDistantObject unless the object is being sent bycopy, in which case the objects actual class is returned. To force bycopy operation the object should return its own class.
This message is sent to an object about to be encoded for sending over the wire. The default action is to return an NSDistantObject which is a local proxy for the object unless the object is being sent bycopy, in which case the actual object is returned. To force bycopy, an object should return itself.