mirror of
https://github.com/gnustep/libs-base.git
synced 2025-04-29 03:21:05 +00:00
a96445d01c
git-svn-id: svn+ssh://svn.gna.org/svn/gnustep/libs/base/trunk@11090 72102866-910b-0410-8b05-ffd578937521
598 lines
21 KiB
XML
598 lines
21 KiB
XML
<?xml version="1.0"?>
|
|
<!DOCTYPE gsdoc PUBLIC "-//GNUstep//DTD gsdoc 0.6.6//EN" "http://www.gnustep.org/gsdoc-0_6_6.xml">
|
|
<gsdoc base="NSConnection" prev="NSConditionLock" next="NSCountedSet" up="Base">
|
|
<head>
|
|
<title>NSConnection</title>
|
|
<author name="Richard Frith-Macdonald">
|
|
<email address="rfm@gnu.org"/>
|
|
<url url="http://www.gnustep.org/developers/whoiswho.html"/>
|
|
</author>
|
|
<version>$Revision$</version>
|
|
<date>$Date$</date>
|
|
</head>
|
|
<body>
|
|
<chapter>
|
|
<heading>NSConnection</heading>
|
|
<class name="NSConnection" super="NSObject">
|
|
<declared>Foundation/NSConnection.h</declared>
|
|
<conform>NSObject</conform>
|
|
<desc>
|
|
NSConnection objects are used to manage communications between
|
|
objects in different processes, in different machines, or in
|
|
different threads.
|
|
</desc>
|
|
<method type="NSArray*" factory="yes">
|
|
<sel>allConnections</sel>
|
|
<desc>
|
|
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.
|
|
</desc>
|
|
</method>
|
|
<method type="NSConnection*" factory="yes">
|
|
<sel>connectionWithReceivePort:</sel>
|
|
<arg type="NSPort*">receivePort</arg>
|
|
<desc>
|
|
Returns a connection created using
|
|
<ref id="initWithReceivePort:sendPort:">
|
|
initWithReceivePort:sendPort:</ref>
|
|
</desc>
|
|
</method>
|
|
<method type="NSConnection*" factory="yes">
|
|
<sel>connectionWithRegisteredName:</sel>
|
|
<arg type="NSString*">name</arg>
|
|
<sel>host:</sel>
|
|
<arg type="NSString*">hostName</arg>
|
|
<desc>
|
|
<p>
|
|
Returns an NSConnection object whose send port is that of the
|
|
NSConnection registered under <em>name</em> on the host
|
|
<em>hostName</em>.
|
|
</p>
|
|
<p>
|
|
This method calls
|
|
<ref id="connectionWithRegisteredName:host:usingNameServer:">
|
|
connectionWithRegisteredName:host:usingNameServer:</ref> using
|
|
the default system name server.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
<method type="NSConnection*" factory="yes"
|
|
id="connectionWithRegisteredName:host:usingNameServer:">
|
|
<sel>connectionWithRegisteredName:</sel>
|
|
<arg type="NSString*">name</arg>
|
|
<sel>host:</sel>
|
|
<arg type="NSString*">host</arg>
|
|
<sel>usingNameServer:</sel>
|
|
<arg type="NSPortNameServer*">server</arg>
|
|
<desc>
|
|
<p>
|
|
Returns an NSConnection object whose send port is that of the
|
|
NSConnection registered under <em>name</em> on <em>host</em>.
|
|
</p>
|
|
<p>
|
|
The nameserver <em>server</em> is used to look up the send
|
|
port to be used for the connection.
|
|
</p>
|
|
<p>
|
|
If <em>host</em> is <code>nil</code> 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.
|
|
</p>
|
|
<p>
|
|
If no NSConnection can be found for <em>name</em> and
|
|
<em>host</em>host, the method returns <code>nil</code>.
|
|
</p>
|
|
<p>
|
|
The returned object has the default NSConnection of the
|
|
current thread as its parent (it has the same receive port
|
|
as the default connection).
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
<method type="id" factory="yes">
|
|
<sel>currentConversation</sel>
|
|
<desc>
|
|
Not implemented
|
|
</desc>
|
|
</method>
|
|
<method type="NSConnection*" factory="yes">
|
|
<sel>defaultConnection</sel>
|
|
<desc>
|
|
Returns the default NSConnection for the current thread.
|
|
<br/>
|
|
Creates a new instance if necessary.
|
|
<br/>
|
|
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.
|
|
</desc>
|
|
</method>
|
|
<method type="NSConnection*" factory="yes">
|
|
<sel>newRegisteringAtName:</sel>
|
|
<arg type="NSString*">name</arg>
|
|
<sel>withRootObject:</sel>
|
|
<arg type="id">anObject</arg>
|
|
<desc>
|
|
This used to be the preferred mechanism for creating a GNUstep
|
|
server NSConnection ... it is now deprecated.
|
|
<br/>
|
|
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;
|
|
</example>
|
|
</desc>
|
|
<standards><GNUstep/><NotMacOS-X/><NotOpenStep/></standards>
|
|
</method>
|
|
<method type="NSDistantObject*" factory="yes">
|
|
<sel>rootProxyForConnectionWithRegisteredName:</sel>
|
|
<arg type="NSString*">name</arg>
|
|
<sel>host:</sel>
|
|
<arg type="NSString*">host</arg>
|
|
<desc>
|
|
This method calls <ref
|
|
id="rootProxyForConnectionWithRegisteredName:host:usingNameServer:">
|
|
rootProxyForConnectionWithRegisteredName:host:usingNameServer:</ref>
|
|
to return a proxy for a root object on the remote connection with
|
|
the send port registered under <em>name</em> on <em>host</em>
|
|
</desc>
|
|
</method>
|
|
<method type="NSDistantObject*" factory="yes"
|
|
id="rootProxyForConnectionWithRegisteredName:host:usingNameServer:">
|
|
<sel>rootProxyForConnectionWithRegisteredName:</sel>
|
|
<arg type="NSString*">name</arg>
|
|
<sel>host:</sel>
|
|
<arg type="NSString*">host</arg>
|
|
<sel>usingNameServer:</sel>
|
|
<arg type="NSPortNameServer*">server</arg>
|
|
<desc>
|
|
This method calls
|
|
<ref id="connectionWithRegisteredName:host:usingNameServer:">
|
|
connectionWithRegisteredName:host:usingNameServer:</ref>
|
|
to get a connection, then sends it a
|
|
<ref id="rootproxy">rootProxy</ref> message to get a proxy for
|
|
the root object being vended by the remote connection.
|
|
Returns the proxy or <code>nil</code> if it couldn't find
|
|
a connection or if the root object for the connection has
|
|
not been set.
|
|
</desc>
|
|
<standards><GNUstep/><MacOS-X/><NotOpenStep/></standards>
|
|
</method>
|
|
<method type="void">
|
|
<sel>addRequestMode:</sel>
|
|
<arg type="NSString*">mode</arg>
|
|
<desc>
|
|
Adds <em>mode</em> to the run loop modes that the NSConnection
|
|
will listen to for incoming messages.
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>addRunLoop:</sel>
|
|
<arg type="NSRunLoop*">loop</arg>
|
|
<desc>
|
|
Adds <em>loop</em> to the set of run loops that the NSConnection
|
|
will listen to for incoming messages.
|
|
</desc>
|
|
</method>
|
|
<method type="id">
|
|
<sel>delegate</sel>
|
|
<desc>
|
|
Returns the delegate of the NSConnection.
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>enableMultipleThreads</sel>
|
|
<desc>
|
|
Sets the NSConnection configuration so that multiple threads may
|
|
use the connection to send requests to the remote connection.
|
|
<br/>
|
|
This option is inherited by child connections.
|
|
</desc>
|
|
</method>
|
|
<method type="BOOL">
|
|
<sel>independentConversationQueueing</sel>
|
|
<desc>
|
|
Returns <code>YES</code> if the NSConnection is configured to
|
|
handle remote messages atomically, <code>NO</code> otherwise.
|
|
<br/>
|
|
This option is inherited by child connections.
|
|
</desc>
|
|
</method>
|
|
<method init="yes" type="id" id="initWithReceivePort:sendPort:">
|
|
<sel>initWithReceivePort:</sel>
|
|
<arg type="NSPort*">recv</arg>
|
|
<sel>sendPort:</sel>
|
|
<arg type="NSPort*">send</arg>
|
|
<desc>
|
|
Initialises an NSConnection with <em>recv</em> and <em>send</em>.
|
|
<br/>
|
|
Behavior varies with the port values as follows -
|
|
<deflist>
|
|
<term><em>recv</em> is <code>nil</code></term>
|
|
<desc>
|
|
The NSConnection is released and the method returns
|
|
<code>nil</code>.
|
|
</desc>
|
|
<term><em>send</em> is <code>nil</code></term>
|
|
<desc>
|
|
The NSConnection uses <em>recv</em> as the send port as
|
|
well as the receive port.
|
|
</desc>
|
|
<term><em>send</em> is the same as <em>recv</em></term>
|
|
<desc>
|
|
The NSConnection is usable only for vending objects.
|
|
</desc>
|
|
<term>A connection with the same ports exists</term>
|
|
<desc>
|
|
The new connection is released and the old connection
|
|
is retained and returned.
|
|
</desc>
|
|
<term>A connection with the same ports (swapped) exists</term>
|
|
<desc>
|
|
The new connection is initialised as normal, and will
|
|
communicate with the old connection.
|
|
</desc>
|
|
</deflist>
|
|
<p>
|
|
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.
|
|
<br/>
|
|
NSConnectionDidInitializeNotification is posted once a new
|
|
connection is initialised.
|
|
</p>
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>invalidate</sel>
|
|
<desc>
|
|
Marks the receiving NSConnection as invalid.
|
|
<br/>
|
|
Removes the NSConnections ports from any run loops.
|
|
<br/>
|
|
Posts an NSConnectionDidDieNotification.
|
|
<br/>
|
|
Invalidates all remote objects and local proxies.
|
|
</desc>
|
|
</method>
|
|
<method type="BOOL">
|
|
<sel>isValid</sel>
|
|
<desc>
|
|
Returns <code>YES</code> if the connection is invalid,
|
|
<code>NO</code> otherwise.
|
|
</desc>
|
|
</method>
|
|
<method type="NSArray*">
|
|
<sel>localObjects</sel>
|
|
<desc>
|
|
Returns an array of all the local proxies to objects that
|
|
are retained by the remote connection.
|
|
</desc>
|
|
</method>
|
|
<method type="BOOL">
|
|
<sel>multipleThreadsEnabled</sel>
|
|
<desc>
|
|
Returns <code>YES</code> if the connection permits
|
|
multiple threads to use it to send requests,
|
|
<code>NO</code> otherwise.
|
|
</desc>
|
|
</method>
|
|
<method type="NSPort*">
|
|
<sel>receivePort</sel>
|
|
<desc>
|
|
Returns the NSPort object on which incoming messages are
|
|
recieved.
|
|
</desc>
|
|
</method>
|
|
<method type="BOOL">
|
|
<sel>registerName:</sel>
|
|
<arg type="NSString*">name</arg>
|
|
<desc>
|
|
Simply invokes <ref id="registerName:usingNameServer:">
|
|
registerName:usingNameServer:</ref> passing it the default
|
|
system nameserver.
|
|
</desc>
|
|
</method>
|
|
<method type="BOOL">
|
|
<sel>registerName:</sel>
|
|
<arg type="NSString*">name</arg>
|
|
<sel>withNameServer:</sel>
|
|
<arg type="NSPortNameServer*">server</arg>
|
|
<desc>
|
|
Registers the recieve port of the NSConnection as <em>name</em> and
|
|
unregisters the previous name (if any).
|
|
<br/>
|
|
Returns <code>YES</code> on success, <code>NO</code> on failure.
|
|
<br/>
|
|
On failure, the connection remains registered under the
|
|
previous name.
|
|
<br/>
|
|
Supply <code>nil</code> as <em>name</em> to unregister the
|
|
NSConnection.
|
|
</desc>
|
|
<standards><GNUstep/><MacOS-X/><NotOpenStep/></standards>
|
|
</method>
|
|
<method type="NSArray*">
|
|
<sel>remoteObjects</sel>
|
|
<desc>
|
|
Returns an array of proxies to all the remote objects known to
|
|
the NSConnection.
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>removeRequestMode:</sel>
|
|
<arg type="NSString*">mode</arg>
|
|
<desc>
|
|
Removes <em>mode</em> from the run loop modes used to recieve
|
|
incoming messages.
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>removeRunLoop:</sel>
|
|
<arg type="NSRunLoop*">loop</arg>
|
|
<desc>
|
|
Removes <em>loop</em> from the run loops used to recieve
|
|
incoming messages.
|
|
</desc>
|
|
</method>
|
|
<method type="NSTimeInterval">
|
|
<sel>replyTimeout</sel>
|
|
<desc>
|
|
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).
|
|
</desc>
|
|
</method>
|
|
<method type="NSArray*">
|
|
<sel>requestModes</sel>
|
|
<desc>
|
|
Returns an array of all the run loop modes that the NSConnection
|
|
uses when waiting for an incoming request.
|
|
</desc>
|
|
</method>
|
|
<method type="NSTimeInterval">
|
|
<sel>requestTimeout</sel>
|
|
<desc>
|
|
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).
|
|
</desc>
|
|
</method>
|
|
<method type="id">
|
|
<sel>rootObject</sel>
|
|
<desc>
|
|
Returns the object that is made available by this connection
|
|
or by its parent (the object is associated with the receive
|
|
port).
|
|
<br/>
|
|
Returns <code>nil</code> if no root object has been set.
|
|
</desc>
|
|
</method>
|
|
<method type="NSDistantObject*">
|
|
<sel>rootProxy</sel>
|
|
<desc>
|
|
Returns the proxy for the root object of the remote NSConnection.
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>runInNewThread</sel>
|
|
<desc>
|
|
Removes the NSConnection from the current threads default
|
|
run loop, then creates a new thread and runs the NSConnection
|
|
in it.
|
|
</desc>
|
|
</method>
|
|
<method type="NSPort*">
|
|
<sel>sendPort</sel>
|
|
<desc>
|
|
Returns the port on which the NSConnection sends messages.
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>setDelegate:</sel>
|
|
<arg type="id">delegate</arg>
|
|
<desc>
|
|
Sets the NSConnection's delegate (without retaining it).
|
|
<br/>
|
|
The delegate is able to control some of the NSConnection's
|
|
behavior by implementing methods in an informal protocol.
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>setIndependentConversationQueueing:</sel>
|
|
<arg type="BOOL">flag</arg>
|
|
<desc>
|
|
Sets whether or not the NSConnection should handle requests
|
|
arriving from the remote NSConnection atomically.
|
|
<br/>
|
|
By default, this is set to <code>NO</code> ... if set to
|
|
<code>YES</code> then any messages arriving while one message
|
|
is being dealt with, will be queued.
|
|
<br/>
|
|
NB. careful - use of this option can cause deadlocks.
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>setReplyTimeout:</sel>
|
|
<arg type="NSTimeInterval">seconds</arg>
|
|
<desc>
|
|
Sets the time interval that the NSConnection will wait for a
|
|
reply to one of its requests before raising an
|
|
NSPortTimeoutException.
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>setRequestTimeout:</sel>
|
|
<arg type="NSTimeInterval">seconds</arg>
|
|
<desc>
|
|
Sets the time interval that the NSConnection will wait to send
|
|
one of its requests before raising an NSPortTimeoutException.
|
|
</desc>
|
|
</method>
|
|
<method type="void">
|
|
<sel>setRootObject:</sel>
|
|
<arg type="id">anObject</arg>
|
|
<desc>
|
|
Sets the root object that is vended by the connection.
|
|
</desc>
|
|
</method>
|
|
<method type="NSDictionary*">
|
|
<sel>statistics</sel>
|
|
<desc>
|
|
Returns an object containing various statistics for the
|
|
NSConnection.
|
|
<br/>
|
|
On GNUstep the dictionary contains -
|
|
<deflist>
|
|
<term>NSConnectionRepliesReceived</term>
|
|
<desc>
|
|
The number of messages replied to by the remote NSConnection
|
|
</desc>
|
|
<term>NSConnectionRepliesSent</term>
|
|
<desc>
|
|
The number of replies sent to the remote NSConnection
|
|
</desc>
|
|
<term>NSConnectionRequestsReceived</term>
|
|
<desc>
|
|
The number of messages recieved from the remote NSConnection
|
|
</desc>
|
|
<term>NSConnectionRequestsSent</term>
|
|
<desc>
|
|
The number of messages sent to the remote NSConnection
|
|
</desc>
|
|
<term>NSConnectionLocalCount</term>
|
|
<desc>
|
|
The number of local objects currently vended
|
|
</desc>
|
|
<term>NSConnectionProxyCount</term>
|
|
<desc>
|
|
The number of remote objects currently in use
|
|
</desc>
|
|
</deflist>
|
|
</desc>
|
|
</method>
|
|
|
|
|
|
<method type="BOOL">
|
|
<sel>authenticateComponents:</sel>
|
|
<arg type="NSMutableArray*">components</arg>
|
|
<sel>withData:</sel>
|
|
<arg type="NSData*">authentication</arg>
|
|
<desc>
|
|
<p>
|
|
This is not an NSConnection method, but is a method that may
|
|
be implemented by the delegate of an NSConnection object.
|
|
</p>
|
|
<p>
|
|
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
|
|
<em>authentication</em> data to check all the NSData objects
|
|
in the <em>components</em> array (ignoring NSPort objects),
|
|
and return <code>YES</code> if they are valid, <code>NO</code>
|
|
otherwise.
|
|
</p>
|
|
<p>
|
|
If the method returns <code>NO</code> then an
|
|
NSFailedAuthentication exception will be raised.
|
|
</p>
|
|
<p>
|
|
In GNUstep the <em>components</em> array is mutable, allowing
|
|
you to replace the NSData objects with your own version.
|
|
</p>
|
|
</desc>
|
|
<standards><GNUstep/><MacOS-X/><NotOpenStep/></standards>
|
|
</method>
|
|
<method type="NSData*">
|
|
<sel>authenticationDataForComponents:</sel>
|
|
<arg type="NSMutableArray*">components</arg>
|
|
<desc>
|
|
<p>
|
|
This is not an NSConnection method, but is a method that may
|
|
be implemented by the delegate of an NSConnection object.
|
|
</p>
|
|
<p>
|
|
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 <em>components</em> array (ignoring NSPort objects),
|
|
and return the authentication data that can be used by the
|
|
remote NSConnection.
|
|
</p>
|
|
<p>
|
|
If the method returns <code>nil</code> then an
|
|
NSGenericException exception will be raised.
|
|
</p>
|
|
<p>
|
|
In GNUstep the <em>components</em> array is mutable, allowing
|
|
you to replace the NSData objects with your own version.
|
|
</p>
|
|
</desc>
|
|
<standards><GNUstep/><MacOS-X/><NotOpenStep/></standards>
|
|
</method>
|
|
<method type="BOOL" id="connection:shouldMakeNewConnection">
|
|
<sel>connection:</sel>
|
|
<arg type="NSConnection*">parentConnection</arg>
|
|
<sel>shouldMakeNewConnection:</sel>
|
|
<arg type="NSConnection*">newConnnection</arg>
|
|
<desc>
|
|
<p>
|
|
This is not an NSConnection method, but is a method that may
|
|
be implemented by the delegate of an NSConnection object.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
</desc>
|
|
<standards><GNUstep/><MacOS-X/><NotOpenStep/></standards>
|
|
</method>
|
|
<method type="BOOL">
|
|
<sel>makeNewConnection:</sel>
|
|
<arg type="NSConnection*">newConnection</arg>
|
|
<desc>
|
|
<p>
|
|
This is not an NSConnection method, but is a method that may
|
|
be implemented by the delegate of an NSConnection object.
|
|
</p>
|
|
<p>
|
|
This is the old equivalent of
|
|
<ref id="connection:shouldMakeNewConnection">
|
|
connection:shouldMakeNewConnection</ref>
|
|
and its use is now deprecated.
|
|
</p>
|
|
</desc>
|
|
<standards><OpenStep/></standards>
|
|
</method>
|
|
</class>
|
|
</chapter>
|
|
</body>
|
|
</gsdoc>
|