Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Token_Request_Reply.h

Go to the documentation of this file.
00001 /* -*- C++ -*- */
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    Token_Request_Reply.h
00006  *
00007  *  $Id: Token_Request_Reply.h,v 1.1.1.4 2003/02/21 18:36:32 chad Exp $
00008  *
00009  *   Define the format used to exchange messages between the
00010  *   ACE_Token Server and its clients.
00011  *
00012  *
00013  *  @author Douglas C. Schmidt (schmidt@cs.wustl.edu)
00014  *  @author Tim Harrison (harrison@cs.wustl.edu)
00015  */
00016 //=============================================================================
00017 
00018 
00019 #ifndef ACE_TOKEN_REQUEST_REPLY_H
00020 #define ACE_TOKEN_REQUEST_REPLY_H
00021 #include "ace/pre.h"
00022 
00023 #include "ace/Local_Tokens.h"
00024 
00025 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00026 # pragma once
00027 #endif /* ACE_LACKS_PRAGMA_ONCE */
00028 
00029 #include "ace/Time_Value.h"
00030 
00031 #if defined (ACE_HAS_TOKENS_LIBRARY)
00032 
00033 // Specifies the size of the fixed length portion of
00034 // the Transfer structure in ACE_Token_Request
00035 #define ACE_TOKEN_REQUEST_HEADER_SIZE 40
00036 
00037 /**
00038  * @class ACE_Token_Request
00039  *
00040  * @brief Message format for delivering requests to the ACE_Token Server.
00041  *
00042  * This class is implemented to minimize data copying.
00043  * In particular, all marshaling is done in situ...
00044  */
00045 class ACE_Export ACE_Token_Request
00046 {
00047 public:
00048   /// Operation types.
00049   enum OPERATION
00050   {
00051     /// Acquire the token.
00052     ACQUIRE,
00053     /// Release the token.
00054     RELEASE,
00055     /// Renew the token.
00056     RENEW,
00057     /// Remove the token.
00058     REMOVE,
00059     // Try to acquire the token.
00060     TRY_ACQUIRE
00061   };
00062 
00063   /// Default constructor.
00064   ACE_Token_Request (void);
00065 
00066   /**
00067    * token_type - MUTEX, RWLOCK
00068    * proxy_type - MUTEX, RLOCK, WLOCK (acquires mean different things)
00069    * operation - method
00070    * token_name
00071    * client_id
00072    * options - we check USE_TIMEOUT and use the arg.
00073    */
00074   ACE_Token_Request (int token_type,
00075                      int proxy_type,
00076                      ACE_UINT32 operation,
00077                      const ACE_TCHAR token_name[],
00078                      const ACE_TCHAR client_id[],
00079                      const ACE_Synch_Options &options);
00080 
00081   /// Get the length of the encoded/decoded message.
00082   ACE_UINT32 length (void) const;
00083 
00084   /// Set the length of the encoded/decoded message.
00085   void length (ACE_UINT32);
00086 
00087   /// Get the type of proxy
00088   int proxy_type (void) const;
00089 
00090   /// Set the type of proxy
00091   void proxy_type (int proxy_type);
00092 
00093   /// Get the type of token
00094   int token_type (void) const;
00095 
00096   /// Set the type of token
00097   void token_type (int token_type);
00098 
00099   /// Get the type of the operation.
00100   ACE_UINT32 operation_type (void) const;
00101 
00102   /// Set the type of the operation.
00103   void operation_type (ACE_UINT32);
00104 
00105   /// Get the requeue position.  These should be used when renew
00106   /// is the operation type.
00107   ACE_UINT32 requeue_position (void) const;
00108 
00109   /// Set the requeue position.  These should be used when renew
00110   /// is the operation type.
00111   void requeue_position (ACE_UINT32);
00112 
00113   /// Get notify.  These should be used when acquire is the operation type.
00114   ACE_UINT32 notify (void) const;
00115 
00116   /// Set notify.  These should be used when acquire is the operation type.
00117   void notify (ACE_UINT32);
00118 
00119   // = Set/get the timeout.
00120   ACE_Synch_Options &options (void) const;
00121   void options (const ACE_Synch_Options &options);
00122 
00123   // = Set/get the name of the token and the client id.  The set
00124   // method is combined to make it easier on us.  We're copying the
00125   // names as a contiguous buffer.
00126   ACE_TCHAR *token_name (void) const;
00127   ACE_TCHAR *client_id (void) const;
00128   void token_name (const ACE_TCHAR *token_name, const ACE_TCHAR *client_id);
00129 
00130   /// Encode the message before transmission.
00131   int encode (void *&);
00132 
00133   /// Decode message after reception.  This must be called to set the
00134   /// internal options.
00135   int decode (void);
00136 
00137   /// Print out the values of the message for debugging purposes.
00138   void dump (void) const;
00139 
00140 private:
00141   // = The 5 fields in the <Transfer> struct are transmitted to the server.
00142   // The remaining 2 fields are not tranferred -- they are used only on
00143   // the server-side to simplify lookups.
00144 
00145   struct Transfer
00146   {
00147     /// Length of entire request.
00148     ACE_UINT32 length_;
00149 
00150     /// Type of the request (i.e., MUTEX, RLOCK, WLOCK...
00151     ACE_UINT32 token_type_;
00152 
00153     /// Type of the request (i.e., MUTEX, RLOCK, WLOCK...
00154     ACE_UINT32 proxy_type_;
00155 
00156     /// Type of the request (i.e., <ACQUIRE>, <RELEASE>, <RENEW>, and <REMOVE>).
00157     ACE_UINT32 operation_type_;
00158 
00159     /// this only makes sense when operation type is renew
00160     ACE_UINT32 requeue_position_;
00161 
00162     /// this only makes sense when operation type is renew
00163     ACE_UINT32 notify_;
00164 
00165     // = ACE_Synch_Options stuff
00166 
00167     /// Indicates if we should block forever.  If 1, then <secTimeout_>
00168     /// and <usecTimeout_> indicates how long we should wait.  If 0,
00169     /// then we block forever.
00170     ACE_UINT32 use_timeout_;
00171 
00172     /// Max seconds willing to wait for token if not blocking forever.
00173     ACE_UINT32 sec_;
00174 
00175     /// Max micro seconds to wait for token if not blocking forever.
00176     ACE_UINT32 usec_;
00177 
00178     /// value returned in <Token_Reply::arg>;
00179     ACE_UINT32 arg_;
00180 
00181     /// The data portion contains the <tokenName_> including a 0 terminator,
00182     /// a ':', then the <clientId> including a 0 terminator
00183     ACE_TCHAR data_[ACE_MAXTOKENNAMELEN + ACE_MAXCLIENTIDLEN + 3];
00184   } transfer_;
00185 
00186   /// Pointer to the beginning of the token name in this->data_.
00187   ACE_TCHAR *token_name_;
00188 
00189   /// Pointer to the beginning of the client id in this->data_;
00190   ACE_TCHAR *client_id_;
00191 
00192   /// Holds arg, sec, usec, etc.
00193   ACE_Synch_Options options_;
00194 };
00195 
00196 /**
00197  * @class ACE_Token_Reply
00198  *
00199  * @brief Message format for delivering replies from the ACE_Token Server.
00200  *
00201  * This class is implemented to minimize data copying.
00202  * In particular, all marshaling is done in situ...
00203  */
00204 class ACE_Export ACE_Token_Reply
00205 {
00206 public:
00207   /// Default constructor.
00208   ACE_Token_Reply (void);
00209 
00210   /// Get the length of the encoded/decoded message.
00211   ACE_UINT32 length (void) const;
00212 
00213   /// Set the length of the encoded/decoded message.
00214   void length (ACE_UINT32);
00215 
00216   /// Get the errno of a reply.
00217   ACE_UINT32 errnum (void) const;
00218 
00219   /// Set the errno of a reply.
00220   void errnum (ACE_UINT32);
00221 
00222   /// Get the arg of a reply.
00223   ACE_UINT32 arg (void) const;
00224 
00225   /// Set the arg of a reply.
00226   void arg (ACE_UINT32);
00227 
00228   /// Encode the message before transfer.
00229   int encode (void *&);
00230 
00231   /// Decode a message after reception.
00232   int decode (void);
00233 
00234   /// Print out the values of the message for debugging purposes.
00235   void dump (void) const;
00236 
00237 private:
00238   // = The 2 fields in the <Transfer> struct are transmitted to the server.
00239 
00240   struct Transfer
00241   {
00242     /// Length of entire reply.
00243     ACE_UINT32 length_;
00244 
00245     /// Indicates why error occurred if <this->type_> == <FAILURE>.
00246     /// Typical reasons include:
00247     ///   <EWOULDBLOCK> (if client requested a non-blocking check for the token).
00248     ///   <ETIME> (if the client timed out after waiting for the token).
00249     ///   <ENOLCK> (if the token lock was removed out from underneath a waiter).
00250     ///   <EACCES> (attempt to renew a token that isn't owned by the client).
00251     ACE_UINT32 errno_;
00252 
00253     /// magic cookie
00254     ACE_UINT32 arg_;
00255 
00256   } transfer_;
00257 };
00258 
00259 #endif /* ACE_HAS_TOKENS_LIBRARY */
00260 
00261 #if defined (__ACE_INLINE__)
00262 #include "ace/Token_Request_Reply.i"
00263 #endif /* __ACE_INLINE__ */
00264 
00265 #include "ace/post.h"
00266 #endif /* ACE_TOKEN_REQUEST_REPLY_H */

Generated on Mon Jun 16 11:21:58 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002