ACE/ace/Token_Request_Reply.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Token_Request_Reply.h
   6  *
   7  *   Define the format used to exchange messages between the
   8  *   ACE_Token Server and its clients.
   9  *
  10  *  @author Douglas C. Schmidt (d.schmidt@vanderbilt.edu)
  11  *  @author Tim Harrison (harrison@cs.wustl.edu)
  12  */
  13 //=============================================================================
  14
  15
  16 #ifndef ACE_TOKEN_REQUEST_REPLY_H
  17 #define ACE_TOKEN_REQUEST_REPLY_H
  18 #include /**/ "ace/pre.h"
  19
  20 #include "ace/Local_Tokens.h"
  21
  22 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  23 # pragma once
  24 #endif /* ACE_LACKS_PRAGMA_ONCE */
  25
  26 #if defined (ACE_HAS_TOKENS_LIBRARY)
  27
  28 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  29
  30 /// Specifies the size of the fixed length portion of
  31 /// the Transfer structure in ACE_Token_Request
  32 #define ACE_TOKEN_REQUEST_HEADER_SIZE 40
  33
  34 /**
  35  * @class ACE_Token_Request
  36  *
  37  * @brief Message format for delivering requests to the ACE_Token Server.
  38  *
  39  * This class is implemented to minimize data copying.
  40  * In particular, all marshaling is done in situ...
  41  */
  42 class ACE_Export ACE_Token_Request
  43 {
  44 public:
  45   /// Operation types.
  46   enum OPERATION
  47   {
  48     /// Acquire the token.
  49     ACQUIRE,
  50     /// Release the token.
  51     RELEASE,
  52     /// Renew the token.
  53     RENEW,
  54     /// Remove the token.
  55     REMOVE,
  56     // Try to acquire the token.
  57     TRY_ACQUIRE
  58   };
  59
  60   /// Default constructor.
  61   ACE_Token_Request (void);
  62
  63   /**
  64    * @param token_type MUTEX, RWLOCK
  65    * @param proxy_type MUTEX, RLOCK, WLOCK (acquires mean different things)
  66    * @param operation method
  67    * @param token_name
  68    * @param client_id
  69    * @param options We check USE_TIMEOUT and use the arg.
  70    */
  71   ACE_Token_Request (int token_type,
  72                      int proxy_type,
  73                      ACE_UINT32 operation,
  74                      const ACE_TCHAR token_name[],
  75                      const ACE_TCHAR client_id[],
  76                      const ACE_Synch_Options &options);
  77
  78   /// Get the length of the encoded/decoded message.
  79   ACE_UINT32 length (void) const;
  80
  81   /// Set the length of the encoded/decoded message.
  82   void length (ACE_UINT32);
  83
  84   /// Get the type of proxy
  85   int proxy_type (void) const;
  86
  87   /// Set the type of proxy
  88   void proxy_type (int proxy_type);
  89
  90   /// Get the type of token
  91   int token_type (void) const;
  92
  93   /// Set the type of token
  94   void token_type (int token_type);
  95
  96   /// Get the type of the operation.
  97   ACE_UINT32 operation_type (void) const;
  98
  99   /// Set the type of the operation.
 100   void operation_type (ACE_UINT32);
 101
 102   /// Get the requeue position.  These should be used when renew
 103   /// is the operation type.
 104   ACE_UINT32 requeue_position (void) const;
 105
 106   /// Set the requeue position.  These should be used when renew
 107   /// is the operation type.
 108   void requeue_position (ACE_UINT32);
 109
 110   /// Get notify.  These should be used when acquire is the operation type.
 111   ACE_UINT32 notify (void) const;
 112
 113   /// Set notify.  These should be used when acquire is the operation type.
 114   void notify (ACE_UINT32);
 115
 116   /// Get the timeout.
 117   ACE_Synch_Options &options (void) const;
 118
 119   /// Set the timeout.
 120   void options (const ACE_Synch_Options &options);
 121
 122   // = Set/get the name of the token and the client id.  The set
 123   // method is combined to make it easier on us.  We're copying the
 124   // names as a contiguous buffer.
 125   ACE_TCHAR *token_name (void) const;
 126   ACE_TCHAR *client_id (void) const;
 127   void token_name (const ACE_TCHAR *token_name, const ACE_TCHAR *client_id);
 128
 129   /// Encode the message before transmission.
 130   int encode (void *&);
 131
 132   /// Decode message after reception.  This must be called to set the
 133   /// internal options.
 134   int decode (void);
 135
 136   /// Print out the values of the message for debugging purposes.
 137   void dump (void) const;
 138
 139 private:
 140   // = The 5 fields in the <Transfer> struct are transmitted to the server.
 141   // The remaining 2 fields are not tranferred -- they are used only on
 142   // the server-side to simplify lookups.
 143
 144   struct Transfer
 145   {
 146     /// Length of entire request.
 147     ACE_UINT32 length_;
 148
 149     /// Type of the request (i.e., MUTEX, RLOCK, WLOCK...
 150     ACE_UINT32 token_type_;
 151
 152     /// Type of the request (i.e., MUTEX, RLOCK, WLOCK...
 153     ACE_UINT32 proxy_type_;
 154
 155     /// Type of the request (i.e., <ACQUIRE>, <RELEASE>, <RENEW>, and <REMOVE>).
 156     ACE_UINT32 operation_type_;
 157
 158     /// this only makes sense when operation type is renew
 159     ACE_UINT32 requeue_position_;
 160
 161     /// this only makes sense when operation type is renew
 162     ACE_UINT32 notify_;
 163
 164     // = ACE_Synch_Options stuff
 165
 166     /// Indicates if we should block forever.  If 1, then <secTimeout_>
 167     /// and <usecTimeout_> indicates how long we should wait.  If 0,
 168     /// then we block forever.
 169     ACE_UINT32 use_timeout_;
 170
 171     /// Max seconds willing to wait for token if not blocking forever.
 172     ACE_UINT32 sec_;
 173
 174     /// Max micro seconds to wait for token if not blocking forever.
 175     ACE_UINT32 usec_;
 176
 177     /// value returned in <Token_Reply::arg>;
 178     ACE_UINT32 arg_;
 179
 180     /// The data portion contains the <tokenName_> including a 0 terminator,
 181     /// a ':', then the <clientId> including a 0 terminator
 182     ACE_TCHAR data_[ACE_MAXTOKENNAMELEN + ACE_MAXCLIENTIDLEN + 3];
 183   } transfer_;
 184
 185   /// Pointer to the beginning of the token name in this->data_.
 186   ACE_TCHAR *token_name_;
 187
 188   /// Pointer to the beginning of the client id in this->data_;
 189   ACE_TCHAR *client_id_;
 190
 191   /// Holds arg, sec, usec, etc.
 192   ACE_Synch_Options options_;
 193 };
 194
 195 /**
 196  * @class ACE_Token_Reply
 197  *
 198  * @brief Message format for delivering replies from the ACE_Token Server.
 199  *
 200  * This class is implemented to minimize data copying.
 201  * In particular, all marshaling is done in situ...
 202  */
 203 class ACE_Export ACE_Token_Reply
 204 {
 205 public:
 206   /// Default constructor.
 207   ACE_Token_Reply (void);
 208
 209   /// Get the length of the encoded/decoded message.
 210   ACE_UINT32 length (void) const;
 211
 212   /// Set the length of the encoded/decoded message.
 213   void length (ACE_UINT32);
 214
 215   /// Get the errno of a reply.
 216   ACE_UINT32 errnum (void) const;
 217
 218   /// Set the errno of a reply.
 219   void errnum (ACE_UINT32);
 220
 221   /// Get the arg of a reply.
 222   ACE_UINT32 arg (void) const;
 223
 224   /// Set the arg of a reply.
 225   void arg (ACE_UINT32);
 226
 227   /// Encode the message before transfer.
 228   int encode (void *&);
 229
 230   /// Decode a message after reception.
 231   int decode (void);
 232
 233   /// Print out the values of the message for debugging purposes.
 234   void dump (void) const;
 235
 236 private:
 237   // = The 2 fields in the <Transfer> struct are transmitted to the server.
 238
 239   struct Transfer
 240   {
 241     /// Length of entire reply.
 242     ACE_UINT32 length_;
 243
 244     /// Indicates why error occurred if <this->type_> == <FAILURE>.
 245     /// Typical reasons include:
 246     ///   @c EWOULDBLOCK (if client requested a non-blocking check for the token).
 247     ///   @c ETIME (if the client timed out after waiting for the token).
 248     ///   <ENOLCK> (if the token lock was removed out from underneath a waiter).
 249     ///   <EACCES> (attempt to renew a token that isn't owned by the client).
 250     ACE_UINT32 errno_;
 251
 252     /// magic cookie
 253     ACE_UINT32 arg_;
 254
 255   } transfer_;
 256 };
 257
 258 ACE_END_VERSIONED_NAMESPACE_DECL
 259
 260 #if defined (__ACE_INLINE__)
 261 #include "ace/Token_Request_Reply.inl"
 262 #endif /* __ACE_INLINE__ */
 263
 264 #endif /* ACE_HAS_TOKENS_LIBRARY */
 265
 266 #include /**/ "ace/post.h"
 267 #endif /* ACE_TOKEN_REQUEST_REPLY_H */