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