diff options
Diffstat (limited to 'Doc/library/_winreg.rst')
| -rw-r--r-- | Doc/library/_winreg.rst | 420 |
1 files changed, 420 insertions, 0 deletions
diff --git a/Doc/library/_winreg.rst b/Doc/library/_winreg.rst new file mode 100644 index 0000000..fddbfd1 --- /dev/null +++ b/Doc/library/_winreg.rst @@ -0,0 +1,420 @@ + +:mod:`_winreg` -- Windows registry access +========================================= + +.. module:: _winreg + :platform: Windows + :synopsis: Routines and objects for manipulating the Windows registry. +.. sectionauthor:: Mark Hammond <MarkH@ActiveState.com> + + +.. versionadded:: 2.0 + +These functions expose the Windows registry API to Python. Instead of using an +integer as the registry handle, a handle object is used to ensure that the +handles are closed correctly, even if the programmer neglects to explicitly +close them. + +This module exposes a very low-level interface to the Windows registry; it is +expected that in the future a new ``winreg`` module will be created offering a +higher-level interface to the registry API. + +This module offers the following functions: + + +.. function:: CloseKey(hkey) + + Closes a previously opened registry key. The hkey argument specifies a + previously opened key. + + Note that if *hkey* is not closed using this method (or via + :meth:`handle.Close`), it is closed when the *hkey* object is destroyed by + Python. + + +.. function:: ConnectRegistry(computer_name, key) + + Establishes a connection to a predefined registry handle on another computer, + and returns a :dfn:`handle object` + + *computer_name* is the name of the remote computer, of the form + ``r"\\computername"``. If ``None``, the local computer is used. + + *key* is the predefined handle to connect to. + + The return value is the handle of the opened key. If the function fails, an + :exc:`EnvironmentError` exception is raised. + + +.. function:: CreateKey(key, sub_key) + + Creates or opens the specified key, returning a :dfn:`handle object` + + *key* is an already open key, or one of the predefined :const:`HKEY_\*` + constants. + + *sub_key* is a string that names the key this method opens or creates. + + If *key* is one of the predefined keys, *sub_key* may be ``None``. In that + case, the handle returned is the same key handle passed in to the function. + + If the key already exists, this function opens the existing key. + + The return value is the handle of the opened key. If the function fails, an + :exc:`EnvironmentError` exception is raised. + + +.. function:: DeleteKey(key, sub_key) + + Deletes the specified key. + + *key* is an already open key, or any one of the predefined :const:`HKEY_\*` + constants. + + *sub_key* is a string that must be a subkey of the key identified by the *key* + parameter. This value must not be ``None``, and the key may not have subkeys. + + *This method can not delete keys with subkeys.* + + If the method succeeds, the entire key, including all of its values, is removed. + If the method fails, an :exc:`EnvironmentError` exception is raised. + + +.. function:: DeleteValue(key, value) + + Removes a named value from a registry key. + + *key* is an already open key, or one of the predefined :const:`HKEY_\*` + constants. + + *value* is a string that identifies the value to remove. + + +.. function:: EnumKey(key, index) + + Enumerates subkeys of an open registry key, returning a string. + + *key* is an already open key, or any one of the predefined :const:`HKEY_\*` + constants. + + *index* is an integer that identifies the index of the key to retrieve. + + The function retrieves the name of one subkey each time it is called. It is + typically called repeatedly until an :exc:`EnvironmentError` exception is + raised, indicating, no more values are available. + + +.. function:: EnumValue(key, index) + + Enumerates values of an open registry key, returning a tuple. + + *key* is an already open key, or any one of the predefined :const:`HKEY_\*` + constants. + + *index* is an integer that identifies the index of the value to retrieve. + + The function retrieves the name of one subkey each time it is called. It is + typically called repeatedly, until an :exc:`EnvironmentError` exception is + raised, indicating no more values. + + The result is a tuple of 3 items: + + +-------+--------------------------------------------+ + | Index | Meaning | + +=======+============================================+ + | ``0`` | A string that identifies the value name | + +-------+--------------------------------------------+ + | ``1`` | An object that holds the value data, and | + | | whose type depends on the underlying | + | | registry type | + +-------+--------------------------------------------+ + | ``2`` | An integer that identifies the type of the | + | | value data | + +-------+--------------------------------------------+ + + +.. function:: FlushKey(key) + + Writes all the attributes of a key to the registry. + + *key* is an already open key, or one of the predefined :const:`HKEY_\*` + constants. + + It is not necessary to call RegFlushKey to change a key. Registry changes are + flushed to disk by the registry using its lazy flusher. Registry changes are + also flushed to disk at system shutdown. Unlike :func:`CloseKey`, the + :func:`FlushKey` method returns only when all the data has been written to the + registry. An application should only call :func:`FlushKey` if it requires + absolute certainty that registry changes are on disk. + + .. note:: + + If you don't know whether a :func:`FlushKey` call is required, it probably + isn't. + + +.. function:: RegLoadKey(key, sub_key, file_name) + + Creates a subkey under the specified key and stores registration information + from a specified file into that subkey. + + *key* is an already open key, or any of the predefined :const:`HKEY_\*` + constants. + + *sub_key* is a string that identifies the sub_key to load. + + *file_name* is the name of the file to load registry data from. This file must + have been created with the :func:`SaveKey` function. Under the file allocation + table (FAT) file system, the filename may not have an extension. + + A call to LoadKey() fails if the calling process does not have the + :const:`SE_RESTORE_PRIVILEGE` privilege. Note that privileges are different than + permissions - see the Win32 documentation for more details. + + If *key* is a handle returned by :func:`ConnectRegistry`, then the path + specified in *fileName* is relative to the remote computer. + + The Win32 documentation implies *key* must be in the :const:`HKEY_USER` or + :const:`HKEY_LOCAL_MACHINE` tree. This may or may not be true. + + +.. function:: OpenKey(key, sub_key[, res=0][, sam=KEY_READ]) + + Opens the specified key, returning a :dfn:`handle object` + + *key* is an already open key, or any one of the predefined :const:`HKEY_\*` + constants. + + *sub_key* is a string that identifies the sub_key to open. + + *res* is a reserved integer, and must be zero. The default is zero. + + *sam* is an integer that specifies an access mask that describes the desired + security access for the key. Default is :const:`KEY_READ` + + The result is a new handle to the specified key. + + If the function fails, :exc:`EnvironmentError` is raised. + + +.. function:: OpenKeyEx() + + The functionality of :func:`OpenKeyEx` is provided via :func:`OpenKey`, by the + use of default arguments. + + +.. function:: QueryInfoKey(key) + + Returns information about a key, as a tuple. + + *key* is an already open key, or one of the predefined :const:`HKEY_\*` + constants. + + The result is a tuple of 3 items: + + +-------+---------------------------------------------+ + | Index | Meaning | + +=======+=============================================+ + | ``0`` | An integer giving the number of sub keys | + | | this key has. | + +-------+---------------------------------------------+ + | ``1`` | An integer giving the number of values this | + | | key has. | + +-------+---------------------------------------------+ + | ``2`` | A long integer giving when the key was last | + | | modified (if available) as 100's of | + | | nanoseconds since Jan 1, 1600. | + +-------+---------------------------------------------+ + + +.. function:: QueryValue(key, sub_key) + + Retrieves the unnamed value for a key, as a string + + *key* is an already open key, or one of the predefined :const:`HKEY_\*` + constants. + + *sub_key* is a string that holds the name of the subkey with which the value is + associated. If this parameter is ``None`` or empty, the function retrieves the + value set by the :func:`SetValue` method for the key identified by *key*. + + Values in the registry have name, type, and data components. This method + retrieves the data for a key's first value that has a NULL name. But the + underlying API call doesn't return the type, Lame Lame Lame, DO NOT USE THIS!!! + + +.. function:: QueryValueEx(key, value_name) + + Retrieves the type and data for a specified value name associated with an open + registry key. + + *key* is an already open key, or one of the predefined :const:`HKEY_\*` + constants. + + *value_name* is a string indicating the value to query. + + The result is a tuple of 2 items: + + +-------+-----------------------------------------+ + | Index | Meaning | + +=======+=========================================+ + | ``0`` | The value of the registry item. | + +-------+-----------------------------------------+ + | ``1`` | An integer giving the registry type for | + | | this value. | + +-------+-----------------------------------------+ + + +.. function:: SaveKey(key, file_name) + + Saves the specified key, and all its subkeys to the specified file. + + *key* is an already open key, or one of the predefined :const:`HKEY_\*` + constants. + + *file_name* is the name of the file to save registry data to. This file cannot + already exist. If this filename includes an extension, it cannot be used on file + allocation table (FAT) file systems by the :meth:`LoadKey`, :meth:`ReplaceKey` + or :meth:`RestoreKey` methods. + + If *key* represents a key on a remote computer, the path described by + *file_name* is relative to the remote computer. The caller of this method must + possess the :const:`SeBackupPrivilege` security privilege. Note that + privileges are different than permissions - see the Win32 documentation for + more details. + + This function passes NULL for *security_attributes* to the API. + + +.. function:: SetValue(key, sub_key, type, value) + + Associates a value with a specified key. + + *key* is an already open key, or one of the predefined :const:`HKEY_\*` + constants. + + *sub_key* is a string that names the subkey with which the value is associated. + + *type* is an integer that specifies the type of the data. Currently this must be + :const:`REG_SZ`, meaning only strings are supported. Use the :func:`SetValueEx` + function for support for other data types. + + *value* is a string that specifies the new value. + + If the key specified by the *sub_key* parameter does not exist, the SetValue + function creates it. + + Value lengths are limited by available memory. Long values (more than 2048 + bytes) should be stored as files with the filenames stored in the configuration + registry. This helps the registry perform efficiently. + + The key identified by the *key* parameter must have been opened with + :const:`KEY_SET_VALUE` access. + + +.. function:: SetValueEx(key, value_name, reserved, type, value) + + Stores data in the value field of an open registry key. + + *key* is an already open key, or one of the predefined :const:`HKEY_\*` + constants. + + *value_name* is a string that names the subkey with which the value is + associated. + + *type* is an integer that specifies the type of the data. This should be one + of the following constants defined in this module: + + +----------------------------------+---------------------------------------------+ + | Constant | Meaning | + +==================================+=============================================+ + | :const:`REG_BINARY` | Binary data in any form. | + +----------------------------------+---------------------------------------------+ + | :const:`REG_DWORD` | A 32-bit number. | + +----------------------------------+---------------------------------------------+ + | :const:`REG_DWORD_LITTLE_ENDIAN` | A 32-bit number in little-endian format. | + +----------------------------------+---------------------------------------------+ + | :const:`REG_DWORD_BIG_ENDIAN` | A 32-bit number in big-endian format. | + +----------------------------------+---------------------------------------------+ + | :const:`REG_EXPAND_SZ` | Null-terminated string containing | + | | references to environment variables | + | | (``%PATH%``). | + +----------------------------------+---------------------------------------------+ + | :const:`REG_LINK` | A Unicode symbolic link. | + +----------------------------------+---------------------------------------------+ + | :const:`REG_MULTI_SZ` | A sequence of null-terminated strings, | + | | terminated by two null characters. (Python | + | | handles this termination automatically.) | + +----------------------------------+---------------------------------------------+ + | :const:`REG_NONE` | No defined value type. | + +----------------------------------+---------------------------------------------+ + | :const:`REG_RESOURCE_LIST` | A device-driver resource list. | + +----------------------------------+---------------------------------------------+ + | :const:`REG_SZ` | A null-terminated string. | + +----------------------------------+---------------------------------------------+ + + *reserved* can be anything - zero is always passed to the API. + + *value* is a string that specifies the new value. + + This method can also set additional value and type information for the specified + key. The key identified by the key parameter must have been opened with + :const:`KEY_SET_VALUE` access. + + To open the key, use the :func:`CreateKeyEx` or :func:`OpenKey` methods. + + Value lengths are limited by available memory. Long values (more than 2048 + bytes) should be stored as files with the filenames stored in the configuration + registry. This helps the registry perform efficiently. + + +.. _handle-object: + +Registry Handle Objects +----------------------- + +This object wraps a Windows HKEY object, automatically closing it when the +object is destroyed. To guarantee cleanup, you can call either the +:meth:`Close` method on the object, or the :func:`CloseKey` function. + +All registry functions in this module return one of these objects. + +All registry functions in this module which accept a handle object also accept +an integer, however, use of the handle object is encouraged. + +Handle objects provide semantics for :meth:`__bool__` - thus :: + + if handle: + print "Yes" + +will print ``Yes`` if the handle is currently valid (has not been closed or +detached). + +The object also support comparison semantics, so handle objects will compare +true if they both reference the same underlying Windows handle value. + +Handle objects can be converted to an integer (e.g., using the builtin +:func:`int` function), in which case the underlying Windows handle value is +returned. You can also use the :meth:`Detach` method to return the integer +handle, and also disconnect the Windows handle from the handle object. + + +.. method:: PyHKEY.Close() + + Closes the underlying Windows handle. + + If the handle is already closed, no error is raised. + + +.. method:: PyHKEY.Detach() + + Detaches the Windows handle from the handle object. + + The result is an integer (or long on 64 bit Windows) that holds the value of the + handle before it is detached. If the handle is already detached or closed, this + will return zero. + + After calling this function, the handle is effectively invalidated, but the + handle is not closed. You would call this function when you need the + underlying Win32 handle to exist beyond the lifetime of the handle object. + |