ACE/ace/Registry.h

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