diff options
| -rw-r--r-- | Doc/library/winreg.rst | 329 |
1 files changed, 247 insertions, 82 deletions
diff --git a/Doc/library/winreg.rst b/Doc/library/winreg.rst index 6120725..5acb1f6 100644 --- a/Doc/library/winreg.rst +++ b/Doc/library/winreg.rst @@ -12,10 +12,6 @@ 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: @@ -24,9 +20,9 @@ This module offers the following functions: 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. + .. note:: + If *hkey* is not closed using this method (or via :meth:`hkey.Close() <PyHKEY.Close>`), + it is closed when the *hkey* object is destroyed by Python. .. function:: ConnectRegistry(computer_name, key) @@ -48,8 +44,8 @@ This module offers the following functions: Creates or opens the specified key, returning a :ref:`handle object <handle-object>`. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <hkey-constants>`. *sub_key* is a string that names the key this method opens or creates. @@ -67,15 +63,16 @@ This module offers the following functions: Creates or opens the specified key, returning a :ref:`handle object <handle-object>`. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <hkey-constants>`. *sub_key* is a string that names the key this method opens or creates. *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_ALL_ACCESS` + security access for the key. Default is :const:`KEY_ALL_ACCESS`. See + :ref:`Access Rights <access-rights>` for other allowed values. 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. @@ -92,8 +89,8 @@ This module offers the following functions: Deletes the specified key. - *key* is an already open key, or any one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <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. @@ -111,10 +108,11 @@ This module offers the following functions: .. note:: The :func:`DeleteKeyEx` function is implemented with the RegDeleteKeyEx Windows API function, which is specific to 64-bit versions of Windows. - See http://msdn.microsoft.com/en-us/library/ms724847%28VS.85%29.aspx + See the `RegDeleteKeyEx documentation + <http://msdn.microsoft.com/en-us/library/ms724847%28VS.85%29.aspx>`__. - *key* is an already open key, or any one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <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 @@ -123,7 +121,8 @@ This module offers the following functions: *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_WOW64_64KEY` + security access for the key. Default is :const:`KEY_ALL_ACCESS`. See + :ref:`Access Rights <access-rights>` for other allowed values. *This method can not delete keys with subkeys.* @@ -139,8 +138,8 @@ This module offers the following functions: Removes a named value from a registry key. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <hkey-constants>`. *value* is a string that identifies the value to remove. @@ -149,8 +148,8 @@ This module offers the following functions: 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. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <hkey-constants>`. *index* is an integer that identifies the index of the key to retrieve. @@ -163,8 +162,8 @@ This module offers the following functions: 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. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <hkey-constants>`. *index* is an integer that identifies the index of the value to retrieve. @@ -200,8 +199,8 @@ This module offers the following functions: Writes all the attributes of a key to the registry. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <hkey-constants>`. It is not necessary to call :func:`FlushKey` to change a key. Registry changes are flushed to disk by the registry using its lazy flusher. Registry changes are @@ -221,8 +220,8 @@ This module offers the following functions: 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. + *key* is a handle returned by :func:`ConnectRegistry` or one of the constants + :const:`HKEY_USERS` or :const:`HKEY_LOCAL_MACHINE`. *sub_key* is a string that identifies the sub_key to load. @@ -232,7 +231,9 @@ This module offers the following functions: 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. + from permissions -- see the `RegLoadKey documentation + <http://msdn.microsoft.com/en-us/library/ms724889%28v=VS.85%29.aspx>`__ for + more details. If *key* is a handle returned by :func:`ConnectRegistry`, then the path specified in *fileName* is relative to the remote computer. @@ -245,15 +246,16 @@ This module offers the following functions: Opens the specified key, returning a :ref:`handle object <handle-object>`. - *key* is an already open key, or any one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <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`. + security access for the key. Default is :const:`KEY_READ`. See + :ref:`Access Rights <access-rights>` for other allowed values. The result is a new handle to the specified key. @@ -270,8 +272,8 @@ This module offers the following functions: Returns information about a key, as a tuple. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <hkey-constants>`. The result is a tuple of 3 items: @@ -294,8 +296,8 @@ This module offers the following functions: Retrieves the unnamed value for a key, as a string. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <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 @@ -312,8 +314,8 @@ This module offers the following functions: 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. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <hkey-constants>`. *value_name* is a string indicating the value to query. @@ -333,8 +335,8 @@ This module offers the following functions: 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. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <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 @@ -344,8 +346,10 @@ This module offers the following functions: 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. + privileges are different than permissions -- see the + `Conflicts Between User Rights and Permissions documentation + <http://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__ + for more details. This function passes NULL for *security_attributes* to the API. @@ -354,8 +358,8 @@ This module offers the following functions: Associates a value with a specified key. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <hkey-constants>`. *sub_key* is a string that names the subkey with which the value is associated. @@ -380,42 +384,14 @@ This module offers the following functions: 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. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <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. | - +----------------------------------+---------------------------------------------+ + *type* is an integer that specifies the type of the data. See + :ref:`Value Types <value-types>` for the available types. *reserved* can be anything -- zero is always passed to the API. @@ -437,8 +413,8 @@ This module offers the following functions: Disables registry reflection for 32-bit processes running on a 64-bit Operating System. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <hkey-constants>`. Will generally raise :exc:`NotImplemented` if executed on a 32-bit Operating System. @@ -452,8 +428,8 @@ This module offers the following functions: Restores registry reflection for the specified disabled key. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <hkey-constants>`. Will generally raise :exc:`NotImplemented` if executed on a 32-bit Operating System. @@ -465,8 +441,8 @@ This module offers the following functions: Determines the reflection state for the specified key. - *key* is an already open key, or one of the predefined :const:`HKEY_\*` - constants. + *key* is an already open key, or one of the predefined + :ref:`HKEY_* constants <hkey-constants>`. Returns ``True`` if reflection is disabled. @@ -474,6 +450,195 @@ This module offers the following functions: Operating System. +.. _constants: + +Constants +------------------ + +The following constants are defined for use in many :mod:`_winreg` functions. + +.. _hkey-constants: + +HKEY_* Constants +++++++++++++++++ + +.. data:: HKEY_CLASSES_ROOT + + Registry entries subordinate to this key define types (or classes) of + documents and the properties associated with those types. Shell and + COM applications use the information stored under this key. + + +.. data:: HKEY_CURRENT_USER + + Registry entries subordinate to this key define the preferences of + the current user. These preferences include the settings of + environment variables, data about program groups, colors, printers, + network connections, and application preferences. + +.. data:: HKEY_LOCAL_MACHINE + + Registry entries subordinate to this key define the physical state + of the computer, including data about the bus type, system memory, + and installed hardware and software. + +.. data:: HKEY_USERS + + Registry entries subordinate to this key define the default user + configuration for new users on the local computer and the user + configuration for the current user. + +.. data:: HKEY_PERFORMANCE_DATA + + Registry entries subordinate to this key allow you to access + performance data. The data is not actually stored in the registry; + the registry functions cause the system to collect the data from + its source. + + +.. data:: HKEY_CURRENT_CONFIG + + Contains information about the current hardware profile of the + local computer system. + +.. data:: HKEY_DYN_DATA + + This key is not used in versions of Windows after 98. + + +.. _access-rights: + +Access Rights ++++++++++++++ + +For more information, see `Registry Key Security and Access +<http://msdn.microsoft.com/en-us/library/ms724878%28v=VS.85%29.aspx>`__. + +.. data:: KEY_ALL_ACCESS + + Combines the STANDARD_RIGHTS_REQUIRED, :const:`KEY_QUERY_VALUE`, + :const:`KEY_SET_VALUE`, :const:`KEY_CREATE_SUB_KEY`, + :const:`KEY_ENUMERATE_SUB_KEYS`, :const:`KEY_NOTIFY`, + and :const:`KEY_CREATE_LINK` access rights. + +.. data:: KEY_WRITE + + Combines the STANDARD_RIGHTS_WRITE, :const:`KEY_SET_VALUE`, and + :const:`KEY_CREATE_SUB_KEY` access rights. + +.. data:: KEY_READ + + Combines the STANDARD_RIGHTS_READ, :const:`KEY_QUERY_VALUE`, + :const:`KEY_ENUMERATE_SUB_KEYS`, and :const:`KEY_NOTIFY` values. + +.. data:: KEY_EXECUTE + + Equivalent to :const:`KEY_READ`. + +.. data:: KEY_QUERY_VALUE + + Required to query the values of a registry key. + +.. data:: KEY_SET_VALUE + + Required to create, delete, or set a registry value. + +.. data:: KEY_CREATE_SUB_KEY + + Required to create a subkey of a registry key. + +.. data:: KEY_ENUMERATE_SUB_KEYS + + Required to enumerate the subkeys of a registry key. + +.. data:: KEY_NOTIFY + + Required to request change notifications for a registry key or for + subkeys of a registry key. + +.. data:: KEY_CREATE_LINK + + Reserved for system use. + + +.. _64-bit-access-rights: + +64-bit Specific +*************** + +For more information, see `Accesing an Alternate Registry View +<http://msdn.microsoft.com/en-us/library/aa384129(v=VS.85).aspx>`__. + +.. data:: KEY_WOW64_64KEY + + Indicates that an application on 64-bit Windows should operate on + the 64-bit registry view. + +.. data:: KEY_WOW64_32KEY + + Indicates that an application on 64-bit Windows should operate on + the 32-bit registry view. + + +.. _value-types: + +Value Types ++++++++++++ + +For more information, see `Registry Value Types +<http://msdn.microsoft.com/en-us/library/ms724884%28v=VS.85%29.aspx>`__. + +.. data:: REG_BINARY + + Binary data in any form. + +.. data:: REG_DWORD + + 32-bit number. + +.. data:: REG_DWORD_LITTLE_ENDIAN + + A 32-bit number in little-endian format. + +.. data:: REG_DWORD_BIG_ENDIAN + + A 32-bit number in big-endian format. + +.. data:: REG_EXPAND_SZ + + Null-terminated string containing references to environment + variables (``%PATH%``). + +.. data:: REG_LINK + + A Unicode symbolic link. + +.. data:: REG_MULTI_SZ + + A sequence of null-terminated strings, terminated by two null characters. + (Python handles this termination automatically.) + +.. data:: REG_NONE + + No defined value type. + +.. data:: REG_RESOURCE_LIST + + A device-driver resource list. + +.. data:: REG_FULL_RESOURCE_DESCRIPTOR + + A hardware setting. + +.. data:: REG_RESOURCE_REQUIREMENTS_LIST + + A hardware resource list. + +.. data:: REG_SZ + + A null-terminated string. + + .. _handle-object: Registry Handle Objects |