interface/wx/msw/registry.h

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