4 Windows Registry access module for Python.
6 * Simple registry access written by Mark Hammond in win32api
8 * Bill Tutt expanded the support significantly not long after.
9 * Numerous other people have submitted patches since then.
10 * Ripped from win32api module 03-Feb-2000 by Mark Hammond, and
11 basic Unicode support added.
16 #include "structmember.h"
17 #include "malloc.h" /* for alloca */
20 static BOOL
PyHKEY_AsHKEY(PyObject
*ob
, HKEY
*pRes
, BOOL bNoneOK
);
21 static PyObject
*PyHKEY_FromHKEY(HKEY h
);
22 static BOOL
PyHKEY_Close(PyObject
*obHandle
);
24 static char errNotAHandle
[] = "Object is not a handle";
26 /* The win32api module reports the function name that failed,
27 but this concept is not in the Python core.
28 Hopefully it will one day, and in the meantime I dont
29 want to lose this info...
31 #define PyErr_SetFromWindowsErrWithFunction(rc, fnname) \
32 PyErr_SetFromWindowsErr(rc)
34 /* Forward declares */
37 PyDoc_STRVAR(module_doc
,
38 "This module provides access to the Windows registry API.\n"
42 "CloseKey() - Closes a registry key.\n"
43 "ConnectRegistry() - Establishes a connection to a predefined registry handle\n"
44 " on another computer.\n"
45 "CreateKey() - Creates the specified key, or opens it if it already exists.\n"
46 "DeleteKey() - Deletes the specified key.\n"
47 "DeleteValue() - Removes a named value from the specified registry key.\n"
48 "EnumKey() - Enumerates subkeys of the specified open registry key.\n"
49 "EnumValue() - Enumerates values of the specified open registry key.\n"
50 "FlushKey() - Writes all the attributes of the specified key to the registry.\n"
51 "LoadKey() - Creates a subkey under HKEY_USER or HKEY_LOCAL_MACHINE and stores\n"
52 " registration information from a specified file into that subkey.\n"
53 "OpenKey() - Alias for <om win32api.RegOpenKeyEx>\n"
54 "OpenKeyEx() - Opens the specified key.\n"
55 "QueryValue() - Retrieves the value associated with the unnamed value for a\n"
56 " specified key in the registry.\n"
57 "QueryValueEx() - Retrieves the type and data for a specified value name\n"
58 " associated with an open registry key.\n"
59 "QueryInfoKey() - Returns information about the specified key.\n"
60 "SaveKey() - Saves the specified key, and all its subkeys a file.\n"
61 "SetValue() - Associates a value with a specified key.\n"
62 "SetValueEx() - Stores data in the value field of an open registry key.\n"
66 "HKEYType -- type object for HKEY objects\n"
67 "error -- exception raised for Win32 errors\n"
69 "Integer constants:\n"
70 "Many constants are defined - see the documentation for each function\n"
71 "to see what constants are used, and where.");
74 PyDoc_STRVAR(CloseKey_doc
,
75 "CloseKey(hkey) - Closes a previously opened registry key.\n"
77 "The hkey argument specifies a previously opened key.\n"
79 "Note that if the key is not closed using this method, it will be\n"
80 "closed when the hkey object is destroyed by Python.");
82 PyDoc_STRVAR(ConnectRegistry_doc
,
83 "key = ConnectRegistry(computer_name, key) - "
84 "Establishes a connection to a predefined registry handle on another computer.\n"
86 "computer_name is the name of the remote computer, of the form \\\\computername.\n"
87 " If None, the local computer is used.\n"
88 "key is the predefined handle to connect to.\n"
90 "The return value is the handle of the opened key.\n"
91 "If the function fails, an EnvironmentError exception is raised.");
93 PyDoc_STRVAR(CreateKey_doc
,
94 "key = CreateKey(key, sub_key) - Creates or opens the specified key.\n"
96 "key is an already open key, or one of the predefined HKEY_* constants\n"
97 "sub_key is a string that names the key this method opens or creates.\n"
98 " If key is one of the predefined keys, sub_key may be None. In that case,\n"
99 " the handle returned is the same key handle passed in to the function.\n"
101 "If the key already exists, this function opens the existing key\n"
103 "The return value is the handle of the opened key.\n"
104 "If the function fails, an exception is raised.");
106 PyDoc_STRVAR(DeleteKey_doc
,
107 "DeleteKey(key, sub_key) - Deletes the specified key.\n"
109 "key is an already open key, or any one of the predefined HKEY_* constants.\n"
110 "sub_key is a string that must be a subkey of the key identified by the key parameter.\n"
111 " This value must not be None, and the key may not have subkeys.\n"
113 "This method can not delete keys with subkeys.\n"
115 "If the method succeeds, the entire key, including all of its values,\n"
116 "is removed. If the method fails, an EnvironmentError exception is raised.");
118 PyDoc_STRVAR(DeleteValue_doc
,
119 "DeleteValue(key, value) - Removes a named value from a registry key.\n"
121 "key is an already open key, or any one of the predefined HKEY_* constants.\n"
122 "value is a string that identifies the value to remove.");
124 PyDoc_STRVAR(EnumKey_doc
,
125 "string = EnumKey(key, index) - Enumerates subkeys of an open registry key.\n"
127 "key is an already open key, or any one of the predefined HKEY_* constants.\n"
128 "index is an integer that identifies the index of the key to retrieve.\n"
130 "The function retrieves the name of one subkey each time it is called.\n"
131 "It is typically called repeatedly until an EnvironmentError exception is\n"
132 "raised, indicating no more values are available.");
134 PyDoc_STRVAR(EnumValue_doc
,
135 "tuple = EnumValue(key, index) - Enumerates values of an open registry key.\n"
136 "key is an already open key, or any one of the predefined HKEY_* constants.\n"
137 "index is an integer that identifies the index of the value to retrieve.\n"
139 "The function retrieves the name of one subkey each time it is called.\n"
140 "It is typically called repeatedly, until an EnvironmentError exception\n"
141 "is raised, indicating no more values.\n"
143 "The result is a tuple of 3 items:\n"
144 "value_name is a string that identifies the value.\n"
145 "value_data is an object that holds the value data, and whose type depends\n"
146 " on the underlying registry type.\n"
147 "data_type is an integer that identifies the type of the value data.");
149 PyDoc_STRVAR(FlushKey_doc
,
150 "FlushKey(key) - Writes all the attributes of a key to the registry.\n"
152 "key is an already open key, or any one of the predefined HKEY_* constants.\n"
154 "It is not necessary to call RegFlushKey to change a key.\n"
155 "Registry changes are flushed to disk by the registry using its lazy flusher.\n"
156 "Registry changes are also flushed to disk at system shutdown.\n"
157 "Unlike CloseKey(), the FlushKey() method returns only when all the data has\n"
158 "been written to the registry.\n"
159 "An application should only call FlushKey() if it requires absolute certainty that registry changes are on disk.\n"
160 "If you don't know whether a FlushKey() call is required, it probably isn't.");
162 PyDoc_STRVAR(LoadKey_doc
,
163 "LoadKey(key, sub_key, file_name) - Creates a subkey under the specified key\n"
164 "and stores registration information from a specified file into that subkey.\n"
166 "key is an already open key, or any one of the predefined HKEY_* constants.\n"
167 "sub_key is a string that identifies the sub_key to load\n"
168 "file_name is the name of the file to load registry data from.\n"
169 " This file must have been created with the SaveKey() function.\n"
170 " Under the file allocation table (FAT) file system, the filename may not\n"
171 "have an extension.\n"
173 "A call to LoadKey() fails if the calling process does not have the\n"
174 "SE_RESTORE_PRIVILEGE privilege.\n"
176 "If key is a handle returned by ConnectRegistry(), then the path specified\n"
177 "in fileName is relative to the remote computer.\n"
179 "The docs imply key must be in the HKEY_USER or HKEY_LOCAL_MACHINE tree");
181 PyDoc_STRVAR(OpenKey_doc
,
182 "key = OpenKey(key, sub_key, res = 0, sam = KEY_READ) - Opens the specified key.\n"
184 "key is an already open key, or any one of the predefined HKEY_* constants.\n"
185 "sub_key is a string that identifies the sub_key to open\n"
186 "res is a reserved integer, and must be zero. Default is zero.\n"
187 "sam is an integer that specifies an access mask that describes the desired\n"
188 " security access for the key. Default is KEY_READ\n"
190 "The result is a new handle to the specified key\n"
191 "If the function fails, an EnvironmentError exception is raised.");
193 PyDoc_STRVAR(OpenKeyEx_doc
, "See OpenKey()");
195 PyDoc_STRVAR(QueryInfoKey_doc
,
196 "tuple = QueryInfoKey(key) - Returns information about a key.\n"
198 "key is an already open key, or any one of the predefined HKEY_* constants.\n"
200 "The result is a tuple of 3 items:"
201 "An integer that identifies the number of sub keys this key has.\n"
202 "An integer that identifies the number of values this key has.\n"
203 "A long integer that identifies when the key was last modified (if available)\n"
204 " as 100's of nanoseconds since Jan 1, 1600.");
206 PyDoc_STRVAR(QueryValue_doc
,
207 "string = QueryValue(key, sub_key) - retrieves the unnamed value for a key.\n"
209 "key is an already open key, or any one of the predefined HKEY_* constants.\n"
210 "sub_key is a string that holds the name of the subkey with which the value\n"
211 " is associated. If this parameter is None or empty, the function retrieves\n"
212 " the value set by the SetValue() method for the key identified by key."
214 "Values in the registry have name, type, and data components. This method\n"
215 "retrieves the data for a key's first value that has a NULL name.\n"
216 "But the underlying API call doesn't return the type, Lame Lame Lame, DONT USE THIS!!!");
218 PyDoc_STRVAR(QueryValueEx_doc
,
219 "value,type_id = QueryValueEx(key, value_name) - Retrieves the type and data for a specified value name associated with an open registry key.\n"
221 "key is an already open key, or any one of the predefined HKEY_* constants.\n"
222 "value_name is a string indicating the value to query");
224 PyDoc_STRVAR(SaveKey_doc
,
225 "SaveKey(key, file_name) - Saves the specified key, and all its subkeys to the specified file.\n"
227 "key is an already open key, or any one of the predefined HKEY_* constants.\n"
228 "file_name is the name of the file to save registry data to.\n"
229 " This file cannot already exist. If this filename includes an extension,\n"
230 " it cannot be used on file allocation table (FAT) file systems by the\n"
231 " LoadKey(), ReplaceKey() or RestoreKey() methods.\n"
233 "If key represents a key on a remote computer, the path described by\n"
234 "file_name is relative to the remote computer.\n"
235 "The caller of this method must possess the SeBackupPrivilege security privilege.\n"
236 "This function passes NULL for security_attributes to the API.");
238 PyDoc_STRVAR(SetValue_doc
,
239 "SetValue(key, sub_key, type, value) - Associates a value with a specified key.\n"
241 "key is an already open key, or any one of the predefined HKEY_* constants.\n"
242 "sub_key is a string that names the subkey with which the value is associated.\n"
243 "type is an integer that specifies the type of the data. Currently this\n"
244 " must be REG_SZ, meaning only strings are supported.\n"
245 "value is a string that specifies the new value.\n"
247 "If the key specified by the sub_key parameter does not exist, the SetValue\n"
248 "function creates it.\n"
250 "Value lengths are limited by available memory. Long values (more than\n"
251 "2048 bytes) should be stored as files with the filenames stored in \n"
252 "the configuration registry. This helps the registry perform efficiently.\n"
254 "The key identified by the key parameter must have been opened with\n"
255 "KEY_SET_VALUE access.");
257 PyDoc_STRVAR(SetValueEx_doc
,
258 "SetValueEx(key, value_name, reserved, type, value) - Stores data in the value field of an open registry key.\n"
260 "key is an already open key, or any one of the predefined HKEY_* constants.\n"
261 "value_name is a string containing the name of the value to set, or None\n"
262 "type is an integer that specifies the type of the data. This should be one of:\n"
263 " REG_BINARY -- Binary data in any form.\n"
264 " REG_DWORD -- A 32-bit number.\n"
265 " REG_DWORD_LITTLE_ENDIAN -- A 32-bit number in little-endian format.\n"
266 " REG_DWORD_BIG_ENDIAN -- A 32-bit number in big-endian format.\n"
267 " REG_EXPAND_SZ -- A null-terminated string that contains unexpanded references\n"
268 " to environment variables (for example, %PATH%).\n"
269 " REG_LINK -- A Unicode symbolic link.\n"
270 " REG_MULTI_SZ -- An sequence of null-terminated strings, terminated by\n"
271 " two null characters. Note that Python handles this\n"
272 " termination automatically.\n"
273 " REG_NONE -- No defined value type.\n"
274 " REG_RESOURCE_LIST -- A device-driver resource list.\n"
275 " REG_SZ -- A null-terminated string.\n"
276 "reserved can be anything - zero is always passed to the API.\n"
277 "value is a string that specifies the new value.\n"
279 "This method can also set additional value and type information for the\n"
280 "specified key. The key identified by the key parameter must have been\n"
281 "opened with KEY_SET_VALUE access.\n"
283 "To open the key, use the CreateKeyEx() or OpenKeyEx() methods.\n"
285 "Value lengths are limited by available memory. Long values (more than\n"
286 "2048 bytes) should be stored as files with the filenames stored in \n"
287 "the configuration registry. This helps the registry perform efficiently.");
289 /* PyHKEY docstrings */
290 PyDoc_STRVAR(PyHKEY_doc
,
291 "PyHKEY Object - A Python object, representing a win32 registry key.\n"
293 "This object wraps a Windows HKEY object, automatically closing it when\n"
294 "the object is destroyed. To guarantee cleanup, you can call either\n"
295 "the Close() method on the PyHKEY, or the CloseKey() method.\n"
297 "All functions which accept a handle object also accept an integer - \n"
298 "however, use of the handle object is encouraged.\n"
301 "Close() - Closes the underlying handle.\n"
302 "Detach() - Returns the integer Win32 handle, detaching it from the object\n"
305 "handle - The integer Win32 handle.\n"
308 "__nonzero__ - Handles with an open object return true, otherwise false.\n"
309 "__int__ - Converting a handle to an integer returns the Win32 handle.\n"
310 "__cmp__ - Handle objects are compared using the handle value.");
313 PyDoc_STRVAR(PyHKEY_Close_doc
,
314 "key.Close() - Closes the underlying Windows handle.\n"
316 "If the handle is already closed, no error is raised.");
318 PyDoc_STRVAR(PyHKEY_Detach_doc
,
319 "int = key.Detach() - Detaches the Windows handle from the handle object.\n"
321 "The result is the value of the handle before it is detached. If the\n"
322 "handle is already detached, this will return zero.\n"
324 "After calling this function, the handle is effectively invalidated,\n"
325 "but the handle is not closed. You would call this function when you\n"
326 "need the underlying win32 handle to exist beyond the lifetime of the\n"
328 "On 64 bit windows, the result of this function is a long integer");
331 /************************************************************************
333 The PyHKEY object definition
335 ************************************************************************/
341 #define PyHKEY_Check(op) ((op)->ob_type == &PyHKEY_Type)
343 static char *failMsg
= "bad operand type";
346 PyHKEY_unaryFailureFunc(PyObject
*ob
)
348 PyErr_SetString(PyExc_TypeError
, failMsg
);
352 PyHKEY_binaryFailureFunc(PyObject
*ob1
, PyObject
*ob2
)
354 PyErr_SetString(PyExc_TypeError
, failMsg
);
358 PyHKEY_ternaryFailureFunc(PyObject
*ob1
, PyObject
*ob2
, PyObject
*ob3
)
360 PyErr_SetString(PyExc_TypeError
, failMsg
);
365 PyHKEY_deallocFunc(PyObject
*ob
)
367 /* Can not call PyHKEY_Close, as the ob->tp_type
368 has already been cleared, thus causing the type
371 PyHKEYObject
*obkey
= (PyHKEYObject
*)ob
;
373 RegCloseKey((HKEY
)obkey
->hkey
);
378 PyHKEY_nonzeroFunc(PyObject
*ob
)
380 return ((PyHKEYObject
*)ob
)->hkey
!= 0;
384 PyHKEY_intFunc(PyObject
*ob
)
386 PyHKEYObject
*pyhkey
= (PyHKEYObject
*)ob
;
387 return PyLong_FromVoidPtr(pyhkey
->hkey
);
391 PyHKEY_printFunc(PyObject
*ob
, FILE *fp
, int flags
)
393 PyHKEYObject
*pyhkey
= (PyHKEYObject
*)ob
;
395 wsprintf(resBuf
, "<PyHKEY at %p (%p)>",
402 PyHKEY_strFunc(PyObject
*ob
)
404 PyHKEYObject
*pyhkey
= (PyHKEYObject
*)ob
;
406 wsprintf(resBuf
, "<PyHKEY:%p>", pyhkey
->hkey
);
407 return PyString_FromString(resBuf
);
411 PyHKEY_compareFunc(PyObject
*ob1
, PyObject
*ob2
)
413 PyHKEYObject
*pyhkey1
= (PyHKEYObject
*)ob1
;
414 PyHKEYObject
*pyhkey2
= (PyHKEYObject
*)ob2
;
415 return pyhkey1
== pyhkey2
? 0 :
416 (pyhkey1
< pyhkey2
? -1 : 1);
420 PyHKEY_hashFunc(PyObject
*ob
)
422 /* Just use the address.
423 XXX - should we use the handle value?
425 return _Py_HashPointer(ob
);
429 static PyNumberMethods PyHKEY_NumberMethods
=
431 PyHKEY_binaryFailureFunc
, /* nb_add */
432 PyHKEY_binaryFailureFunc
, /* nb_subtract */
433 PyHKEY_binaryFailureFunc
, /* nb_multiply */
434 PyHKEY_binaryFailureFunc
, /* nb_divide */
435 PyHKEY_binaryFailureFunc
, /* nb_remainder */
436 PyHKEY_binaryFailureFunc
, /* nb_divmod */
437 PyHKEY_ternaryFailureFunc
, /* nb_power */
438 PyHKEY_unaryFailureFunc
, /* nb_negative */
439 PyHKEY_unaryFailureFunc
, /* nb_positive */
440 PyHKEY_unaryFailureFunc
, /* nb_absolute */
441 PyHKEY_nonzeroFunc
, /* nb_nonzero */
442 PyHKEY_unaryFailureFunc
, /* nb_invert */
443 PyHKEY_binaryFailureFunc
, /* nb_lshift */
444 PyHKEY_binaryFailureFunc
, /* nb_rshift */
445 PyHKEY_binaryFailureFunc
, /* nb_and */
446 PyHKEY_binaryFailureFunc
, /* nb_xor */
447 PyHKEY_binaryFailureFunc
, /* nb_or */
448 0, /* nb_coerce (allowed to be zero) */
449 PyHKEY_intFunc
, /* nb_int */
450 PyHKEY_unaryFailureFunc
, /* nb_long */
451 PyHKEY_unaryFailureFunc
, /* nb_float */
452 PyHKEY_unaryFailureFunc
, /* nb_oct */
453 PyHKEY_unaryFailureFunc
, /* nb_hex */
457 /* fwd declare __getattr__ */
458 static PyObject
*PyHKEY_getattr(PyObject
*self
, const char *name
);
460 /* The type itself */
461 PyTypeObject PyHKEY_Type
=
463 PyVarObject_HEAD_INIT(0, 0) /* fill in type at module init */
465 sizeof(PyHKEYObject
),
467 PyHKEY_deallocFunc
, /* tp_dealloc */
468 PyHKEY_printFunc
, /* tp_print */
469 PyHKEY_getattr
, /* tp_getattr */
471 PyHKEY_compareFunc
, /* tp_compare */
473 &PyHKEY_NumberMethods
, /* tp_as_number */
474 0, /* tp_as_sequence */
475 0, /* tp_as_mapping */
476 PyHKEY_hashFunc
, /* tp_hash */
478 PyHKEY_strFunc
, /* tp_str */
481 0, /* tp_as_buffer */
483 PyHKEY_doc
, /* tp_doc */
486 #define OFF(e) offsetof(PyHKEYObject, e)
488 static struct memberlist PyHKEY_memberlist
[] = {
489 {"handle", T_INT
, OFF(hkey
)},
490 {NULL
} /* Sentinel */
493 /************************************************************************
495 The PyHKEY object methods
497 ************************************************************************/
499 PyHKEY_CloseMethod(PyObject
*self
, PyObject
*args
)
501 if (!PyArg_ParseTuple(args
, ":Close"))
503 if (!PyHKEY_Close(self
))
510 PyHKEY_DetachMethod(PyObject
*self
, PyObject
*args
)
513 PyHKEYObject
*pThis
= (PyHKEYObject
*)self
;
514 if (!PyArg_ParseTuple(args
, ":Detach"))
516 ret
= (void*)pThis
->hkey
;
518 return PyLong_FromVoidPtr(ret
);
521 static struct PyMethodDef PyHKEY_methods
[] = {
522 {"Close", PyHKEY_CloseMethod
, METH_VARARGS
, PyHKEY_Close_doc
},
523 {"Detach", PyHKEY_DetachMethod
, METH_VARARGS
, PyHKEY_Detach_doc
},
527 /*static*/ PyObject
*
528 PyHKEY_getattr(PyObject
*self
, const char *name
)
532 res
= Py_FindMethod(PyHKEY_methods
, self
, name
);
536 if (strcmp(name
, "handle") == 0)
537 return PyLong_FromVoidPtr(((PyHKEYObject
*)self
)->hkey
);
538 return PyMember_Get((char *)self
, PyHKEY_memberlist
, name
);
541 /************************************************************************
542 The public PyHKEY API (well, not public yet :-)
543 ************************************************************************/
545 PyHKEY_New(HKEY hInit
)
547 PyHKEYObject
*key
= PyObject_NEW(PyHKEYObject
, &PyHKEY_Type
);
550 return (PyObject
*)key
;
554 PyHKEY_Close(PyObject
*ob_handle
)
559 if (!PyHKEY_Check(ob_handle
)) {
560 PyErr_SetString(PyExc_TypeError
, "bad operand type");
563 key
= (PyHKEYObject
*)ob_handle
;
564 rc
= key
->hkey
? RegCloseKey((HKEY
)key
->hkey
) : ERROR_SUCCESS
;
566 if (rc
!= ERROR_SUCCESS
)
567 PyErr_SetFromWindowsErrWithFunction(rc
, "RegCloseKey");
568 return rc
== ERROR_SUCCESS
;
572 PyHKEY_AsHKEY(PyObject
*ob
, HKEY
*pHANDLE
, BOOL bNoneOK
)
578 "None is not a valid HKEY in this context");
583 else if (PyHKEY_Check(ob
)) {
584 PyHKEYObject
*pH
= (PyHKEYObject
*)ob
;
587 else if (PyInt_Check(ob
) || PyLong_Check(ob
)) {
588 /* We also support integers */
590 *pHANDLE
= (HKEY
)PyLong_AsVoidPtr(ob
);
591 if (PyErr_Occurred())
597 "The object is not a PyHKEY object");
604 PyHKEY_FromHKEY(HKEY h
)
608 /* Inline PyObject_New */
609 op
= (PyHKEYObject
*) PyObject_MALLOC(sizeof(PyHKEYObject
));
611 return PyErr_NoMemory();
612 PyObject_INIT(op
, &PyHKEY_Type
);
614 return (PyObject
*)op
;
618 /************************************************************************
620 ************************************************************************/
622 PyWinObject_CloseHKEY(PyObject
*obHandle
)
625 if (PyHKEY_Check(obHandle
)) {
626 ok
= PyHKEY_Close(obHandle
);
628 #if SIZEOF_LONG >= SIZEOF_HKEY
629 else if (PyInt_Check(obHandle
)) {
630 long rc
= RegCloseKey((HKEY
)PyInt_AsLong(obHandle
));
631 ok
= (rc
== ERROR_SUCCESS
);
633 PyErr_SetFromWindowsErrWithFunction(rc
, "RegCloseKey");
636 else if (PyLong_Check(obHandle
)) {
637 long rc
= RegCloseKey((HKEY
)PyLong_AsVoidPtr(obHandle
));
638 ok
= (rc
== ERROR_SUCCESS
);
640 PyErr_SetFromWindowsErrWithFunction(rc
, "RegCloseKey");
646 "A handle must be a HKEY object or an integer");
654 Private Helper functions for the registry interfaces
656 ** Note that fixupMultiSZ and countString have both had changes
657 ** made to support "incorrect strings". The registry specification
658 ** calls for strings to be terminated with 2 null bytes. It seems
659 ** some commercial packages install strings which dont conform,
660 ** causing this code to fail - however, "regedit" etc still work
661 ** with these strings (ie only we dont!).
664 fixupMultiSZ(char **str
, char *data
, int len
)
671 for (P
= data
, i
= 0; P
< Q
&& *P
!= '\0'; P
++, i
++) {
673 for(; *P
!= '\0'; P
++)
679 countStrings(char *data
, int len
)
683 char *Q
= data
+ len
;
685 for (P
= data
, strings
= 0; P
< Q
&& *P
!= '\0'; P
++, strings
++)
686 for (; P
< Q
&& *P
!= '\0'; P
++)
691 /* Convert PyObject into Registry data.
692 Allocates space as needed. */
694 Py2Reg(PyObject
*value
, DWORD typ
, BYTE
**retDataBuf
, DWORD
*retDataSize
)
699 if (value
!= Py_None
&& !PyInt_Check(value
))
701 *retDataBuf
= (BYTE
*)PyMem_NEW(DWORD
, 1);
702 if (*retDataBuf
==NULL
){
706 *retDataSize
= sizeof(DWORD
);
707 if (value
== Py_None
) {
709 memcpy(*retDataBuf
, &zero
, sizeof(DWORD
));
713 &PyInt_AS_LONG((PyIntObject
*)value
),
720 if (value
== Py_None
)
723 if (PyUnicode_Check(value
)) {
724 value
= PyUnicode_AsEncodedString(
732 if (!PyString_Check(value
))
734 *retDataSize
= 1 + strlen(
736 (PyStringObject
*)value
));
738 *retDataBuf
= (BYTE
*)PyMem_NEW(DWORD
, *retDataSize
);
739 if (*retDataBuf
==NULL
){
743 if (value
== Py_None
)
744 strcpy((char *)*retDataBuf
, "");
746 strcpy((char *)*retDataBuf
,
748 (PyStringObject
*)value
));
757 PyObject
**obs
= NULL
;
759 if (value
== Py_None
)
762 if (!PyList_Check(value
))
764 i
= PyList_Size(value
);
766 obs
= malloc(sizeof(PyObject
*) * i
);
767 memset(obs
, 0, sizeof(PyObject
*) * i
);
768 for (j
= 0; j
< i
; j
++)
772 (PyListObject
*)value
,j
);
773 if (PyString_Check(t
)) {
776 } else if (PyUnicode_Check(t
)) {
777 obs
[j
] = PyUnicode_AsEncodedString(
787 (PyStringObject
*)obs
[j
]));
790 *retDataSize
= size
+ 1;
791 *retDataBuf
= (BYTE
*)PyMem_NEW(char,
793 if (*retDataBuf
==NULL
){
797 P
= (char *)*retDataBuf
;
799 for (j
= 0; j
< i
; j
++)
805 (PyStringObject
*)t
));
808 (PyStringObject
*)t
));
811 /* And doubly-terminate the list... */
817 for (j
= 0; j
< i
; j
++)
825 /* ALSO handle ALL unknown data types here. Even if we can't
826 support it natively, we should handle the bits. */
828 if (value
== Py_None
)
832 PyBufferProcs
*pb
= value
->ob_type
->tp_as_buffer
;
834 PyErr_Format(PyExc_TypeError
,
835 "Objects of type '%s' can not "
836 "be used as binary registry values",
837 value
->ob_type
->tp_name
);
840 *retDataSize
= (*pb
->bf_getreadbuffer
)(value
, 0, &src_buf
);
841 *retDataBuf
= (BYTE
*)PyMem_NEW(char,
843 if (*retDataBuf
==NULL
){
847 memcpy(*retDataBuf
, src_buf
, *retDataSize
);
854 /* Convert Registry data into PyObject*/
856 Reg2Py(char *retDataBuf
, DWORD retDataSize
, DWORD typ
)
862 if (retDataSize
== 0)
863 obData
= Py_BuildValue("i", 0);
865 obData
= Py_BuildValue("i",
870 /* retDataBuf may or may not have a trailing NULL in
872 if (retDataSize
&& retDataBuf
[retDataSize
-1] == '\0')
876 obData
= PyUnicode_DecodeMBCS(retDataBuf
,
881 if (retDataSize
== 0)
882 obData
= PyList_New(0);
886 int s
= countStrings(retDataBuf
, retDataSize
);
887 char **str
= (char **)malloc(sizeof(char *)*s
);
889 return PyErr_NoMemory();
891 fixupMultiSZ(str
, retDataBuf
, retDataSize
);
892 obData
= PyList_New(s
);
895 for (index
= 0; index
< s
; index
++)
897 size_t len
= _mbstrlen(str
[index
]);
899 PyErr_SetString(PyExc_OverflowError
,
900 "registry string is too long for a Python string");
904 PyList_SetItem(obData
,
906 PyUnicode_DecodeMBCS(
907 (const char *)str
[index
],
917 /* ALSO handle ALL unknown data types here. Even if we can't
918 support it natively, we should handle the bits. */
920 if (retDataSize
== 0) {
925 obData
= Py_BuildValue("s#",
936 /* The Python methods */
939 PyCloseKey(PyObject
*self
, PyObject
*args
)
942 if (!PyArg_ParseTuple(args
, "O:CloseKey", &obKey
))
944 if (!PyHKEY_Close(obKey
))
951 PyConnectRegistry(PyObject
*self
, PyObject
*args
)
955 char *szCompName
= NULL
;
958 if (!PyArg_ParseTuple(args
, "zO:ConnectRegistry", &szCompName
, &obKey
))
960 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
962 Py_BEGIN_ALLOW_THREADS
963 rc
= RegConnectRegistry(szCompName
, hKey
, &retKey
);
965 if (rc
!= ERROR_SUCCESS
)
966 return PyErr_SetFromWindowsErrWithFunction(rc
,
968 return PyHKEY_FromHKEY(retKey
);
972 PyCreateKey(PyObject
*self
, PyObject
*args
)
979 if (!PyArg_ParseTuple(args
, "Oz:CreateKey", &obKey
, &subKey
))
981 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
983 rc
= RegCreateKey(hKey
, subKey
, &retKey
);
984 if (rc
!= ERROR_SUCCESS
)
985 return PyErr_SetFromWindowsErrWithFunction(rc
, "CreateKey");
986 return PyHKEY_FromHKEY(retKey
);
990 PyDeleteKey(PyObject
*self
, PyObject
*args
)
996 if (!PyArg_ParseTuple(args
, "Os:DeleteKey", &obKey
, &subKey
))
998 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
1000 rc
= RegDeleteKey(hKey
, subKey
);
1001 if (rc
!= ERROR_SUCCESS
)
1002 return PyErr_SetFromWindowsErrWithFunction(rc
, "RegDeleteKey");
1008 PyDeleteValue(PyObject
*self
, PyObject
*args
)
1014 if (!PyArg_ParseTuple(args
, "Oz:DeleteValue", &obKey
, &subKey
))
1016 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
1018 Py_BEGIN_ALLOW_THREADS
1019 rc
= RegDeleteValue(hKey
, subKey
);
1020 Py_END_ALLOW_THREADS
1021 if (rc
!=ERROR_SUCCESS
)
1022 return PyErr_SetFromWindowsErrWithFunction(rc
,
1029 PyEnumKey(PyObject
*self
, PyObject
*args
)
1036 char tmpbuf
[256]; /* max key name length is 255 */
1037 DWORD len
= sizeof(tmpbuf
); /* includes NULL terminator */
1039 if (!PyArg_ParseTuple(args
, "Oi:EnumKey", &obKey
, &index
))
1041 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
1044 Py_BEGIN_ALLOW_THREADS
1045 rc
= RegEnumKeyEx(hKey
, index
, tmpbuf
, &len
, NULL
, NULL
, NULL
, NULL
);
1046 Py_END_ALLOW_THREADS
1047 if (rc
!= ERROR_SUCCESS
)
1048 return PyErr_SetFromWindowsErrWithFunction(rc
, "RegEnumKeyEx");
1050 retStr
= PyString_FromStringAndSize(tmpbuf
, len
);
1051 return retStr
; /* can be NULL */
1055 PyEnumValue(PyObject
*self
, PyObject
*args
)
1069 if (!PyArg_ParseTuple(args
, "Oi:EnumValue", &obKey
, &index
))
1071 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
1074 if ((rc
= RegQueryInfoKey(hKey
, NULL
, NULL
, NULL
, NULL
, NULL
, NULL
,
1076 &retValueSize
, &retDataSize
, NULL
, NULL
))
1078 return PyErr_SetFromWindowsErrWithFunction(rc
,
1080 ++retValueSize
; /* include null terminators */
1082 retValueBuf
= (char *)PyMem_Malloc(retValueSize
);
1083 if (retValueBuf
== NULL
)
1084 return PyErr_NoMemory();
1085 retDataBuf
= (char *)PyMem_Malloc(retDataSize
);
1086 if (retDataBuf
== NULL
) {
1087 PyMem_Free(retValueBuf
);
1088 return PyErr_NoMemory();
1091 Py_BEGIN_ALLOW_THREADS
1092 rc
= RegEnumValue(hKey
,
1100 Py_END_ALLOW_THREADS
1102 if (rc
!= ERROR_SUCCESS
) {
1103 retVal
= PyErr_SetFromWindowsErrWithFunction(rc
,
1107 obData
= Reg2Py(retDataBuf
, retDataSize
, typ
);
1108 if (obData
== NULL
) {
1112 retVal
= Py_BuildValue("sOi", retValueBuf
, obData
, typ
);
1115 PyMem_Free(retValueBuf
);
1116 PyMem_Free(retDataBuf
);
1121 PyFlushKey(PyObject
*self
, PyObject
*args
)
1126 if (!PyArg_ParseTuple(args
, "O:FlushKey", &obKey
))
1128 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
1130 Py_BEGIN_ALLOW_THREADS
1131 rc
= RegFlushKey(hKey
);
1132 Py_END_ALLOW_THREADS
1133 if (rc
!= ERROR_SUCCESS
)
1134 return PyErr_SetFromWindowsErrWithFunction(rc
, "RegFlushKey");
1139 PyLoadKey(PyObject
*self
, PyObject
*args
)
1147 if (!PyArg_ParseTuple(args
, "Oss:LoadKey", &obKey
, &subKey
, &fileName
))
1149 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
1151 Py_BEGIN_ALLOW_THREADS
1152 rc
= RegLoadKey(hKey
, subKey
, fileName
);
1153 Py_END_ALLOW_THREADS
1154 if (rc
!= ERROR_SUCCESS
)
1155 return PyErr_SetFromWindowsErrWithFunction(rc
, "RegLoadKey");
1161 PyOpenKey(PyObject
*self
, PyObject
*args
)
1170 REGSAM sam
= KEY_READ
;
1171 if (!PyArg_ParseTuple(args
, "Oz|ii:OpenKey", &obKey
, &subKey
,
1174 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
1177 Py_BEGIN_ALLOW_THREADS
1178 rc
= RegOpenKeyEx(hKey
, subKey
, res
, sam
, &retKey
);
1179 Py_END_ALLOW_THREADS
1180 if (rc
!= ERROR_SUCCESS
)
1181 return PyErr_SetFromWindowsErrWithFunction(rc
, "RegOpenKeyEx");
1182 return PyHKEY_FromHKEY(retKey
);
1187 PyQueryInfoKey(PyObject
*self
, PyObject
*args
)
1192 DWORD nSubKeys
, nValues
;
1197 if (!PyArg_ParseTuple(args
, "O:QueryInfoKey", &obKey
))
1199 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
1201 if ((rc
= RegQueryInfoKey(hKey
, NULL
, NULL
, 0, &nSubKeys
, NULL
, NULL
,
1202 &nValues
, NULL
, NULL
, NULL
, &ft
))
1204 return PyErr_SetFromWindowsErrWithFunction(rc
, "RegQueryInfoKey");
1205 li
.LowPart
= ft
.dwLowDateTime
;
1206 li
.HighPart
= ft
.dwHighDateTime
;
1207 l
= PyLong_FromLongLong(li
.QuadPart
);
1210 ret
= Py_BuildValue("iiO", nSubKeys
, nValues
, l
);
1216 PyQueryValue(PyObject
*self
, PyObject
*args
)
1226 if (!PyArg_ParseTuple(args
, "Oz:QueryValue", &obKey
, &subKey
))
1229 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
1231 if ((rc
= RegQueryValue(hKey
, subKey
, NULL
, &bufSize
))
1233 return PyErr_SetFromWindowsErrWithFunction(rc
,
1235 retStr
= PyString_FromStringAndSize(NULL
, bufSize
);
1238 retBuf
= PyString_AS_STRING(retStr
);
1239 if ((rc
= RegQueryValue(hKey
, subKey
, retBuf
, &bufSize
))
1242 return PyErr_SetFromWindowsErrWithFunction(rc
,
1245 _PyString_Resize(&retStr
, strlen(retBuf
));
1250 PyQueryValueEx(PyObject
*self
, PyObject
*args
)
1263 if (!PyArg_ParseTuple(args
, "Oz:QueryValueEx", &obKey
, &valueName
))
1266 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
1268 if ((rc
= RegQueryValueEx(hKey
, valueName
,
1272 return PyErr_SetFromWindowsErrWithFunction(rc
,
1274 retBuf
= (char *)PyMem_Malloc(bufSize
);
1276 return PyErr_NoMemory();
1277 if ((rc
= RegQueryValueEx(hKey
, valueName
, NULL
,
1278 &typ
, (BYTE
*)retBuf
, &bufSize
))
1281 return PyErr_SetFromWindowsErrWithFunction(rc
,
1284 obData
= Reg2Py(retBuf
, bufSize
, typ
);
1285 PyMem_Free((void *)retBuf
);
1288 result
= Py_BuildValue("Oi", obData
, typ
);
1295 PySaveKey(PyObject
*self
, PyObject
*args
)
1300 LPSECURITY_ATTRIBUTES pSA
= NULL
;
1303 if (!PyArg_ParseTuple(args
, "Os:SaveKey", &obKey
, &fileName
))
1305 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
1307 /* One day we may get security into the core?
1308 if (!PyWinObject_AsSECURITY_ATTRIBUTES(obSA, &pSA, TRUE))
1311 Py_BEGIN_ALLOW_THREADS
1312 rc
= RegSaveKey(hKey
, fileName
, pSA
);
1313 Py_END_ALLOW_THREADS
1314 if (rc
!= ERROR_SUCCESS
)
1315 return PyErr_SetFromWindowsErrWithFunction(rc
, "RegSaveKey");
1321 PySetValue(PyObject
*self
, PyObject
*args
)
1332 if (!PyArg_ParseTuple(args
, "OOiO:SetValue",
1338 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
1340 if (typ
!= REG_SZ
) {
1341 PyErr_SetString(PyExc_TypeError
,
1342 "Type must be _winreg.REG_SZ");
1345 /* XXX - need Unicode support */
1346 str
= PyString_AsString(obStrVal
);
1349 len
= PyString_Size(obStrVal
);
1350 if (obSubKey
== Py_None
)
1353 subKey
= PyString_AsString(obSubKey
);
1357 Py_BEGIN_ALLOW_THREADS
1358 rc
= RegSetValue(hKey
, subKey
, REG_SZ
, str
, len
+1);
1359 Py_END_ALLOW_THREADS
1360 if (rc
!= ERROR_SUCCESS
)
1361 return PyErr_SetFromWindowsErrWithFunction(rc
, "RegSetValue");
1367 PySetValueEx(PyObject
*self
, PyObject
*args
)
1380 if (!PyArg_ParseTuple(args
, "OzOiO:SetValueEx",
1387 if (!PyHKEY_AsHKEY(obKey
, &hKey
, FALSE
))
1389 if (!Py2Reg(value
, typ
, &data
, &len
))
1391 if (!PyErr_Occurred())
1392 PyErr_SetString(PyExc_ValueError
,
1393 "Could not convert the data to the specified type.");
1396 Py_BEGIN_ALLOW_THREADS
1397 rc
= RegSetValueEx(hKey
, valueName
, 0, typ
, data
, len
);
1398 Py_END_ALLOW_THREADS
1400 if (rc
!= ERROR_SUCCESS
)
1401 return PyErr_SetFromWindowsErrWithFunction(rc
,
1407 static struct PyMethodDef winreg_methods
[] = {
1408 {"CloseKey", PyCloseKey
, METH_VARARGS
, CloseKey_doc
},
1409 {"ConnectRegistry", PyConnectRegistry
, METH_VARARGS
, ConnectRegistry_doc
},
1410 {"CreateKey", PyCreateKey
, METH_VARARGS
, CreateKey_doc
},
1411 {"DeleteKey", PyDeleteKey
, METH_VARARGS
, DeleteKey_doc
},
1412 {"DeleteValue", PyDeleteValue
, METH_VARARGS
, DeleteValue_doc
},
1413 {"EnumKey", PyEnumKey
, METH_VARARGS
, EnumKey_doc
},
1414 {"EnumValue", PyEnumValue
, METH_VARARGS
, EnumValue_doc
},
1415 {"FlushKey", PyFlushKey
, METH_VARARGS
, FlushKey_doc
},
1416 {"LoadKey", PyLoadKey
, METH_VARARGS
, LoadKey_doc
},
1417 {"OpenKey", PyOpenKey
, METH_VARARGS
, OpenKey_doc
},
1418 {"OpenKeyEx", PyOpenKey
, METH_VARARGS
, OpenKeyEx_doc
},
1419 {"QueryValue", PyQueryValue
, METH_VARARGS
, QueryValue_doc
},
1420 {"QueryValueEx", PyQueryValueEx
, METH_VARARGS
, QueryValueEx_doc
},
1421 {"QueryInfoKey", PyQueryInfoKey
, METH_VARARGS
, QueryInfoKey_doc
},
1422 {"SaveKey", PySaveKey
, METH_VARARGS
, SaveKey_doc
},
1423 {"SetValue", PySetValue
, METH_VARARGS
, SetValue_doc
},
1424 {"SetValueEx", PySetValueEx
, METH_VARARGS
, SetValueEx_doc
},
1429 insint(PyObject
* d
, char * name
, long value
)
1431 PyObject
*v
= PyInt_FromLong(value
);
1432 if (!v
|| PyDict_SetItemString(d
, name
, v
))
1437 #define ADD_INT(val) insint(d, #val, val)
1440 inskey(PyObject
* d
, char * name
, HKEY key
)
1442 PyObject
*v
= PyLong_FromVoidPtr(key
);
1443 if (!v
|| PyDict_SetItemString(d
, name
, v
))
1448 #define ADD_KEY(val) inskey(d, #val, val)
1450 PyMODINIT_FUNC
init_winreg(void)
1453 m
= Py_InitModule3("_winreg", winreg_methods
, module_doc
);
1456 d
= PyModule_GetDict(m
);
1457 PyHKEY_Type
.ob_type
= &PyType_Type
;
1458 PyHKEY_Type
.tp_doc
= PyHKEY_doc
;
1459 Py_INCREF(&PyHKEY_Type
);
1460 if (PyDict_SetItemString(d
, "HKEYType",
1461 (PyObject
*)&PyHKEY_Type
) != 0)
1463 Py_INCREF(PyExc_WindowsError
);
1464 if (PyDict_SetItemString(d
, "error",
1465 PyExc_WindowsError
) != 0)
1468 /* Add the relevant constants */
1469 ADD_KEY(HKEY_CLASSES_ROOT
);
1470 ADD_KEY(HKEY_CURRENT_USER
);
1471 ADD_KEY(HKEY_LOCAL_MACHINE
);
1472 ADD_KEY(HKEY_USERS
);
1473 ADD_KEY(HKEY_PERFORMANCE_DATA
);
1474 #ifdef HKEY_CURRENT_CONFIG
1475 ADD_KEY(HKEY_CURRENT_CONFIG
);
1477 #ifdef HKEY_DYN_DATA
1478 ADD_KEY(HKEY_DYN_DATA
);
1480 ADD_INT(KEY_QUERY_VALUE
);
1481 ADD_INT(KEY_SET_VALUE
);
1482 ADD_INT(KEY_CREATE_SUB_KEY
);
1483 ADD_INT(KEY_ENUMERATE_SUB_KEYS
);
1484 ADD_INT(KEY_NOTIFY
);
1485 ADD_INT(KEY_CREATE_LINK
);
1488 ADD_INT(KEY_EXECUTE
);
1489 ADD_INT(KEY_ALL_ACCESS
);
1490 ADD_INT(REG_OPTION_RESERVED
);
1491 ADD_INT(REG_OPTION_NON_VOLATILE
);
1492 ADD_INT(REG_OPTION_VOLATILE
);
1493 ADD_INT(REG_OPTION_CREATE_LINK
);
1494 ADD_INT(REG_OPTION_BACKUP_RESTORE
);
1495 ADD_INT(REG_OPTION_OPEN_LINK
);
1496 ADD_INT(REG_LEGAL_OPTION
);
1497 ADD_INT(REG_CREATED_NEW_KEY
);
1498 ADD_INT(REG_OPENED_EXISTING_KEY
);
1499 ADD_INT(REG_WHOLE_HIVE_VOLATILE
);
1500 ADD_INT(REG_REFRESH_HIVE
);
1501 ADD_INT(REG_NO_LAZY_FLUSH
);
1502 ADD_INT(REG_NOTIFY_CHANGE_NAME
);
1503 ADD_INT(REG_NOTIFY_CHANGE_ATTRIBUTES
);
1504 ADD_INT(REG_NOTIFY_CHANGE_LAST_SET
);
1505 ADD_INT(REG_NOTIFY_CHANGE_SECURITY
);
1506 ADD_INT(REG_LEGAL_CHANGE_FILTER
);
1509 ADD_INT(REG_EXPAND_SZ
);
1510 ADD_INT(REG_BINARY
);
1512 ADD_INT(REG_DWORD_LITTLE_ENDIAN
);
1513 ADD_INT(REG_DWORD_BIG_ENDIAN
);
1515 ADD_INT(REG_MULTI_SZ
);
1516 ADD_INT(REG_RESOURCE_LIST
);
1517 ADD_INT(REG_FULL_RESOURCE_DESCRIPTOR
);
1518 ADD_INT(REG_RESOURCE_REQUIREMENTS_LIST
);