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