dep/ACE_wrappers/ace/Token_Request_Reply.h

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