home *** CD-ROM | disk | FTP | other *** search
/ OpenStep 4.2J (Developer) / os42jdev.iso / NextDeveloper / OpenStepConversion / IntermediateFrameworks2 / Foundation.framework / Headers / NSConnection.h next >
Text File  |  1996-01-23  |  6KB  |  172 lines
  1. /*      NSConnection.h
  2.     Encapsulates the state of a DO circuit
  3.     Copyright 1994, NeXT Computer, Inc.
  4.     All rights reserved.
  5. */
  6.  
  7. #import <Foundation/NSObject.h>
  8. #import <Foundation/NSDate.h>
  9.  
  10. @class NSData, NSMutableData, NSDistantObject, NSException;
  11.  
  12. #if !defined(STRICT_OPENSTEP)
  13. @class NSPort;
  14. #endif /* !STRICT_OPENSTEP */
  15.  
  16. /*****************  NSConnection    **************************/
  17.  
  18. // When a connection dies, before it is deallocated, the event {name = NSConnectionDidDieNotification; sender = connection} is posted to let external clients back off the connection
  19.  
  20. /* A connection object is a bookkeeper for objects vended or received over a particular port resource.  It may not be shared by multiple threads. */
  21.  
  22. @interface NSConnection: NSObject {
  23.     @private
  24.     unsigned    isValid:1;
  25.     unsigned    isDead:1;
  26.     unsigned    isQueueing:1;
  27.     unsigned    authGen:1;
  28.     unsigned    authCheck:1;
  29.     unsigned    encryptFlag:1;
  30.     unsigned    decryptFlag:1;
  31.     unsigned    doRequest:1;
  32.     unsigned    refCount:24;
  33.     id          delegate;
  34.     id        receivePort;    // port that we decode from
  35.     id        sendPort;    // port that we encode to
  36.     void        *localProxies;
  37.     void        *remoteProxies;
  38.     id          coderClass;
  39.     NSTimeInterval    requestLimit;
  40.     NSTimeInterval    replyLimit;
  41.     id        requestModes;    // modes in which we honor requests
  42.     id          rootObject; // the "default" object for this connection
  43.     id        registerName;
  44.     id        statistics;
  45.     void    *classInfoExported;
  46.     void    *classInfoImported;
  47.     NSMutableData    *releasedProxies;
  48.     void    *reserved;
  49. }
  50.  
  51. - (NSDictionary *)statistics;    // for this connection
  52.  
  53. + (NSArray *)allConnections;   // return existing valid connections
  54.   
  55.   
  56.  // All connections register their receivePort for "server" activity in the default
  57.  // runLoop's default mode.  For activity to be honored in other modes,
  58.  // add the connection's receivePort for those modes.
  59.  
  60. + (NSConnection *)defaultConnection;
  61.   // (Establish and) provide a default per-thread connection
  62.  
  63. + (NSConnection *)connectionWithRegisteredName:(NSString *)name host:(NSString *)hostName;
  64. + (NSDistantObject *)rootProxyForConnectionWithRegisteredName:(NSString *)name host:(NSString *)hostName;
  65.   // use the MACH nmserver for name resolution. @"*" as a host implies a
  66.   // broadcast lookup for any server registered with name.  nil as host
  67.   // implies the local machine only
  68.   
  69.   // timeout values are inherited; infinite is the default
  70. - (void)setRequestTimeout:(NSTimeInterval)ti;
  71. - (NSTimeInterval)requestTimeout;
  72. - (void)setReplyTimeout:(NSTimeInterval)ti;
  73. - (NSTimeInterval)replyTimeout;
  74.  
  75. - (BOOL)registerName:(NSString *) name;
  76.   // register the receivePort with name on the local system
  77.  
  78. - (void)setRootObject:(id)anObject;  // set or replace root object served
  79. - (id)rootObject;
  80.  
  81. - (NSDistantObject *)rootProxy;
  82.   // return a NSDistantObject proxy to the root object served by this connection
  83.   
  84. - (id)setDelegate:(id)anObject;
  85. - (id)delegate;
  86.   // delegate methods are discussed below
  87.  
  88. - (void)setIndependentConversationQueueing:(BOOL)yorn;
  89. - (BOOL)independentConversationQueueing;
  90.   // default is NO
  91.   // inherited by "child" connections
  92.   // if yes, unrelated requests are queued for later processing
  93.   // this can easily cause deadlocks among peers but will protect
  94.   // state from simultaneous changes
  95.  
  96. - (BOOL)isValid;
  97.  
  98. - (void)invalidate;
  99.   // force the connection into an invalid state
  100.  
  101. - (void)addRequestMode:(NSString *)rmode;
  102. - (void)removeRequestMode:(NSString *)rmode;
  103. - (NSArray *)requestModes;
  104.  
  105. #if !defined(STRICT_OPENSTEP)
  106. + (NSConnection *)connectionWithReceivePort:(NSPort *)receivePort sendPort:(NSPort *)sendPort;
  107.    // find or build a connection
  108.  
  109. - (id)initWithReceivePort:(NSPort *)receivePort sendPort:(NSPort *)sendPort;
  110.    // designated initializer for subclassers
  111.    // the object will be deallocated and nil returned if a connection for
  112.    // this port pair already exists
  113. - (NSPort *)sendPort;
  114. - (NSPort *)receivePort;
  115. #endif /* !STRICT_OPENSTEP */
  116.  
  117. @end
  118.  
  119. extern NSString *NSConnectionReplyMode;
  120.     // the runLoop mode that DO seeks replies; use
  121.     // this to add timers or other activities that need to be processed
  122.     // while awaiting DO replies
  123.  
  124. extern NSString *NSConnectionDidDieNotification;
  125.  
  126. @interface NSObject (NSConnectionDelegateMethods)
  127.  
  128. - (BOOL)connection:(NSConnection *)ancestor shouldMakeNewConnection:(NSConnection *)conn;
  129.   // delegate should return YES to proceed.  conn is not yet entered into
  130.   // the global table, so communication cannot occur on it yet.
  131.   // conn's parameters may be reset.
  132.  
  133. - (BOOL)makeNewConnection:(NSConnection *)conn sender:(NSConnection *)ancestor;
  134.   // synonym for the above.
  135.   // Use the method -connection:shouldMakeNewConnection: in preference to
  136.   // this one.  Note: the arguments are reversed!
  137.  
  138. #if !defined(STRICT_OPENSTEP)
  139.  
  140. - (NSData *)authenticationDataForComponents:(NSArray *)components;
  141.     // If implemented, delegate should generate and return authentication data
  142.  
  143. - (BOOL)authenticateComponents:(NSArray *)components withData:(NSData *)signature;
  144.     // If implemented, delegate should verify authentication data
  145.  
  146. extern NSString *NSFailedAuthenticationException;
  147.  
  148. #endif /* !STRICT_OPENSTEP */
  149.  
  150. @end
  151.  
  152. #if !defined(STRICT_OPENSTEP)
  153.  
  154. // Asynchronous request handling
  155.  
  156. @interface NSDistantObjectRequest : NSObject
  157. - (NSInvocation *)invocation;
  158. - (NSConnection *)connection;
  159. - (void)replyWithException:(NSException *)exception;
  160.     // the result from the doreq's invocation will be returned unless
  161.     // the exception parameter is supplied (in which case the exception will
  162.     // be delivered to the requesting party).
  163. @end
  164.  
  165. @interface NSObject (NSDistantObjectRequestMethods)
  166. - (BOOL)connection:(NSConnection *)connection handleRequest:(NSDistantObjectRequest *)doreq;
  167.     // return NO if connection should disptach & return reply
  168.     // return YES if delegate will dispatch & return reply
  169. @end
  170.  
  171. #endif /* !STRICT_OPENSTEP */
  172.