blob: fc185a2105775118e4ffd5305c6665ce61e51caf [file] [log] [blame]
Georg Brandl116aa622007-08-15 14:28:22 +00001
2:mod:`_winreg` -- Windows registry access
3=========================================
4
5.. module:: _winreg
6 :platform: Windows
7 :synopsis: Routines and objects for manipulating the Windows registry.
8.. sectionauthor:: Mark Hammond <MarkH@ActiveState.com>
9
10
Georg Brandl116aa622007-08-15 14:28:22 +000011These functions expose the Windows registry API to Python. Instead of using an
12integer as the registry handle, a handle object is used to ensure that the
13handles are closed correctly, even if the programmer neglects to explicitly
14close them.
15
16This module exposes a very low-level interface to the Windows registry; it is
17expected that in the future a new ``winreg`` module will be created offering a
18higher-level interface to the registry API.
19
20This module offers the following functions:
21
22
23.. function:: CloseKey(hkey)
24
25 Closes a previously opened registry key. The hkey argument specifies a
26 previously opened key.
27
28 Note that if *hkey* is not closed using this method (or via
29 :meth:`handle.Close`), it is closed when the *hkey* object is destroyed by
30 Python.
31
32
33.. function:: ConnectRegistry(computer_name, key)
34
35 Establishes a connection to a predefined registry handle on another computer,
36 and returns a :dfn:`handle object`
37
38 *computer_name* is the name of the remote computer, of the form
39 ``r"\\computername"``. If ``None``, the local computer is used.
40
41 *key* is the predefined handle to connect to.
42
43 The return value is the handle of the opened key. If the function fails, an
44 :exc:`EnvironmentError` exception is raised.
45
46
47.. function:: CreateKey(key, sub_key)
48
49 Creates or opens the specified key, returning a :dfn:`handle object`
50
51 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
52 constants.
53
54 *sub_key* is a string that names the key this method opens or creates.
55
56 If *key* is one of the predefined keys, *sub_key* may be ``None``. In that
57 case, the handle returned is the same key handle passed in to the function.
58
59 If the key already exists, this function opens the existing key.
60
61 The return value is the handle of the opened key. If the function fails, an
62 :exc:`EnvironmentError` exception is raised.
63
64
65.. function:: DeleteKey(key, sub_key)
66
67 Deletes the specified key.
68
69 *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
70 constants.
71
72 *sub_key* is a string that must be a subkey of the key identified by the *key*
73 parameter. This value must not be ``None``, and the key may not have subkeys.
74
75 *This method can not delete keys with subkeys.*
76
77 If the method succeeds, the entire key, including all of its values, is removed.
78 If the method fails, an :exc:`EnvironmentError` exception is raised.
79
80
81.. function:: DeleteValue(key, value)
82
83 Removes a named value from a registry key.
84
85 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
86 constants.
87
88 *value* is a string that identifies the value to remove.
89
90
91.. function:: EnumKey(key, index)
92
93 Enumerates subkeys of an open registry key, returning a string.
94
95 *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
96 constants.
97
98 *index* is an integer that identifies the index of the key to retrieve.
99
100 The function retrieves the name of one subkey each time it is called. It is
101 typically called repeatedly until an :exc:`EnvironmentError` exception is
102 raised, indicating, no more values are available.
103
104
105.. function:: EnumValue(key, index)
106
107 Enumerates values of an open registry key, returning a tuple.
108
109 *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
110 constants.
111
112 *index* is an integer that identifies the index of the value to retrieve.
113
114 The function retrieves the name of one subkey each time it is called. It is
115 typically called repeatedly, until an :exc:`EnvironmentError` exception is
116 raised, indicating no more values.
117
118 The result is a tuple of 3 items:
119
120 +-------+--------------------------------------------+
121 | Index | Meaning |
122 +=======+============================================+
123 | ``0`` | A string that identifies the value name |
124 +-------+--------------------------------------------+
125 | ``1`` | An object that holds the value data, and |
126 | | whose type depends on the underlying |
127 | | registry type |
128 +-------+--------------------------------------------+
129 | ``2`` | An integer that identifies the type of the |
130 | | value data |
131 +-------+--------------------------------------------+
132
133
134.. function:: FlushKey(key)
135
136 Writes all the attributes of a key to the registry.
137
138 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
139 constants.
140
141 It is not necessary to call RegFlushKey to change a key. Registry changes are
142 flushed to disk by the registry using its lazy flusher. Registry changes are
143 also flushed to disk at system shutdown. Unlike :func:`CloseKey`, the
144 :func:`FlushKey` method returns only when all the data has been written to the
145 registry. An application should only call :func:`FlushKey` if it requires
146 absolute certainty that registry changes are on disk.
147
148 .. note::
149
150 If you don't know whether a :func:`FlushKey` call is required, it probably
151 isn't.
152
153
154.. function:: RegLoadKey(key, sub_key, file_name)
155
156 Creates a subkey under the specified key and stores registration information
157 from a specified file into that subkey.
158
159 *key* is an already open key, or any of the predefined :const:`HKEY_\*`
160 constants.
161
162 *sub_key* is a string that identifies the sub_key to load.
163
164 *file_name* is the name of the file to load registry data from. This file must
165 have been created with the :func:`SaveKey` function. Under the file allocation
166 table (FAT) file system, the filename may not have an extension.
167
168 A call to LoadKey() fails if the calling process does not have the
169 :const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different than
170 permissions - see the Win32 documentation for more details.
171
172 If *key* is a handle returned by :func:`ConnectRegistry`, then the path
173 specified in *fileName* is relative to the remote computer.
174
175 The Win32 documentation implies *key* must be in the :const:`HKEY_USER` or
176 :const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true.
177
178
179.. function:: OpenKey(key, sub_key[, res=0][, sam=KEY_READ])
180
181 Opens the specified key, returning a :dfn:`handle object`
182
183 *key* is an already open key, or any one of the predefined :const:`HKEY_\*`
184 constants.
185
186 *sub_key* is a string that identifies the sub_key to open.
187
188 *res* is a reserved integer, and must be zero. The default is zero.
189
190 *sam* is an integer that specifies an access mask that describes the desired
191 security access for the key. Default is :const:`KEY_READ`
192
193 The result is a new handle to the specified key.
194
195 If the function fails, :exc:`EnvironmentError` is raised.
196
197
198.. function:: OpenKeyEx()
199
200 The functionality of :func:`OpenKeyEx` is provided via :func:`OpenKey`, by the
201 use of default arguments.
202
203
204.. function:: QueryInfoKey(key)
205
206 Returns information about a key, as a tuple.
207
208 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
209 constants.
210
211 The result is a tuple of 3 items:
212
213 +-------+---------------------------------------------+
214 | Index | Meaning |
215 +=======+=============================================+
216 | ``0`` | An integer giving the number of sub keys |
217 | | this key has. |
218 +-------+---------------------------------------------+
219 | ``1`` | An integer giving the number of values this |
220 | | key has. |
221 +-------+---------------------------------------------+
222 | ``2`` | A long integer giving when the key was last |
223 | | modified (if available) as 100's of |
224 | | nanoseconds since Jan 1, 1600. |
225 +-------+---------------------------------------------+
226
227
228.. function:: QueryValue(key, sub_key)
229
230 Retrieves the unnamed value for a key, as a string
231
232 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
233 constants.
234
235 *sub_key* is a string that holds the name of the subkey with which the value is
236 associated. If this parameter is ``None`` or empty, the function retrieves the
237 value set by the :func:`SetValue` method for the key identified by *key*.
238
239 Values in the registry have name, type, and data components. This method
240 retrieves the data for a key's first value that has a NULL name. But the
241 underlying API call doesn't return the type, Lame Lame Lame, DO NOT USE THIS!!!
242
243
244.. function:: QueryValueEx(key, value_name)
245
246 Retrieves the type and data for a specified value name associated with an open
247 registry key.
248
249 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
250 constants.
251
252 *value_name* is a string indicating the value to query.
253
254 The result is a tuple of 2 items:
255
256 +-------+-----------------------------------------+
257 | Index | Meaning |
258 +=======+=========================================+
259 | ``0`` | The value of the registry item. |
260 +-------+-----------------------------------------+
261 | ``1`` | An integer giving the registry type for |
262 | | this value. |
263 +-------+-----------------------------------------+
264
265
266.. function:: SaveKey(key, file_name)
267
268 Saves the specified key, and all its subkeys to the specified file.
269
270 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
271 constants.
272
273 *file_name* is the name of the file to save registry data to. This file cannot
274 already exist. If this filename includes an extension, it cannot be used on file
275 allocation table (FAT) file systems by the :meth:`LoadKey`, :meth:`ReplaceKey`
276 or :meth:`RestoreKey` methods.
277
278 If *key* represents a key on a remote computer, the path described by
279 *file_name* is relative to the remote computer. The caller of this method must
280 possess the :const:`SeBackupPrivilege` security privilege. Note that
281 privileges are different than permissions - see the Win32 documentation for
282 more details.
283
284 This function passes NULL for *security_attributes* to the API.
285
286
287.. function:: SetValue(key, sub_key, type, value)
288
289 Associates a value with a specified key.
290
291 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
292 constants.
293
294 *sub_key* is a string that names the subkey with which the value is associated.
295
296 *type* is an integer that specifies the type of the data. Currently this must be
297 :const:`REG_SZ`, meaning only strings are supported. Use the :func:`SetValueEx`
298 function for support for other data types.
299
300 *value* is a string that specifies the new value.
301
302 If the key specified by the *sub_key* parameter does not exist, the SetValue
303 function creates it.
304
305 Value lengths are limited by available memory. Long values (more than 2048
306 bytes) should be stored as files with the filenames stored in the configuration
307 registry. This helps the registry perform efficiently.
308
309 The key identified by the *key* parameter must have been opened with
310 :const:`KEY_SET_VALUE` access.
311
312
313.. function:: SetValueEx(key, value_name, reserved, type, value)
314
315 Stores data in the value field of an open registry key.
316
317 *key* is an already open key, or one of the predefined :const:`HKEY_\*`
318 constants.
319
320 *value_name* is a string that names the subkey with which the value is
321 associated.
322
323 *type* is an integer that specifies the type of the data. This should be one
324 of the following constants defined in this module:
325
326 +----------------------------------+---------------------------------------------+
327 | Constant | Meaning |
328 +==================================+=============================================+
329 | :const:`REG_BINARY` | Binary data in any form. |
330 +----------------------------------+---------------------------------------------+
331 | :const:`REG_DWORD` | A 32-bit number. |
332 +----------------------------------+---------------------------------------------+
333 | :const:`REG_DWORD_LITTLE_ENDIAN` | A 32-bit number in little-endian format. |
334 +----------------------------------+---------------------------------------------+
335 | :const:`REG_DWORD_BIG_ENDIAN` | A 32-bit number in big-endian format. |
336 +----------------------------------+---------------------------------------------+
337 | :const:`REG_EXPAND_SZ` | Null-terminated string containing |
338 | | references to environment variables |
339 | | (``%PATH%``). |
340 +----------------------------------+---------------------------------------------+
341 | :const:`REG_LINK` | A Unicode symbolic link. |
342 +----------------------------------+---------------------------------------------+
343 | :const:`REG_MULTI_SZ` | A sequence of null-terminated strings, |
344 | | terminated by two null characters. (Python |
345 | | handles this termination automatically.) |
346 +----------------------------------+---------------------------------------------+
347 | :const:`REG_NONE` | No defined value type. |
348 +----------------------------------+---------------------------------------------+
349 | :const:`REG_RESOURCE_LIST` | A device-driver resource list. |
350 +----------------------------------+---------------------------------------------+
351 | :const:`REG_SZ` | A null-terminated string. |
352 +----------------------------------+---------------------------------------------+
353
354 *reserved* can be anything - zero is always passed to the API.
355
356 *value* is a string that specifies the new value.
357
358 This method can also set additional value and type information for the specified
359 key. The key identified by the key parameter must have been opened with
360 :const:`KEY_SET_VALUE` access.
361
362 To open the key, use the :func:`CreateKeyEx` or :func:`OpenKey` methods.
363
364 Value lengths are limited by available memory. Long values (more than 2048
365 bytes) should be stored as files with the filenames stored in the configuration
366 registry. This helps the registry perform efficiently.
367
368
369.. _handle-object:
370
371Registry Handle Objects
372-----------------------
373
374This object wraps a Windows HKEY object, automatically closing it when the
375object is destroyed. To guarantee cleanup, you can call either the
376:meth:`Close` method on the object, or the :func:`CloseKey` function.
377
378All registry functions in this module return one of these objects.
379
380All registry functions in this module which accept a handle object also accept
381an integer, however, use of the handle object is encouraged.
382
383Handle objects provide semantics for :meth:`__bool__` - thus ::
384
385 if handle:
386 print "Yes"
387
388will print ``Yes`` if the handle is currently valid (has not been closed or
389detached).
390
391The object also support comparison semantics, so handle objects will compare
392true if they both reference the same underlying Windows handle value.
393
394Handle objects can be converted to an integer (e.g., using the builtin
395:func:`int` function), in which case the underlying Windows handle value is
396returned. You can also use the :meth:`Detach` method to return the integer
397handle, and also disconnect the Windows handle from the handle object.
398
399
400.. method:: PyHKEY.Close()
401
402 Closes the underlying Windows handle.
403
404 If the handle is already closed, no error is raised.
405
406
407.. method:: PyHKEY.Detach()
408
409 Detaches the Windows handle from the handle object.
410
411 The result is an integer (or long on 64 bit Windows) that holds the value of the
412 handle before it is detached. If the handle is already detached or closed, this
413 will return zero.
414
415 After calling this function, the handle is effectively invalidated, but the
416 handle is not closed. You would call this function when you need the
417 underlying Win32 handle to exist beyond the lifetime of the handle object.
418