1///////////////////////////////////////////////////////////////////////////////
2// Name:        wx/msw/registry.h
3// Purpose:     Registry classes and functions
4// Author:      Vadim Zeitlin
5// Modified by:
6// Created:     03.04.1998
7// RCS-ID:      $Id: registry.h 49563 2007-10-31 20:46:21Z VZ $
8// Copyright:   (c) 1998 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
9// Licence:     wxWindows licence
10///////////////////////////////////////////////////////////////////////////////
11
12#ifndef _WX_MSW_REGISTRY_H_
13#define _WX_MSW_REGISTRY_H_
14
15class WXDLLIMPEXP_FWD_BASE wxOutputStream;
16
17// ----------------------------------------------------------------------------
18// class wxRegKey encapsulates window HKEY handle
19// ----------------------------------------------------------------------------
20
21class WXDLLIMPEXP_BASE wxRegKey
22{
23public:
24  // NB: do _not_ change the values of elements in these enumerations!
25
26  // registry value types (with comments from winnt.h)
27  enum ValueType
28  {
29    Type_None,                       // No value type
30    Type_String,                     // Unicode nul terminated string
31    Type_Expand_String,              // Unicode nul terminated string
32                                     // (with environment variable references)
33    Type_Binary,                     // Free form binary
34    Type_Dword,                      // 32-bit number
35    Type_Dword_little_endian         // 32-bit number
36        = Type_Dword,                // (same as Type_DWORD)
37    Type_Dword_big_endian,           // 32-bit number
38    Type_Link,                       // Symbolic Link (unicode)
39    Type_Multi_String,               // Multiple Unicode strings
40    Type_Resource_list,              // Resource list in the resource map
41    Type_Full_resource_descriptor,   // Resource list in the hardware description
42    Type_Resource_requirements_list  // ???
43  };
44
45  // predefined registry keys
46  enum StdKey
47  {
48    HKCR,       // classes root
49    HKCU,       // current user
50    HKLM,       // local machine
51    HKUSR,      // users
52    HKPD,       // performance data (WinNT/2K only)
53    HKCC,       // current config
54    HKDD,       // dynamic data (Win95/98 only)
55    HKMAX
56  };
57
58  // access mode for the key
59  enum AccessMode
60  {
61      Read,     // read-only
62      Write     // read and write
63  };
64
65  // information about standard (predefined) registry keys
66    // number of standard keys
67  static const size_t nStdKeys;
68    // get the name of a standard key
69  static const wxChar *GetStdKeyName(size_t key);
70    // get the short name of a standard key
71  static const wxChar *GetStdKeyShortName(size_t key);
72    // get StdKey from root HKEY
73  static StdKey GetStdKeyFromHkey(WXHKEY hkey);
74
75  // extacts the std key prefix from the string (return value) and
76  // leaves only the part after it (i.e. modifies the string passed!)
77  static StdKey ExtractKeyName(wxString& str);
78
79  // ctors
80    // root key is set to HKCR (the only root key under Win16)
81  wxRegKey();
82    // strKey is the full name of the key (i.e. starting with HKEY_xxx...)
83  wxRegKey(const wxString& strKey);
84    // strKey is the name of key under (standard key) keyParent
85  wxRegKey(StdKey keyParent, const wxString& strKey);
86    // strKey is the name of key under (previously created) keyParent
87  wxRegKey(const wxRegKey& keyParent, const wxString& strKey);
88    // dtor closes the key
89 ~wxRegKey();
90
91  // change key (closes the previously opened key if any)
92    // the name is absolute, i.e. should start with HKEY_xxx
93  void  SetName(const wxString& strKey);
94    // the name is relative to the parent key
95  void  SetName(StdKey keyParent, const wxString& strKey);
96    // the name is relative to the parent key
97  void  SetName(const wxRegKey& keyParent, const wxString& strKey);
98    // hKey should be opened and will be closed in wxRegKey dtor
99  void  SetHkey(WXHKEY hKey);
100
101  // get infomation about the key
102    // get the (full) key name. Abbreviate std root keys if bShortPrefix.
103  wxString GetName(bool bShortPrefix = true) const;
104    // return true if the key exists
105  bool  Exists() const;
106    // get the info about key (any number of these pointers may be NULL)
107  bool  GetKeyInfo(size_t *pnSubKeys,      // number of subkeys
108                   size_t *pnMaxKeyLen,    // max len of subkey name
109                   size_t *pnValues,       // number of values
110                   size_t *pnMaxValueLen) const;
111    // return true if the key is opened
112  bool  IsOpened() const { return m_hKey != 0; }
113    // for "if ( !key ) wxLogError(...)" kind of expressions
114  operator bool()  const { return m_dwLastError == 0; }
115
116  // operations on the key itself
117    // explicitly open the key (will be automatically done by all functions
118    // which need the key to be opened if the key is not opened yet)
119  bool  Open(AccessMode mode = Write);
120    // create the key: will fail if the key already exists and !bOkIfExists
121  bool  Create(bool bOkIfExists = true);
122    // rename a value from old name to new one
123  bool  RenameValue(const wxChar *szValueOld, const wxChar *szValueNew);
124    // rename the key
125  bool  Rename(const wxChar *szNewName);
126    // copy value to another key possibly changing its name (by default it will
127    // remain the same)
128  bool  CopyValue(const wxChar *szValue, wxRegKey& keyDst,
129                  const wxChar *szNewName = NULL);
130    // copy the entire contents of the key recursively to another location
131  bool  Copy(const wxChar *szNewName);
132    // same as Copy() but using a key and not the name
133  bool  Copy(wxRegKey& keyDst);
134    // close the key (will be automatically done in dtor)
135  bool  Close();
136
137  // deleting keys/values
138    // deletes this key and all of it's subkeys/values
139  bool  DeleteSelf();
140    // deletes the subkey with all of it's subkeys/values recursively
141  bool  DeleteKey(const wxChar *szKey);
142    // deletes the named value (may be NULL to remove the default value)
143  bool  DeleteValue(const wxChar *szValue);
144
145  // access to values and subkeys
146    // get value type
147  ValueType GetValueType(const wxChar *szValue) const;
148    // returns true if the value contains a number (else it's some string)
149  bool IsNumericValue(const wxChar *szValue) const;
150
151    // assignment operators set the default value of the key
152  wxRegKey& operator=(const wxString& strValue)
153    { SetValue(NULL, strValue); return *this; }
154  wxRegKey& operator=(long lValue)
155    { SetValue(NULL, lValue); return *this; }
156
157    // query the default value of the key: implicitly or explicitly
158  wxString QueryDefaultValue() const;
159  operator wxString() const { return QueryDefaultValue(); }
160
161    // named values
162
163    // set the string value
164  bool  SetValue(const wxChar *szValue, const wxString& strValue);
165    // retrieve the string value
166  bool  QueryValue(const wxChar *szValue, wxString& strValue) const
167    { return QueryValue(szValue, strValue, false); }
168    // retrieve raw string value
169  bool  QueryRawValue(const wxChar *szValue, wxString& strValue) const
170    { return QueryValue(szValue, strValue, true); }
171    // retrieve either raw or expanded string value
172  bool  QueryValue(const wxChar *szValue, wxString& strValue, bool raw) const;
173
174    // set the numeric value
175  bool  SetValue(const wxChar *szValue, long lValue);
176    // return the numeric value
177  bool  QueryValue(const wxChar *szValue, long *plValue) const;
178    // set the binary value
179  bool  SetValue(const wxChar *szValue, const wxMemoryBuffer& buf);
180    // return the binary value
181  bool  QueryValue(const wxChar *szValue, wxMemoryBuffer& buf) const;
182
183  // query existence of a key/value
184    // return true if value exists
185  bool HasValue(const wxChar *szKey) const;
186    // return true if given subkey exists
187  bool HasSubKey(const wxChar *szKey) const;
188    // return true if any subkeys exist
189  bool HasSubkeys() const;
190    // return true if any values exist
191  bool HasValues() const;
192    // return true if the key is empty (nothing under this key)
193  bool IsEmpty() const { return !HasSubkeys() && !HasValues(); }
194
195  // enumerate values and subkeys
196  bool  GetFirstValue(wxString& strValueName, long& lIndex);
197  bool  GetNextValue (wxString& strValueName, long& lIndex) const;
198
199  bool  GetFirstKey  (wxString& strKeyName  , long& lIndex);
200  bool  GetNextKey   (wxString& strKeyName  , long& lIndex) const;
201
202  // export the contents of this key and all its subkeys to the given file
203  // (which won't be overwritten, it's an error if it already exists)
204  //
205  // note that we export the key in REGEDIT4 format, not RegSaveKey() binary
206  // format nor newer REGEDIT5 one
207  bool Export(const wxString& filename) const;
208
209  // same as above but write to the given (opened) stream
210  bool Export(wxOutputStream& ostr) const;
211
212
213  // for wxRegConfig usage only: preallocate some memory for the name
214  void ReserveMemoryForName(size_t bytes) { m_strKey.reserve(bytes); }
215
216private:
217  // common part of all ctors
218  void Init()
219  {
220    m_hKey = (WXHKEY) NULL;
221    m_dwLastError = 0;
222  }
223
224  // recursive helper for Export()
225  bool DoExport(wxOutputStream& ostr) const;
226
227  // export a single value
228  bool DoExportValue(wxOutputStream& ostr, const wxString& name) const;
229
230  // return the text representation (in REGEDIT4 format) of the value with the
231  // given name
232  wxString FormatValue(const wxString& name) const;
233
234
235  WXHKEY      m_hKey,           // our handle
236              m_hRootKey;       // handle of the top key (i.e. StdKey)
237  wxString    m_strKey;         // key name (relative to m_hRootKey)
238
239  AccessMode  m_mode;           // valid only if key is opened
240  long        m_dwLastError;    // last error (0 if none)
241
242
243  DECLARE_NO_COPY_CLASS(wxRegKey)
244};
245
246#endif // _WX_MSW_REGISTRY_H_
247
248