interface/wx/msw/registry.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        msw/registry.h
   3 // Purpose:     interface of wxRegKey
   4 // Author:      wxWidgets team
   5 // Licence:     wxWindows licence
   6 /////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxRegKey
  10
  11     wxRegKey is a class representing the Windows registry (it is only available
  12     under Windows). One can create, query and delete registry keys using this
  13     class.
  14
  15     The Windows registry is easy to understand. There are five registry keys,
  16     namely:
  17
  18     @li @c HKEY_CLASSES_ROOT (HKCR)
  19     @li @c HKEY_CURRENT_USER (HKCU)
  20     @li @c HKEY_LOCAL_MACHINE (HKLM)
  21     @li @c HKEY_CURRENT_CONFIG (HKCC)
  22     @li @c HKEY_USERS (HKU)
  23
  24     After creating a key, it can hold a value. The values can be:
  25
  26     @li String Value
  27     @li Binary Value
  28     @li DWORD Value
  29     @li Multi String Value
  30     @li Expandable String Value
  31
  32     @onlyfor{wxmsw}
  33
  34     @b Example:
  35
  36     @code
  37     // This assume that the key already exists, use HasSubKey() to check
  38     // for the key existence if necessary.
  39     wxRegKey key(wxRegKey::HKLM, "Software\\MyKey");
  40
  41     // Create a new value "MyValue" and set it to 12.
  42     key.SetValue("MyValue", 12);
  43
  44     // Read the value back.
  45     long value;
  46     key.QueryValue("MyValue", &value);
  47     wxMessageBox(wxString::Format("%d", value), "Registry Value", wxOK);
  48
  49     // Get the number of subkeys and enumerate them.
  50     size_t subkeys;
  51     key.GetKeyInfo(&subkeys, NULL, NULL, NULL);
  52
  53     wxString key_name;
  54     key.GetFirstKey(key_name, 1);
  55     for(int i = 0; i < subkeys; i++)
  56     {
  57         wxMessageBox(key_name, "Subkey Name", wxOK);
  58         key.GetNextKey(key_name, 1);
  59     }
  60     @endcode
  61
  62
  63     @library{wxbase}
  64     @category{cfg}
  65 */
  66 class wxRegKey
  67 {
  68 public:
  69     /**
  70         Default constructor, initializes to @c HKEY_CLASSES_ROOT.
  71
  72         The @a viewMode parameter is new since wxWidgets 2.9.2.
  73     */
  74     wxRegKey(WOW64ViewMode viewMode = WOW64ViewMode_Default);
  75     /**
  76         The constructor to set the full name of the key.
  77
  78         The @a viewMode parameter is new since wxWidgets 2.9.2.
  79     */
  80     wxRegKey(const wxString& strKey,
  81         WOW64ViewMode viewMode = WOW64ViewMode_Default);
  82     /**
  83         The constructor to set the full name of the key using one of the
  84         standard keys, that is, HKCR, HKCU, HKLM, HKUSR, HKPD, HKCC or HKDD.
  85         The @a viewMode parameter is new since wxWidgets 2.9.2.
  86     */
  87     wxRegKey(StdKey keyParent, const wxString& strKey,
  88         WOW64ViewMode viewMode = WOW64ViewMode_Default);
  89     /**
  90         The constructor to set the full name of the key under a previously
  91         created parent. The registry view is inherited from the parent.
  92     */
  93     wxRegKey(const wxRegKey& keyParent, const wxString& strKey);
  94
  95     /**
  96         Access modes for wxRegKey.
  97     */
  98     enum AccessMode
  99     {
 100         Read, ///< Read-only
 101         Write ///< Read and Write
 102     };
 103
 104     /**
 105         The standard registry key enumerator.
 106     */
 107     enum StdKey
 108     {
 109     HKCR,  ///< HKEY_CLASSES_ROOT
 110     HKCU,  ///< HKEY_CURRENT_USER
 111     HKLM,  ///< HKEY_LOCAL_MACHINE
 112     HKUSR, ///< HKEY_USERS
 113     HKPD,  ///< HKEY_PERFORMANCE_DATA (Windows NT and 2K only)
 114     HKCC,  ///< HKEY_CURRENT_CONFIG
 115     HKDD,  ///< HKEY_DYN_DATA (Windows 95 and 98 only)
 116     HKMAX
 117     };
 118
 119     /**
 120         The value type enumerator.
 121     */
 122     enum ValueType
 123     {
 124     Type_None,                ///< No value type
 125     Type_String,              ///< Unicode null-terminated string
 126     Type_Expand_String,       ///< Unicode null-terminated string
 127                               ///< (with environment variable references)
 128     Type_Binary,              ///< Free form binary
 129     Type_Dword,               ///< 32-bit number
 130     Type_Dword_little_endian, ///< 32-bit number (same as Type_Dword)
 131     Type_Dword_big_endian,    ///< 32-bit number
 132     Type_Link,                ///< Symbolic Link (Unicode)
 133     Type_Multi_String,        ///< Multiple Unicode strings
 134     Type_Resource_list,       ///< Resource list in the resource map
 135     Type_Full_resource_descriptor,  ///< Resource list in the hardware description
 136     Type_Resource_requirements_list ///<
 137     };
 138
 139     /**
 140         Used to determine how the registry will be viewed, either as
 141         32-bit or 64-bit.
 142
 143         @since 2.9.2
 144     */
 145     enum WOW64ViewMode
 146     {
 147         /**
 148             Uses 32-bit registry for 32-bit applications and
 149             64-bit registry for 64-bit ones.
 150         */
 151         WOW64ViewMode_Default,
 152
 153         /**
 154             Can be used in 64-bit apps to access the 32-bit registry,
 155             has no effect (i.e. treated as default) in 32-bit apps.
 156         */
 157         WOW64ViewMode_32,
 158
 159         /**
 160             Can be used in 32-bit apps to access the 64-bit registry,
 161             has no effect (i.e. treated as default) in 64-bit apps.
 162         */
 163         WOW64ViewMode_64
 164     };
 165
 166     /**
 167         Closes the key.
 168     */
 169     void Close();
 170
 171     /**
 172         Copy the entire contents of the key recursively to another location
 173         using the name. Returns @true if successful.
 174     */
 175     bool Copy(const wxString& szNewName);
 176     /**
 177         Copy the entire contents of the key recursively to another location
 178         using the key. Returns @true if successful.
 179     */
 180     bool Copy(wxRegKey& keyDst);
 181
 182     /**
 183         Copy the value to another key, possibly changing its name. By default
 184         it will remain the same. Returns @true if successful.
 185     */
 186     bool CopyValue(const wxString& szValue, wxRegKey& keyDst,
 187                   const wxString& szNewName = wxEmptyString);
 188     /**
 189         Creates the key. Will fail if the key already exists and @a bOkIfExists
 190         is @false. Returns @true if successful.
 191     */
 192     bool Create(bool bOkIfExists = true);
 193
 194     /**
 195         Deletes the subkey with all its subkeys and values recursively.
 196     */
 197     void DeleteKey(const wxString& szKey);
 198
 199     /**
 200         Deletes this key and all its subkeys and values recursively.
 201     */
 202     void DeleteSelf();
 203
 204     /**
 205         Deletes the named value or use an empty string argument to remove the
 206         default value of the key.
 207     */
 208     void DeleteValue(const wxString& szKey);
 209
 210     /**
 211         Returns @true if the key exists.
 212     */
 213     bool Exists() const;
 214
 215     /**
 216         Write the contents of this key and all its subkeys to the given file.
 217         (The file will not be overwritten; it's an error if it already exists.)
 218         Note that we export the key in REGEDIT4 format, not RegSaveKey() binary
 219         format nor the newer REGEDIT5. Returns @true if successful.
 220     */
 221     bool Export(const wxString& filename) const;
 222     /**
 223         Write the contents of this key and all its subkeys to the opened stream.
 224         Returns @true if successful.
 225     */
 226     bool Export(wxOutputStream& ostr) const;
 227
 228     /**
 229         Gets the first key. Returns @true if successful.
 230     */
 231     bool GetFirstKey(wxString& strKeyName, long& lIndex);
 232
 233     /**
 234         Gets the first value of this key. Returns @true if successful.
 235     */
 236     bool GetFirstValue(wxString& strValueName, long& lIndex);
 237
 238     /**
 239         Gets information about the key. Returns @true if successful.
 240
 241         @param pnSubKeys
 242             The number of subkeys.
 243         @param pnMaxKeyLen
 244             The maximum length of the subkey name.
 245         @param pnValues
 246             The number of values.
 247         @param pnMaxValueLen
 248             The maximum length of a value.
 249     */
 250     bool GetKeyInfo(size_t* pnSubKeys, size_t* pnMaxKeyLen,
 251                     size_t* pnValues, size_t* pnMaxValueLen) const;
 252
 253     /**
 254         Gets the name of the registry key.
 255     */
 256     wxString GetName(bool bShortPrefix = true) const;
 257
 258     /**
 259         Retrieves the registry view used by this key.
 260
 261         @since 2.9.2
 262
 263         @return The registry view given at the object's construction.
 264     */
 265     WOW64ViewMode GetView() const { return m_viewMode; }
 266
 267     /**
 268         Gets the next key. Returns @true if successful.
 269     */
 270     bool GetNextKey(wxString& strKeyName, long& lIndex) const;
 271
 272     /**
 273         Gets the next key value for this key. Returns @true if successful.
 274     */
 275     bool GetNextValue(wxString& strValueName, long& lIndex) const;
 276
 277     /**
 278         Gets the value type.
 279     */
 280     ValueType GetValueType(const wxString& szValue) const;
 281
 282     /**
 283         Returns @true if given subkey exists.
 284     */
 285     bool HasSubKey(const wxString& szKey) const;
 286
 287     /**
 288         Returns @true if any subkeys exist.
 289     */
 290     bool HasSubkeys() const;
 291
 292     /**
 293         Returns @true if the value exists.
 294     */
 295     bool HasValue(const wxString& szValue) const;
 296
 297     /**
 298         Returns @true if any values exist.
 299     */
 300     bool HasValues() const;
 301
 302     /**
 303         Returns @true if this key is empty, nothing under this key.
 304     */
 305     bool IsEmpty() const;
 306
 307     /**
 308         Returns @true if the value contains a number.
 309     */
 310     bool IsNumericValue(const wxString& szValue) const;
 311
 312     /**
 313         Returns @true if the key is opened.
 314     */
 315     bool IsOpened() const;
 316
 317     /**
 318         Explicitly opens the key. This method also allows the key to be opened
 319         in read-only mode by passing wxRegKey::Read instead of default
 320         wxRegKey::Write parameter. Returns @true if successful.
 321     */
 322     bool Open(AccessMode mode = Write);
 323
 324     /**
 325         Assignment operator to set the default value of the key.
 326     */
 327     wxRegKey& operator=(const wxString& strValue);
 328
 329     /**
 330         Return the default value of the key.
 331     */
 332     wxString QueryDefaultValue() const;
 333
 334     /**
 335         Retrieves the raw string value. Returns @true if successful.
 336         An empty @a szValue queries the default/unnamed key value.
 337     */
 338     bool QueryRawValue(const wxString& szValue, wxString& strValue) const;
 339
 340     /**
 341         Retrieves the raw or expanded string value. Returns @true if successful.
 342         An empty @a szValue queries the default/unnamed key value.
 343     */
 344     bool QueryValue(const wxString& szValue, wxString& strValue, bool raw) const;
 345
 346     /**
 347         Retrieves the numeric value. Returns @true if successful.
 348         An empty @a szValue queries the default/unnamed key value.
 349     */
 350     bool QueryValue(const wxString& szValue, long* plValue) const;
 351
 352     /**
 353         Retrieves the binary structure. Returns @true if successful.
 354         An empty @a szValue queries the default/unnamed key value.
 355     */
 356     bool QueryValue(const wxString& szValue, wxMemoryBuffer& buf) const;
 357
 358     /**
 359         Renames the key. Returns @true if successful.
 360     */
 361     bool Rename(const wxString& szNewName);
 362
 363     /**
 364         Renames a value. Returns @true if successful.
 365     */
 366     bool RenameValue(const wxString& szValueOld,
 367                      const wxString& szValueNew);
 368
 369     /**
 370         Preallocate some memory for the name. For wxRegConfig usage only.
 371     */
 372     void ReserveMemoryForName(size_t bytes);
 373
 374     /**
 375         Set or change the HKEY handle.
 376     */
 377     void SetHkey(WXHKEY hKey);
 378
 379     /**
 380         Set the full key name. The name is absolute. It should start with
 381         HKEY_xxx.
 382     */
 383     void SetName(const wxString& strKey);
 384     /**
 385         Set the name relative to the parent key
 386     */
 387     void SetName(StdKey keyParent, const wxString& strKey);
 388     /**
 389         Set the name relative to the parent key
 390     */
 391     void SetName(const wxRegKey& keyParent, const wxString& strKey);
 392
 393     /**
 394         Sets the given @a szValue which must be numeric. If the value doesn't
 395         exist, it is created. Returns @true if successful.
 396         An empty @a szValue sets the default/unnamed key value.
 397     */
 398     bool SetValue(const wxString& szValue, long lValue);
 399     /**
 400         Sets the given @a szValue which must be string. If the value doesn't
 401         exist, it is created. Returns @true if successful.
 402         An empty @a szValue sets the default/unnamed key value.
 403     */
 404     bool SetValue(const wxString& szValue, const wxString& strValue);
 405     /**
 406         Sets the given @a szValue which must be binary. If the value doesn't
 407         exist, it is created. Returns @true if successful.
 408         An empty @a szValue sets the default/unnamed key value.
 409     */
 410     bool SetValue(const wxString& szValue, const wxMemoryBuffer& buf);
 411 };