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 license
   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     wxRegKey();
  76     /**
  77         The constructor to set the full name of the key.
  78     */
  79     wxRegKey(const wxString& strKey);
  80     /**
  81         The constructor to set the full name of the key using one of the
  82         standard keys, that is, HKCR, HKCU, HKLM, HKUSR, HKPD, HKCC or HKDD.
  83     */
  84     wxRegKey(StdKey keyParent, const wxString& strKey);
  85     /**
  86         The constructor to set the full name of the key under a previously created
  87         parent.
  88     */
  89     wxRegKey(const wxRegKey& keyParent, const wxString& strKey);
  90
  91     /**
  92         Access modes for wxRegKey.
  93     */
  94     enum AccessMode
  95     {
  96         Read, ///< Read-only
  97         Write ///< Read and Write
  98     };
  99
 100     /**
 101         The standard registry key enumerator.
 102     */
 103     enum StdKey
 104     {
 105     HKCR,  ///< HKEY_CLASSES_ROOT
 106     HKCU,  ///< HKEY_CURRENT_USER
 107     HKLM,  ///< HKEY_LOCAL_MACHINE
 108     HKUSR, ///< HKEY_USERS
 109     HKPD,  ///< HKEY_PERFORMANCE_DATA (Windows NT and 2K only)
 110     HKCC,  ///< HKEY_CURRENT_CONFIG
 111     HKDD,  ///< HKEY_DYN_DATA (Windows 95 and 98 only)
 112     HKMAX
 113     };
 114
 115     /**
 116         The value type enumerator.
 117     */
 118     enum ValueType
 119     {
 120     Type_None,                ///< No value type
 121     Type_String,              ///< Unicode null-terminated string
 122     Type_Expand_String,       ///< Unicode null-terminated string
 123                               ///< (with environment variable references)
 124     Type_Binary,              ///< Free form binary
 125     Type_Dword,               ///< 32-bit number
 126     Type_Dword_little_endian, ///< 32-bit number (same as Type_Dword)
 127     Type_Dword_big_endian,    ///< 32-bit number
 128     Type_Link,                ///< Symbolic Link (Unicode)
 129     Type_Multi_String,        ///< Multiple Unicode strings
 130     Type_Resource_list,       ///< Resource list in the resource map
 131     Type_Full_resource_descriptor,  ///< Resource list in the hardware description
 132     Type_Resource_requirements_list ///<
 133     };
 134
 135     /**
 136         Closes the key.
 137     */
 138     void Close();
 139
 140     /**
 141         Copy the entire contents of the key recursively to another location
 142         using the name. Returns @true if successful.
 143     */
 144     bool Copy(const wxString& szNewName);
 145     /**
 146         Copy the entire contents of the key recursively to another location
 147         using the key. Returns @true if successful.
 148     */
 149     bool Copy(wxRegKey& keyDst);
 150
 151     /**
 152         Copy the value to another key, possibly changing its name. By default
 153         it will remain the same. Returns @true if successful.
 154     */
 155     bool CopyValue(const wxString& szValue, wxRegKey& keyDst,
 156                   const wxString& szNewName = wxEmptyString);
 157     /**
 158         Creates the key. Will fail if the key already exists and @a bOkIfExists
 159         is @false. Returns @true if successful.
 160     */
 161     bool Create(bool bOkIfExists = true);
 162
 163     /**
 164         Deletes the subkey with all its subkeys and values recursively.
 165     */
 166     void DeleteKey(const wxString& szKey);
 167
 168     /**
 169         Deletes this key and all its subkeys and values recursively.
 170     */
 171     void DeleteSelf();
 172
 173     /**
 174         Deletes the named value or use an empty string argument to remove the
 175         default value of the key.
 176     */
 177     void DeleteValue(const wxString& szKey);
 178
 179     /**
 180         Returns @true if the key exists.
 181     */
 182     bool Exists() const;
 183
 184     /**
 185         Write the contents of this key and all its subkeys to the given file.
 186         (The file will not be overwritten; it's an error if it already exists.)
 187         Note that we export the key in REGEDIT4 format, not RegSaveKey() binary
 188         format nor the newer REGEDIT5. Returns @true if successful.
 189     */
 190     bool Export(const wxString& filename) const;
 191     /**
 192         Write the contents of this key and all its subkeys to the opened stream.
 193         Returns @true if successful.
 194     */
 195     bool Export(wxOutputStream& ostr) const;
 196
 197     /**
 198         Gets the first key. Returns @true if successful.
 199     */
 200     bool GetFirstKey(wxString& strKeyName, long& lIndex);
 201
 202     /**
 203         Gets the first value of this key. Returns @true if successful.
 204     */
 205     bool GetFirstValue(wxString& strValueName, long& lIndex);
 206
 207     /**
 208         Gets information about the key. Returns @true if successful.
 209
 210         @param pnSubKeys
 211             The number of subkeys.
 212         @param pnMaxKeyLen
 213             The maximum length of the subkey name.
 214         @param pnValues
 215             The number of values.
 216         @param pnMaxValueLen
 217             The maximum length of a value.
 218     */
 219     bool GetKeyInfo(size_t* pnSubKeys, size_t* pnMaxKeyLen,
 220                     size_t* pnValues, size_t* pnMaxValueLen) const;
 221
 222     /**
 223         Gets the name of the registry key.
 224     */
 225     wxString GetName(bool bShortPrefix = true) const;
 226
 227     /**
 228         Gets the next key. Returns @true if successful.
 229     */
 230     bool GetNextKey(wxString& strKeyName, long& lIndex) const;
 231
 232     /**
 233         Gets the next key value for this key. Returns @true if successful.
 234     */
 235     bool GetNextValue(wxString& strValueName, long& lIndex) const;
 236
 237     /**
 238         Gets the value type.
 239     */
 240     ValueType GetValueType(const wxString& szValue) const;
 241
 242     /**
 243         Returns @true if given subkey exists.
 244     */
 245     bool HasSubKey(const wxString& szKey) const;
 246
 247     /**
 248         Returns @true if any subkeys exist.
 249     */
 250     bool HasSubKeys() const;
 251
 252     /**
 253         Returns @true if the value exists.
 254     */
 255     bool HasValue(const wxString& szValue) const;
 256
 257     /**
 258         Returns @true if any values exist.
 259     */
 260     bool HasValues() const;
 261
 262     /**
 263         Returns @true if this key is empty, nothing under this key.
 264     */
 265     bool IsEmpty() const;
 266
 267     /**
 268         Returns @true if the value contains a number.
 269     */
 270     bool IsNumericValue(const wxString& szValue) const;
 271
 272     /**
 273         Returns @true if the key is opened.
 274     */
 275     bool IsOpened() const;
 276
 277     /**
 278         Explicitly opens the key. This method also allows the key to be opened
 279         in read-only mode by passing wxRegKey::Read instead of default
 280         wxRegKey::Write parameter. Returns @true if successful.
 281     */
 282     bool Open(AccessMode mode = Write);
 283
 284     /**
 285         Assignment operator to set the default value of the key.
 286     */
 287     wxRegKey& operator=(const wxString& strValue);
 288
 289     /**
 290         Return the default value of the key.
 291     */
 292     wxString QueryDefaultValue() const;
 293
 294     /**
 295         Retrieves the raw string value. Returns @true if successful.
 296         An empty @a szValue queries the default/unnamed key value.
 297     */
 298     bool QueryRawValue(const wxString& szValue, wxString& strValue) const;
 299
 300     /**
 301         Retrieves the raw or expanded string value. Returns @true if successful.
 302         An empty @a szValue queries the default/unnamed key value.
 303     */
 304     bool QueryValue(const wxString& szValue, wxString& strValue, bool raw) const;
 305
 306     /**
 307         Retrieves the numeric value. Returns @true if successful.
 308         An empty @a szValue queries the default/unnamed key value.
 309     */
 310     bool QueryValue(const wxString& szValue, long* plValue) const;
 311
 312     /**
 313         Retrieves the binary structure. Returns @true if successful.
 314         An empty @a szValue queries the default/unnamed key value.
 315     */
 316     bool QueryValue(const wxString& szValue, wxMemoryBuffer& buf) const;
 317
 318     /**
 319         Renames the key. Returns @true if successful.
 320     */
 321     bool Rename(const wxString& szNewName);
 322
 323     /**
 324         Renames a value. Returns @true if successful.
 325     */
 326     bool RenameValue(const wxString& szValueOld,
 327                      const wxString& szValueNew);
 328
 329     /**
 330         Preallocate some memory for the name. For wxRegConfig usage only.
 331     */
 332     void ReserveMemoryForName(size_t bytes);
 333
 334     /**
 335         Set or change the HKEY handle.
 336     */
 337     void SetHkey(WXHKEY hKey);
 338
 339     /**
 340         Set the full key name. The name is absolute. It should start with
 341         HKEY_xxx.
 342     */
 343     void SetName(const wxString& strKey);
 344     /**
 345         Set the name relative to the parent key
 346     */
 347     void SetName(StdKey keyParent, const wxString& strKey);
 348     /**
 349         Set the name relative to the parent key
 350     */
 351     void SetName(const wxRegKey& keyParent, const wxString& strKey);
 352
 353     /**
 354         Sets the given @a szValue which must be numeric. If the value doesn't
 355         exist, it is created. Returns @true if successful.
 356         An empty @a szValue sets the default/unnamed key value.
 357     */
 358     bool SetValue(const wxString& szValue, long lValue);
 359     /**
 360         Sets the given @a szValue which must be string. If the value doesn't
 361         exist, it is created. Returns @true if successful.
 362         An empty @a szValue sets the default/unnamed key value.
 363     */
 364     bool SetValue(const wxString& szValue, const wxString& strValue);
 365     /**
 366         Sets the given @a szValue which must be binary. If the value doesn't
 367         exist, it is created. Returns @true if successful.
 368         An empty @a szValue sets the default/unnamed key value.
 369     */
 370     bool SetValue(const wxString& szValue, const wxMemoryBuffer& buf);
 371 };