]>
Commit | Line | Data |
---|---|---|
23324ae1 FM |
1 | ///////////////////////////////////////////////////////////////////////////// |
2 | // Name: msw/registry.h | |
e54c96f1 | 3 | // Purpose: interface of wxRegKey |
23324ae1 FM |
4 | // Author: wxWidgets team |
5 | // RCS-ID: $Id$ | |
526954c5 | 6 | // Licence: wxWindows licence |
23324ae1 FM |
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 | |
03c9cce5 VZ |
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"); | |
bbc5b7f8 | 41 | |
4c51a665 | 42 | // Create a new value "MyValue" and set it to 12. |
03c9cce5 | 43 | key.SetValue("MyValue", 12); |
bbc5b7f8 BP |
44 | |
45 | // Read the value back. | |
46 | long value; | |
03c9cce5 | 47 | key.QueryValue("MyValue", &value); |
bbc5b7f8 BP |
48 | wxMessageBox(wxString::Format("%d", value), "Registry Value", wxOK); |
49 | ||
50 | // Get the number of subkeys and enumerate them. | |
51 | size_t subkeys; | |
03c9cce5 | 52 | key.GetKeyInfo(&subkeys, NULL, NULL, NULL); |
bbc5b7f8 BP |
53 | |
54 | wxString key_name; | |
03c9cce5 | 55 | key.GetFirstKey(key_name, 1); |
bbc5b7f8 BP |
56 | for(int i = 0; i < subkeys; i++) |
57 | { | |
58 | wxMessageBox(key_name, "Subkey Name", wxOK); | |
03c9cce5 | 59 | key.GetNextKey(key_name, 1); |
bbc5b7f8 BP |
60 | } |
61 | @endcode | |
3c99e2fd FM |
62 | |
63 | ||
64 | @library{wxbase} | |
65 | @category{cfg} | |
23324ae1 | 66 | */ |
7c913512 | 67 | class wxRegKey |
23324ae1 FM |
68 | { |
69 | public: | |
23324ae1 | 70 | /** |
9602ce3d | 71 | Default constructor, initializes to @c HKEY_CLASSES_ROOT. |
a5c46848 VZ |
72 | |
73 | The @a viewMode parameter is new since wxWidgets 2.9.2. | |
23324ae1 | 74 | */ |
a5c46848 | 75 | wxRegKey(WOW64ViewMode viewMode = WOW64ViewMode_Default); |
bbc5b7f8 BP |
76 | /** |
77 | The constructor to set the full name of the key. | |
a5c46848 VZ |
78 | |
79 | The @a viewMode parameter is new since wxWidgets 2.9.2. | |
bbc5b7f8 | 80 | */ |
a5c46848 VZ |
81 | wxRegKey(const wxString& strKey, |
82 | WOW64ViewMode viewMode = WOW64ViewMode_Default); | |
69e037ac | 83 | /** |
3c99e2fd | 84 | The constructor to set the full name of the key using one of the |
69e037ac | 85 | standard keys, that is, HKCR, HKCU, HKLM, HKUSR, HKPD, HKCC or HKDD. |
a5c46848 | 86 | The @a viewMode parameter is new since wxWidgets 2.9.2. |
69e037ac | 87 | */ |
a5c46848 VZ |
88 | wxRegKey(StdKey keyParent, const wxString& strKey, |
89 | WOW64ViewMode viewMode = WOW64ViewMode_Default); | |
bbc5b7f8 | 90 | /** |
a5c46848 VZ |
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. | |
bbc5b7f8 | 93 | */ |
7c913512 | 94 | wxRegKey(const wxRegKey& keyParent, const wxString& strKey); |
bbc5b7f8 BP |
95 | |
96 | /** | |
97 | Access modes for wxRegKey. | |
98 | */ | |
99 | enum AccessMode | |
100 | { | |
69e037ac VZ |
101 | Read, ///< Read-only |
102 | Write ///< Read and Write | |
103 | }; | |
104 | ||
3c99e2fd | 105 | /** |
69e037ac VZ |
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 | |
3c99e2fd | 137 | Type_Resource_requirements_list ///< |
bbc5b7f8 | 138 | }; |
23324ae1 | 139 | |
a5c46848 VZ |
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 | ||
23324ae1 FM |
167 | /** |
168 | Closes the key. | |
169 | */ | |
170 | void Close(); | |
171 | ||
69e037ac VZ |
172 | /** |
173 | Copy the entire contents of the key recursively to another location | |
a90280fe | 174 | using the name. Returns @true if successful. |
69e037ac VZ |
175 | */ |
176 | bool Copy(const wxString& szNewName); | |
177 | /** | |
178 | Copy the entire contents of the key recursively to another location | |
a90280fe | 179 | using the key. Returns @true if successful. |
69e037ac VZ |
180 | */ |
181 | bool Copy(wxRegKey& keyDst); | |
3c99e2fd | 182 | |
69e037ac VZ |
183 | /** |
184 | Copy the value to another key, possibly changing its name. By default | |
a90280fe | 185 | it will remain the same. Returns @true if successful. |
69e037ac | 186 | */ |
3c99e2fd | 187 | bool CopyValue(const wxString& szValue, wxRegKey& keyDst, |
69e037ac | 188 | const wxString& szNewName = wxEmptyString); |
23324ae1 | 189 | /** |
a90280fe BP |
190 | Creates the key. Will fail if the key already exists and @a bOkIfExists |
191 | is @false. Returns @true if successful. | |
23324ae1 | 192 | */ |
4cc4bfaf | 193 | bool Create(bool bOkIfExists = true); |
23324ae1 FM |
194 | |
195 | /** | |
a90280fe | 196 | Deletes the subkey with all its subkeys and values recursively. |
23324ae1 | 197 | */ |
920b92a3 | 198 | void DeleteKey(const wxString& szKey); |
23324ae1 FM |
199 | |
200 | /** | |
a90280fe | 201 | Deletes this key and all its subkeys and values recursively. |
23324ae1 FM |
202 | */ |
203 | void DeleteSelf(); | |
204 | ||
205 | /** | |
3c99e2fd | 206 | Deletes the named value or use an empty string argument to remove the |
a90280fe | 207 | default value of the key. |
23324ae1 | 208 | */ |
920b92a3 | 209 | void DeleteValue(const wxString& szKey); |
23324ae1 FM |
210 | |
211 | /** | |
212 | Returns @true if the key exists. | |
213 | */ | |
bbc5b7f8 | 214 | bool Exists() const; |
23324ae1 | 215 | |
69e037ac VZ |
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 | |
a90280fe | 220 | format nor the newer REGEDIT5. Returns @true if successful. |
69e037ac VZ |
221 | */ |
222 | bool Export(const wxString& filename) const; | |
223 | /** | |
224 | Write the contents of this key and all its subkeys to the opened stream. | |
a90280fe | 225 | Returns @true if successful. |
69e037ac VZ |
226 | */ |
227 | bool Export(wxOutputStream& ostr) const; | |
3c99e2fd | 228 | |
23324ae1 | 229 | /** |
a90280fe | 230 | Gets the first key. Returns @true if successful. |
23324ae1 FM |
231 | */ |
232 | bool GetFirstKey(wxString& strKeyName, long& lIndex); | |
233 | ||
234 | /** | |
a90280fe | 235 | Gets the first value of this key. Returns @true if successful. |
23324ae1 FM |
236 | */ |
237 | bool GetFirstValue(wxString& strValueName, long& lIndex); | |
238 | ||
239 | /** | |
a90280fe | 240 | Gets information about the key. Returns @true if successful. |
d9faa1fe | 241 | |
7c913512 | 242 | @param pnSubKeys |
4cc4bfaf | 243 | The number of subkeys. |
7c913512 | 244 | @param pnMaxKeyLen |
4cc4bfaf | 245 | The maximum length of the subkey name. |
7c913512 | 246 | @param pnValues |
4cc4bfaf | 247 | The number of values. |
7c913512 | 248 | @param pnMaxValueLen |
4cc4bfaf | 249 | The maximum length of a value. |
23324ae1 | 250 | */ |
bbc5b7f8 BP |
251 | bool GetKeyInfo(size_t* pnSubKeys, size_t* pnMaxKeyLen, |
252 | size_t* pnValues, size_t* pnMaxValueLen) const; | |
23324ae1 FM |
253 | |
254 | /** | |
255 | Gets the name of the registry key. | |
256 | */ | |
328f5751 | 257 | wxString GetName(bool bShortPrefix = true) const; |
23324ae1 | 258 | |
a5c46848 VZ |
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 | ||
23324ae1 | 268 | /** |
a90280fe | 269 | Gets the next key. Returns @true if successful. |
23324ae1 | 270 | */ |
328f5751 | 271 | bool GetNextKey(wxString& strKeyName, long& lIndex) const; |
23324ae1 FM |
272 | |
273 | /** | |
a90280fe | 274 | Gets the next key value for this key. Returns @true if successful. |
23324ae1 | 275 | */ |
328f5751 | 276 | bool GetNextValue(wxString& strValueName, long& lIndex) const; |
23324ae1 | 277 | |
69e037ac VZ |
278 | /** |
279 | Gets the value type. | |
280 | */ | |
281 | ValueType GetValueType(const wxString& szValue) const; | |
3c99e2fd | 282 | |
23324ae1 FM |
283 | /** |
284 | Returns @true if given subkey exists. | |
285 | */ | |
920b92a3 | 286 | bool HasSubKey(const wxString& szKey) const; |
23324ae1 FM |
287 | |
288 | /** | |
289 | Returns @true if any subkeys exist. | |
290 | */ | |
328f5751 | 291 | bool HasSubKeys() const; |
23324ae1 FM |
292 | |
293 | /** | |
294 | Returns @true if the value exists. | |
295 | */ | |
920b92a3 | 296 | bool HasValue(const wxString& szValue) const; |
23324ae1 FM |
297 | |
298 | /** | |
299 | Returns @true if any values exist. | |
300 | */ | |
328f5751 | 301 | bool HasValues() const; |
23324ae1 FM |
302 | |
303 | /** | |
304 | Returns @true if this key is empty, nothing under this key. | |
305 | */ | |
328f5751 | 306 | bool IsEmpty() const; |
23324ae1 | 307 | |
69e037ac | 308 | /** |
a90280fe | 309 | Returns @true if the value contains a number. |
69e037ac VZ |
310 | */ |
311 | bool IsNumericValue(const wxString& szValue) const; | |
312 | ||
23324ae1 FM |
313 | /** |
314 | Returns @true if the key is opened. | |
315 | */ | |
328f5751 | 316 | bool IsOpened() const; |
23324ae1 FM |
317 | |
318 | /** | |
a90280fe BP |
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. | |
23324ae1 FM |
322 | */ |
323 | bool Open(AccessMode mode = Write); | |
324 | ||
a90280fe BP |
325 | /** |
326 | Assignment operator to set the default value of the key. | |
327 | */ | |
328 | wxRegKey& operator=(const wxString& strValue); | |
329 | ||
23324ae1 | 330 | /** |
69e037ac VZ |
331 | Return the default value of the key. |
332 | */ | |
333 | wxString QueryDefaultValue() const; | |
334 | ||
335 | /** | |
a90280fe | 336 | Retrieves the raw string value. Returns @true if successful. |
3a326bfe | 337 | An empty @a szValue queries the default/unnamed key value. |
23324ae1 | 338 | */ |
69e037ac VZ |
339 | bool QueryRawValue(const wxString& szValue, wxString& strValue) const; |
340 | ||
341 | /** | |
a90280fe | 342 | Retrieves the raw or expanded string value. Returns @true if successful. |
3a326bfe | 343 | An empty @a szValue queries the default/unnamed key value. |
69e037ac VZ |
344 | */ |
345 | bool QueryValue(const wxString& szValue, wxString& strValue, bool raw) const; | |
bbc5b7f8 BP |
346 | |
347 | /** | |
a90280fe | 348 | Retrieves the numeric value. Returns @true if successful. |
3a326bfe | 349 | An empty @a szValue queries the default/unnamed key value. |
bbc5b7f8 | 350 | */ |
69e037ac VZ |
351 | bool QueryValue(const wxString& szValue, long* plValue) const; |
352 | ||
353 | /** | |
a90280fe | 354 | Retrieves the binary structure. Returns @true if successful. |
3a326bfe | 355 | An empty @a szValue queries the default/unnamed key value. |
69e037ac VZ |
356 | */ |
357 | bool QueryValue(const wxString& szValue, wxMemoryBuffer& buf) const; | |
23324ae1 FM |
358 | |
359 | /** | |
a90280fe | 360 | Renames the key. Returns @true if successful. |
23324ae1 | 361 | */ |
920b92a3 | 362 | bool Rename(const wxString& szNewName); |
23324ae1 FM |
363 | |
364 | /** | |
a90280fe | 365 | Renames a value. Returns @true if successful. |
23324ae1 | 366 | */ |
920b92a3 FM |
367 | bool RenameValue(const wxString& szValueOld, |
368 | const wxString& szValueNew); | |
23324ae1 | 369 | |
69e037ac VZ |
370 | /** |
371 | Preallocate some memory for the name. For wxRegConfig usage only. | |
372 | */ | |
3c99e2fd | 373 | void ReserveMemoryForName(size_t bytes); |
69e037ac VZ |
374 | |
375 | /** | |
376 | Set or change the HKEY handle. | |
377 | */ | |
378 | void SetHkey(WXHKEY hKey); | |
3c99e2fd | 379 | |
69e037ac VZ |
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); | |
3c99e2fd | 393 | |
23324ae1 | 394 | /** |
a90280fe BP |
395 | Sets the given @a szValue which must be numeric. If the value doesn't |
396 | exist, it is created. Returns @true if successful. | |
3a326bfe | 397 | An empty @a szValue sets the default/unnamed key value. |
23324ae1 | 398 | */ |
920b92a3 | 399 | bool SetValue(const wxString& szValue, long lValue); |
bbc5b7f8 | 400 | /** |
a90280fe BP |
401 | Sets the given @a szValue which must be string. If the value doesn't |
402 | exist, it is created. Returns @true if successful. | |
3a326bfe | 403 | An empty @a szValue sets the default/unnamed key value. |
bbc5b7f8 | 404 | */ |
920b92a3 | 405 | bool SetValue(const wxString& szValue, const wxString& strValue); |
bbc5b7f8 | 406 | /** |
3c99e2fd | 407 | Sets the given @a szValue which must be binary. If the value doesn't |
a90280fe | 408 | exist, it is created. Returns @true if successful. |
3a326bfe | 409 | An empty @a szValue sets the default/unnamed key value. |
bbc5b7f8 | 410 | */ |
920b92a3 | 411 | bool SetValue(const wxString& szValue, const wxMemoryBuffer& buf); |
23324ae1 | 412 | }; |