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