dep/ACE_wrappers/ace/Registry.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    Registry.h
   6  *
   7  *  $Id: Registry.h 80826 2008-03-04 14:51:23Z wotte $
   8  *
   9  *  @author Irfan Pyarali (irfan@cs.wustl.edu)
  10  */
  11 //=============================================================================
  12
  13
  14 #ifndef ACE_REGISTRY_H
  15 #define ACE_REGISTRY_H
  16 #include /**/ "ace/pre.h"
  17
  18 #include /**/ "ace/config-all.h"
  19
  20 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  21 # pragma once
  22 #endif /* ACE_LACKS_PRAGMA_ONCE */
  23
  24 #if defined (ACE_WIN32) && !defined (ACE_LACKS_WIN32_REGISTRY)
  25 // This only works on registry-capable Win32 platforms.
  26
  27 #include "ace/Containers.h"
  28 #include "ace/SString.h"
  29
  30 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  31
  32 /**
  33  * @class ACE_Registry
  34  *
  35  * @brief A Name Server implementation
  36  *
  37  * The registry interface is inspired by the interface
  38  * specified in the CORBA Naming Service Specification.
  39  * The implementation is done through Win32 <Reg*> functions.
  40  * Other than providing an OO wrapper for the Win32 <Reg*>
  41  * functions, ACE_Registry provides an abstraction for iteration
  42  * over the elements of the Registry.
  43  */
  44 class ACE_Export ACE_Registry
  45 {
  46 public:
  47
  48   /// International string
  49   struct ACE_Export Name_Component
  50   {
  51     ACE_TString id_;
  52     ACE_TString kind_;
  53
  54     bool operator== (const Name_Component &rhs) const;
  55     bool operator!= (const Name_Component &rhs) const;
  56     // Comparison
  57   };
  58   // The <id_> field is used,
  59   // but the <kind_> field is currently ignored
  60
  61   /// A Name is an ordered collections of components (ids)
  62   typedef ACE_Unbounded_Set<Name_Component> Name;
  63
  64   /// Separator for components in a name
  65   static const ACE_TCHAR STRING_SEPARATOR[];
  66
  67   /// Convert a @a name to a @c string
  68   static ACE_TString make_string (const Name &name);
  69
  70   /// Convert a @a string to a @c name
  71   static Name make_name (const ACE_TString &string);
  72
  73   /// There are two types of bindings
  74   enum Binding_Type {INVALID, OBJECT, CONTEXT};
  75
  76   struct ACE_Export Binding
  77   {
  78     /// Empty (default) constructor
  79     Binding (void);
  80
  81     /// Constructor
  82     /// (Name version)
  83     Binding (const Name &binding_name,
  84              Binding_Type binding_type);
  85
  86     /// Constructor
  87     /// (String version)
  88     Binding (const ACE_TString &binding_name,
  89              Binding_Type binding_type);
  90
  91     bool operator== (const Binding &rhs) const;
  92     bool operator!= (const Binding &rhs) const;
  93     // Comparison
  94
  95     /// Name accessor
  96     /// (Name version)
  97     void name (Name &name);
  98
  99     /// Set Name (String version)
 100     void name (ACE_TString &name);
 101
 102     /// Get Name (String version)
 103     ACE_TString name (void);
 104
 105     /// Type accessor
 106     Binding_Type type (void);
 107
 108   private:
 109     /// A binding has a name
 110     ACE_TString name_;
 111
 112     /// .... and a type
 113     Binding_Type type_;
 114   };
 115
 116   /// A list of bindings
 117   typedef ACE_Unbounded_Set<Binding> Binding_List;
 118
 119   // Forward declaration of iterator
 120   class Binding_Iterator;
 121
 122   /**
 123    * @class Object
 124    *
 125    * @brief An object representation
 126    *
 127    * In CORBA, all objects inherit from (CORBA::Object).
 128    * For the registry, this is used as a wrapper for an
 129    * instance of a built-in data type.
 130    * Think about an object as being similar to a file
 131    * in a file system.
 132    */
 133   class ACE_Export Object
 134   {
 135   public:
 136     /// Default constructor
 137     Object (void *data = 0,
 138             u_long size = 0,
 139             u_long type = REG_NONE);
 140
 141     /// Set data
 142     void data (void *data);
 143
 144     /// Get data
 145     void *data (void) const;
 146
 147     /// Set size
 148     void size (u_long size);
 149
 150     /// Get size
 151     u_long size (void) const;
 152
 153     /// Set type
 154     void type (u_long type);
 155
 156     /// Get type
 157     u_long type (void) const;
 158
 159   private:
 160     /// Pointer to data
 161     void *data_;
 162
 163     /// Size of the data
 164     u_long size_;
 165
 166     /// Type of data
 167     u_long type_;
 168   };
 169
 170   /**
 171    * @class Naming_Context
 172    *
 173    * @brief An context representation
 174    *
 175    * Think about a context as being similar to a directory
 176    * in a file system.
 177    */
 178   class ACE_Export Naming_Context
 179   {
 180   public:
 181     /// Friend factory
 182     friend class ACE_Predefined_Naming_Contexts;
 183
 184     enum {
 185       /// Max sizes of names
 186       /// (Not too sure about this value)
 187       MAX_OBJECT_NAME_SIZE = BUFSIZ,
 188
 189       /// Max size of context name
 190       MAX_CONTEXT_NAME_SIZE = MAXPATHLEN + 1
 191     };
 192
 193     /// Empty constructor: keys will be NULL
 194     Naming_Context (void);
 195
 196     /// Constructor: key_ will be set to @a key
 197     Naming_Context (const HKEY &key);
 198
 199     /// Destructor will call <Naming_Context::close>.
 200     ~Naming_Context (void);
 201
 202     // The following interfaces are for objects
 203
 204     /**
 205      * Insert @a object with @a name into @c this context.
 206      * This will fail if @a name already exists
 207      * (Name version)
 208      */
 209     int bind_new (const Name &name,
 210                   const Object &object);
 211
 212     /**
 213      * Insert @a object with @a name into @c this context
 214      * This will fail if @a name already exists
 215      * (String version)
 216      */
 217     int bind_new (const ACE_TString &name,
 218                   const Object &object);
 219
 220     /**
 221      * Insert or update @a object with @a name into @c this context
 222      * This will not fail if @a name already exists
 223      * (Name version)
 224      */
 225     int bind (const Name &name,
 226               const Object &object);
 227
 228     /**
 229      * Insert or update <object> with @a name into @c this context
 230      * This will not fail if @a name already exists
 231      * (String version)
 232      */
 233     int bind (const ACE_TString &name,
 234               const Object &object);
 235
 236     /// Update <object> with @a name in @c this context
 237     /// (Name version)
 238     int rebind (const Name &name,
 239                 const Object &object);
 240
 241     /// Update <object> with @a name in @c this context
 242     int rebind (const ACE_TString &name,
 243                 const Object &object);
 244
 245     /// Find <object> with @a name in @c this context
 246     /// (Name version)
 247     int resolve (const Name &name,
 248                  Object &object);
 249
 250     /// Find <object> with @a name in @c this context
 251     int resolve (const ACE_TString &name,
 252                  Object &object);
 253
 254     /// Delete object with @a name in @c this context
 255     /// (Name version)
 256     int unbind (const Name &name);
 257
 258     /// Delete object with @a name in @c this context
 259     int unbind (const ACE_TString &name);
 260
 261
 262     // The following interfaces are for Naming Context
 263
 264     /// Create new @c naming_context
 265     int new_context (Naming_Context &naming_context);
 266
 267     /**
 268      * Insert <naming_context> with @a name relative to @c this context
 269      * This will fail if @a name already exists
 270      * (Name version)
 271      */
 272     int bind_new_context (const Name &name,
 273                           Naming_Context &naming_context,
 274                           u_long persistence = REG_OPTION_NON_VOLATILE,
 275                           u_long security_access = KEY_ALL_ACCESS,
 276                           LPSECURITY_ATTRIBUTES security_attributes = 0);
 277
 278     /// Insert <naming_context> with @a name relative to @c this context
 279     /// This will fail if @a name already exists
 280     int bind_new_context (const ACE_TString &name,
 281                           Naming_Context &naming_context,
 282                           u_long persistence = REG_OPTION_NON_VOLATILE,
 283                           u_long security_access = KEY_ALL_ACCESS,
 284                           LPSECURITY_ATTRIBUTES security_attributes = 0);
 285
 286     /**
 287      * Insert or update <naming_context> with @a name relative to @c this context
 288      * This will not fail if @a name already exists
 289      * (Name version)
 290      */
 291     int bind_context (const Name &name,
 292                       /* const */ Naming_Context &naming_context,
 293                       u_long persistence = REG_OPTION_NON_VOLATILE,
 294                       u_long security_access = KEY_ALL_ACCESS,
 295                       LPSECURITY_ATTRIBUTES security_attributes = 0);
 296
 297     /// Insert or update <naming_context> with @a name relative to @c this context
 298     /// This will not fail if @a name already exists
 299     int bind_context (const ACE_TString &name,
 300                       /* const */ Naming_Context &naming_context,
 301                       u_long persistence = REG_OPTION_NON_VOLATILE,
 302                       u_long security_access = KEY_ALL_ACCESS,
 303                       LPSECURITY_ATTRIBUTES security_attributes = 0);
 304
 305     /// Rename <naming_context> to @a name
 306     /// (Name version)
 307     int rebind_context (const Name &name,
 308                         /* const */ Naming_Context &naming_context);
 309
 310     /// Rename <naming_context> to @a name
 311     int rebind_context (const ACE_TString &name,
 312                         /* const */ Naming_Context &naming_context);
 313
 314     /// Find <naming_context> with @a name in @c this context
 315     /// (Name version)
 316     int resolve_context (const Name &name,
 317                          Naming_Context &naming_context,
 318                          u_long security_access = KEY_ALL_ACCESS);
 319
 320     /// Find <naming_context> with @a name in @c this context
 321     int resolve_context (const ACE_TString &name,
 322                          Naming_Context &naming_context,
 323                          u_long security_access = KEY_ALL_ACCESS);
 324
 325     /// Remove naming_context with @a name from @c this context
 326     /// (Name version)
 327     int unbind_context (const Name &name);
 328
 329     /// Remove naming_context with @a name from @c this context
 330     int unbind_context (const ACE_TString &name);
 331
 332     /// Same as <unbind_context> with @c this as naming_context
 333     int destroy (void);
 334
 335     /**
 336      * listing function: iterator creator
 337      * This is useful when there are many objects and contexts
 338      * in @c this context and you only want to look at a few entries
 339      * at a time
 340      */
 341     int list (u_long how_many,
 342               Binding_List &list,
 343               Binding_Iterator &iterator);
 344
 345     /// listing function: iterator creator
 346     /// This gives back a listing of all entries in @c this context.
 347     int list (Binding_List &list);
 348
 349     // Some other necessary functions which are
 350     // not part of the CORBA interface
 351
 352     /// Sync content of context to disk
 353     int flush (void);
 354
 355     /// Close the handle of the context
 356     /// @note <close> does not call <flush>
 357     int close (void);
 358
 359     // Accessors
 360
 361     /// Get key
 362     HKEY key (void);
 363
 364     // void parent (HKEY parent);
 365     /// Get parent
 366     HKEY parent (void);
 367
 368     /// Get name
 369     /// (Name version)
 370     void name (Name &name);
 371
 372     /// Set name (String version)
 373     void name (ACE_TString &name);
 374
 375     /// Get name (String version)
 376     ACE_TString name (void);
 377
 378   protected:
 379     /// Set key
 380     void key (HKEY key);
 381
 382     /// Set parent
 383     void parent (HKEY parent);
 384
 385     /// Set name
 386     /// (Name version)
 387     void name (const Name &name);
 388
 389     /// Set name
 390     /// (String version)
 391     void name (const ACE_TString &name);
 392
 393   private:
 394     /// Disallow copy constructors
 395     Naming_Context (const Naming_Context &rhs);
 396
 397     /// Disallow assignment
 398     const Naming_Context &operator= (const Naming_Context &rhs);
 399
 400     /// Key for self
 401     HKEY key_;
 402
 403     /// Key for parent
 404     HKEY parent_key_;
 405
 406     /// Name of self
 407     ACE_TString name_;
 408   };
 409
 410   /**
 411    * @class Binding_Iterator
 412    *
 413    * @brief An iterator
 414    *
 415    * Useful when iteratorating over a few entries at a time
 416    */
 417   class ACE_Export Binding_Iterator
 418   {
 419   public:
 420     /// Friend factory
 421     friend class Naming_Context;
 422
 423     /// Default constructor
 424     Binding_Iterator (void);
 425
 426     /// Next entry
 427     int next_one (Binding &binding);
 428
 429     /// Next <how_many> entries
 430     int next_n (u_long how_many,
 431                 Binding_List &list);
 432
 433     /// Cleanup
 434     int destroy (void);
 435
 436     /// Reset the internal state of the iterator
 437     void reset (void);
 438
 439     /// Get naming_context that the iterator is iterating over
 440     Naming_Context &naming_context (void);
 441
 442   private:
 443
 444     /// Set naming_context that the iterator is iterating over
 445     void naming_context (Naming_Context& naming_context);
 446
 447     /// Reference to context
 448     Naming_Context *naming_context_;
 449
 450   public:
 451     // This should really be private
 452     // But the compiler is broken
 453
 454     /**
 455      * @class Iteration_State
 456      *
 457      * Base class for state
 458      */
 459     class ACE_Export Iteration_State
 460       {
 461       public:
 462         /// Constructor
 463         Iteration_State ();
 464
 465         /// Set the iterator reference.
 466         void iterator (Binding_Iterator *iterator);
 467
 468         /// Next <how_many> entries
 469         virtual int next_n (u_long how_many,
 470                             Binding_List &list) = 0;
 471
 472         /// Reset state
 473         void reset (void);
 474
 475       protected:
 476         /// Pointer to parent iterator
 477         Binding_Iterator *parent_;
 478
 479         u_long index_;
 480       };
 481
 482   private:
 483     class ACE_Export Object_Iteration : public Iteration_State
 484       {
 485         /// Next <how_many> entries
 486         int next_n (u_long how_many,
 487                     Binding_List &list);
 488       };
 489
 490     class ACE_Export Context_Iteration : public Iteration_State
 491       {
 492       public:
 493         /// Next @a how_many entries
 494         int next_n (u_long how_many,
 495                     Binding_List &list);
 496       };
 497
 498     class ACE_Export Iteration_Complete : public Iteration_State
 499       {
 500       public:
 501         /// Next @a how_many entries
 502         int next_n (u_long how_many,
 503                     Binding_List &list);
 504       };
 505
 506     /// Friend states
 507     friend class Iteration_State;
 508     friend class Object_Iteration;
 509     friend class Context_Iteration;
 510     friend class Iteration_Complete;
 511
 512     /// Instances of all states
 513     Object_Iteration object_iteration_;
 514     Context_Iteration context_iteration_;
 515     Iteration_Complete iteration_complete_;
 516
 517     /// Pointer to current state
 518     Iteration_State *current_enumeration_;
 519
 520     /// Set current_enumeration
 521     void current_enumeration (Iteration_State& current_enumeration);
 522
 523     /// Get current_enumeration
 524     Iteration_State &current_enumeration (void);
 525   };
 526 };
 527
 528 /**
 529  * @class ACE_Predefined_Naming_Contexts
 530  *
 531  * @brief A factory for predefined registries, which exist by default
 532  * on Win32 platforms
 533  *
 534  * This factory can connect to both local and remote
 535  * predefined registries.
 536  */
 537 class ACE_Export ACE_Predefined_Naming_Contexts
 538 {
 539 public:
 540   /**
 541    * Factory method for connecting to predefined registries.  This
 542    * method works for both remote and local machines.  However, for
 543    * remote machines, HKEY_CLASSES_ROOT and HKEY_CURRENT_USER types
 544    * are not allowed
 545    */
 546   static int connect (ACE_Registry::Naming_Context &naming_context,
 547                       HKEY predefined = HKEY_LOCAL_MACHINE,
 548                       const ACE_TCHAR *machine_name = 0);
 549
 550 private:
 551   /// Check if @a machine_name is the local host
 552   static int is_local_host (const ACE_TCHAR *machine_name);
 553 };
 554
 555 ACE_END_VERSIONED_NAMESPACE_DECL
 556
 557 #endif /* ACE_WIN32 && !ACE_LACKS_WIN32_REGISTRY */
 558 #include /**/ "ace/post.h"
 559 #endif /* ACE_REGISTRY_H */