]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/msw/registry.h
Added wxFileName::Exists().
[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$
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 67class wxRegKey
23324ae1
FM
68{
69public:
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};