]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/msw/registry.h
Implement wx-prefixed macros versions of DECLARE/IMPLEMENT_APP_* macros.
[wxWidgets.git] / interface / wx / msw / registry.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: msw/registry.h
e54c96f1 3// Purpose: interface of wxRegKey
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxRegKey
7c913512 11
23324ae1
FM
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.
7c913512 15
23324ae1
FM
16 The Windows registry is easy to understand. There are five registry keys,
17 namely:
7c913512 18
9602ce3d
BP
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)
7c913512 24
23324ae1 25 After creating a key, it can hold a value. The values can be:
7c913512 26
bbc5b7f8
BP
27 @li String Value
28 @li Binary Value
29 @li DWORD Value
30 @li Multi String Value
31 @li Expandable String Value
7c913512 32
d9faa1fe 33 @onlyfor{wxmsw}
7c913512 34
bbc5b7f8
BP
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
3c99e2fd
FM
64
65
66 @library{wxbase}
67 @category{cfg}
23324ae1 68*/
7c913512 69class wxRegKey
23324ae1
FM
70{
71public:
23324ae1 72 /**
9602ce3d 73 Default constructor, initializes to @c HKEY_CLASSES_ROOT.
23324ae1
FM
74 */
75 wxRegKey();
bbc5b7f8
BP
76 /**
77 The constructor to set the full name of the key.
78 */
7c913512 79 wxRegKey(const wxString& strKey);
69e037ac 80 /**
3c99e2fd 81 The constructor to set the full name of the key using one of the
69e037ac
VZ
82 standard keys, that is, HKCR, HKCU, HKLM, HKUSR, HKPD, HKCC or HKDD.
83 */
84 wxRegKey(StdKey keyParent, const wxString& strKey);
bbc5b7f8
BP
85 /**
86 The constructor to set the full name of the key under a previously created
87 parent.
88 */
7c913512 89 wxRegKey(const wxRegKey& keyParent, const wxString& strKey);
bbc5b7f8
BP
90
91 /**
92 Access modes for wxRegKey.
93 */
94 enum AccessMode
95 {
69e037ac
VZ
96 Read, ///< Read-only
97 Write ///< Read and Write
98 };
99
3c99e2fd 100 /**
69e037ac
VZ
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
3c99e2fd 132 Type_Resource_requirements_list ///<
bbc5b7f8 133 };
23324ae1
FM
134
135 /**
136 Closes the key.
137 */
138 void Close();
139
69e037ac
VZ
140 /**
141 Copy the entire contents of the key recursively to another location
a90280fe 142 using the name. Returns @true if successful.
69e037ac
VZ
143 */
144 bool Copy(const wxString& szNewName);
145 /**
146 Copy the entire contents of the key recursively to another location
a90280fe 147 using the key. Returns @true if successful.
69e037ac
VZ
148 */
149 bool Copy(wxRegKey& keyDst);
3c99e2fd 150
69e037ac
VZ
151 /**
152 Copy the value to another key, possibly changing its name. By default
a90280fe 153 it will remain the same. Returns @true if successful.
69e037ac 154 */
3c99e2fd 155 bool CopyValue(const wxString& szValue, wxRegKey& keyDst,
69e037ac 156 const wxString& szNewName = wxEmptyString);
23324ae1 157 /**
a90280fe
BP
158 Creates the key. Will fail if the key already exists and @a bOkIfExists
159 is @false. Returns @true if successful.
23324ae1 160 */
4cc4bfaf 161 bool Create(bool bOkIfExists = true);
23324ae1
FM
162
163 /**
a90280fe 164 Deletes the subkey with all its subkeys and values recursively.
23324ae1 165 */
920b92a3 166 void DeleteKey(const wxString& szKey);
23324ae1
FM
167
168 /**
a90280fe 169 Deletes this key and all its subkeys and values recursively.
23324ae1
FM
170 */
171 void DeleteSelf();
172
173 /**
3c99e2fd 174 Deletes the named value or use an empty string argument to remove the
a90280fe 175 default value of the key.
23324ae1 176 */
920b92a3 177 void DeleteValue(const wxString& szKey);
23324ae1
FM
178
179 /**
180 Returns @true if the key exists.
181 */
bbc5b7f8 182 bool Exists() const;
23324ae1 183
69e037ac
VZ
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
a90280fe 188 format nor the newer REGEDIT5. Returns @true if successful.
69e037ac
VZ
189 */
190 bool Export(const wxString& filename) const;
191 /**
192 Write the contents of this key and all its subkeys to the opened stream.
a90280fe 193 Returns @true if successful.
69e037ac
VZ
194 */
195 bool Export(wxOutputStream& ostr) const;
3c99e2fd 196
23324ae1 197 /**
a90280fe 198 Gets the first key. Returns @true if successful.
23324ae1
FM
199 */
200 bool GetFirstKey(wxString& strKeyName, long& lIndex);
201
202 /**
a90280fe 203 Gets the first value of this key. Returns @true if successful.
23324ae1
FM
204 */
205 bool GetFirstValue(wxString& strValueName, long& lIndex);
206
207 /**
a90280fe 208 Gets information about the key. Returns @true if successful.
d9faa1fe 209
7c913512 210 @param pnSubKeys
4cc4bfaf 211 The number of subkeys.
7c913512 212 @param pnMaxKeyLen
4cc4bfaf 213 The maximum length of the subkey name.
7c913512 214 @param pnValues
4cc4bfaf 215 The number of values.
7c913512 216 @param pnMaxValueLen
4cc4bfaf 217 The maximum length of a value.
23324ae1 218 */
bbc5b7f8
BP
219 bool GetKeyInfo(size_t* pnSubKeys, size_t* pnMaxKeyLen,
220 size_t* pnValues, size_t* pnMaxValueLen) const;
23324ae1
FM
221
222 /**
223 Gets the name of the registry key.
224 */
328f5751 225 wxString GetName(bool bShortPrefix = true) const;
23324ae1
FM
226
227 /**
a90280fe 228 Gets the next key. Returns @true if successful.
23324ae1 229 */
328f5751 230 bool GetNextKey(wxString& strKeyName, long& lIndex) const;
23324ae1
FM
231
232 /**
a90280fe 233 Gets the next key value for this key. Returns @true if successful.
23324ae1 234 */
328f5751 235 bool GetNextValue(wxString& strValueName, long& lIndex) const;
23324ae1 236
69e037ac
VZ
237 /**
238 Gets the value type.
239 */
240 ValueType GetValueType(const wxString& szValue) const;
3c99e2fd 241
23324ae1
FM
242 /**
243 Returns @true if given subkey exists.
244 */
920b92a3 245 bool HasSubKey(const wxString& szKey) const;
23324ae1
FM
246
247 /**
248 Returns @true if any subkeys exist.
249 */
328f5751 250 bool HasSubKeys() const;
23324ae1
FM
251
252 /**
253 Returns @true if the value exists.
254 */
920b92a3 255 bool HasValue(const wxString& szValue) const;
23324ae1
FM
256
257 /**
258 Returns @true if any values exist.
259 */
328f5751 260 bool HasValues() const;
23324ae1
FM
261
262 /**
263 Returns @true if this key is empty, nothing under this key.
264 */
328f5751 265 bool IsEmpty() const;
23324ae1 266
69e037ac 267 /**
a90280fe 268 Returns @true if the value contains a number.
69e037ac
VZ
269 */
270 bool IsNumericValue(const wxString& szValue) const;
271
23324ae1
FM
272 /**
273 Returns @true if the key is opened.
274 */
328f5751 275 bool IsOpened() const;
23324ae1
FM
276
277 /**
a90280fe
BP
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.
23324ae1
FM
281 */
282 bool Open(AccessMode mode = Write);
283
a90280fe
BP
284 /**
285 Assignment operator to set the default value of the key.
286 */
287 wxRegKey& operator=(const wxString& strValue);
288
23324ae1 289 /**
69e037ac
VZ
290 Return the default value of the key.
291 */
292 wxString QueryDefaultValue() const;
293
294 /**
a90280fe 295 Retrieves the raw string value. Returns @true if successful.
3a326bfe 296 An empty @a szValue queries the default/unnamed key value.
23324ae1 297 */
69e037ac
VZ
298 bool QueryRawValue(const wxString& szValue, wxString& strValue) const;
299
300 /**
a90280fe 301 Retrieves the raw or expanded string value. Returns @true if successful.
3a326bfe 302 An empty @a szValue queries the default/unnamed key value.
69e037ac
VZ
303 */
304 bool QueryValue(const wxString& szValue, wxString& strValue, bool raw) const;
bbc5b7f8
BP
305
306 /**
a90280fe 307 Retrieves the numeric value. Returns @true if successful.
3a326bfe 308 An empty @a szValue queries the default/unnamed key value.
bbc5b7f8 309 */
69e037ac
VZ
310 bool QueryValue(const wxString& szValue, long* plValue) const;
311
312 /**
a90280fe 313 Retrieves the binary structure. Returns @true if successful.
3a326bfe 314 An empty @a szValue queries the default/unnamed key value.
69e037ac
VZ
315 */
316 bool QueryValue(const wxString& szValue, wxMemoryBuffer& buf) const;
23324ae1
FM
317
318 /**
a90280fe 319 Renames the key. Returns @true if successful.
23324ae1 320 */
920b92a3 321 bool Rename(const wxString& szNewName);
23324ae1
FM
322
323 /**
a90280fe 324 Renames a value. Returns @true if successful.
23324ae1 325 */
920b92a3
FM
326 bool RenameValue(const wxString& szValueOld,
327 const wxString& szValueNew);
23324ae1 328
69e037ac
VZ
329 /**
330 Preallocate some memory for the name. For wxRegConfig usage only.
331 */
3c99e2fd 332 void ReserveMemoryForName(size_t bytes);
69e037ac
VZ
333
334 /**
335 Set or change the HKEY handle.
336 */
337 void SetHkey(WXHKEY hKey);
3c99e2fd 338
69e037ac
VZ
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);
3c99e2fd 352
23324ae1 353 /**
a90280fe
BP
354 Sets the given @a szValue which must be numeric. If the value doesn't
355 exist, it is created. Returns @true if successful.
3a326bfe 356 An empty @a szValue sets the default/unnamed key value.
23324ae1 357 */
920b92a3 358 bool SetValue(const wxString& szValue, long lValue);
bbc5b7f8 359 /**
a90280fe
BP
360 Sets the given @a szValue which must be string. If the value doesn't
361 exist, it is created. Returns @true if successful.
3a326bfe 362 An empty @a szValue sets the default/unnamed key value.
bbc5b7f8 363 */
920b92a3 364 bool SetValue(const wxString& szValue, const wxString& strValue);
bbc5b7f8 365 /**
3c99e2fd 366 Sets the given @a szValue which must be binary. If the value doesn't
a90280fe 367 exist, it is created. Returns @true if successful.
3a326bfe 368 An empty @a szValue sets the default/unnamed key value.
bbc5b7f8 369 */
920b92a3 370 bool SetValue(const wxString& szValue, const wxMemoryBuffer& buf);
23324ae1 371};