415 lines
14 KiB
TeX
415 lines
14 KiB
TeX
\section{\module{_winreg} --
|
|
Windows registry access}
|
|
|
|
\declaremodule[-winreg]{extension}{_winreg}
|
|
\platform{Windows}
|
|
\modulesynopsis{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 \code{winreg}
|
|
module will be created offering a higher-level interface to the
|
|
registry API.
|
|
|
|
This module offers the following functions:
|
|
|
|
|
|
\begin{funcdesc}{CloseKey}{hkey}
|
|
Closes a previously opened registry key.
|
|
The hkey argument specifies a previously opened key.
|
|
|
|
Note that if \var{hkey} is not closed using this method, (or the
|
|
\method{handle.Close()} closed when the \var{hkey} object is
|
|
destroyed by Python.
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{ConnectRegistry}{computer_name, key}
|
|
Establishes a connection to a predefined registry handle on
|
|
another computer, and returns a \dfn{handle object}
|
|
|
|
\var{computer_name} is the name of the remote computer, of the
|
|
form \samp{\e\e computername}. If \code{None}, the local computer
|
|
is used.
|
|
|
|
\var{key} is the predefined handle to connect to.
|
|
|
|
The return value is the handle of the opened key.
|
|
If the function fails, an \exception{EnvironmentError} exception is
|
|
raised.
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{CreateKey}{key, sub_key}
|
|
Creates or opens the specified key, returning a \dfn{handle object}
|
|
|
|
\var{key} is an already open key, or one of the predefined
|
|
\constant{HKEY_*} constants.
|
|
|
|
\var{sub_key} is a string that names the key this method opens
|
|
or creates.
|
|
|
|
If \var{key} is one of the predefined keys, \var{sub_key} may
|
|
be \code{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 \exception{EnvironmentError} exception is
|
|
raised.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{DeleteKey}{key, sub_key}
|
|
Deletes the specified key.
|
|
|
|
\var{key} is an already open key, or any one of the predefined
|
|
\constant{HKEY_*} constants.
|
|
|
|
\var{sub_key} is a string that must be a subkey of the key
|
|
identified by the \var{key} parameter. This value must not be
|
|
\code{None}, and the key may not have subkeys.
|
|
|
|
\emph{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 \exception{EnvironmentError}
|
|
exception is raised.
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{DeleteValue}{key, value}
|
|
Removes a named value from a registry key.
|
|
|
|
\var{key} is an already open key, or one of the predefined
|
|
\constant{HKEY_*} constants.
|
|
|
|
\var{value} is a string that identifies the value to remove.
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{EnumKey}{key, index}
|
|
Enumerates subkeys of an open registry key, returning a string.
|
|
|
|
\var{key} is an already open key, or any one of the predefined
|
|
\constant{HKEY_*} constants.
|
|
|
|
\var{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
|
|
\exception{EnvironmentError} exception
|
|
is raised, indicating, no more values are available.
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{EnumValue}{key, index}
|
|
Enumerates values of an open registry key, returning a tuple.
|
|
|
|
\var{key} is an already open key, or any one of the predefined
|
|
\constant{HKEY_*} constants.
|
|
|
|
\var{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
|
|
\exception{EnvironmentError} exception is raised, indicating
|
|
no more values.
|
|
|
|
The result is a tuple of 3 items:
|
|
|
|
\begin{tableii}{c|p{3in}}{code}{Index}{Meaning}
|
|
\lineii{0}{A string that identifies the value name}
|
|
\lineii{1}{An object that holds the value data, and whose
|
|
type depends on the underlying registry type}
|
|
\lineii{2}{An integer that identifies the type of the value data}
|
|
\end{tableii}
|
|
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{FlushKey}{key}
|
|
Writes all the attributes of a key to the registry.
|
|
|
|
\var{key} is an already open key, or one of the predefined
|
|
\constant{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 \function{CloseKey()}, the \function{FlushKey()} method
|
|
returns only when all the data has been written to the registry.
|
|
An application should only call \function{FlushKey()} if it requires absolute
|
|
certainty that registry changes are on disk.
|
|
|
|
\emph{If you don't know whether a \function{FlushKey()} call is required, it
|
|
probably isn't.}
|
|
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{RegLoadKey}{key, sub_key, file_name}
|
|
Creates a subkey under the specified key and stores registration
|
|
information from a specified file into that subkey.
|
|
|
|
\var{key} is an already open key, or any of the predefined
|
|
\constant{HKEY_*} constants.
|
|
|
|
\var{sub_key} is a string that identifies the sub_key to load
|
|
|
|
\var {file_name} is the name of the file to load registry data from.
|
|
This file must have been created with the \function{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
|
|
\constant{SE_RESTORE_PRIVILEGE} privilege. Note that privileges
|
|
are different than permissions - see the Win32 documentation for
|
|
more details.
|
|
|
|
If \var{key} is a handle returned by \function{ConnectRegistry()},
|
|
then the path specified in \var{fileName} is relative to the
|
|
remote computer.
|
|
|
|
The Win32 documentation implies \var{key} must be in the
|
|
\constant{HKEY_USER} or \constant{HKEY_LOCAL_MACHINE} tree.
|
|
This may or may not be true.
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{OpenKey}{key, sub_key\optional{, res\code{ = 0}}\optional{, sam\code{ = \constant{KEY_READ}}}}
|
|
Opens the specified key, returning a \dfn{handle object}
|
|
|
|
\var{key} is an already open key, or any one of the predefined
|
|
\constant{HKEY_*} constants.
|
|
|
|
\var{sub_key} is a string that identifies the sub_key to open
|
|
|
|
\var{res} is a reserved integer, and must be zero. The default is zero.
|
|
|
|
\var{sam} is an integer that specifies an access mask that describes
|
|
the desired security access for the key. Default is \constant{KEY_READ}
|
|
|
|
The result is a new handle to the specified key
|
|
|
|
If the function fails, \exception{EnvironmentError} is raised.
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{OpenKeyEx}{}
|
|
The functionality of \function{OpenKeyEx()} is provided via
|
|
\function{OpenKey()}, by the use of default arguments.
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{QueryInfoKey}{key}
|
|
Returns information about a key, as a tuple.
|
|
|
|
\var{key} is an already open key, or one of the predefined
|
|
\constant{HKEY_*} constants.
|
|
|
|
The result is a tuple of 3 items:
|
|
|
|
\begin{tableii}{c|p{3in}}{code}{Index}{Meaning}
|
|
\lineii{0}{An integer giving the number of sub keys this key has.}
|
|
\lineii{1}{An integer giving the number of values this key has.}
|
|
\lineii{2}{A long integer giving when the key was last modified (if
|
|
available) as 100's of nanoseconds since Jan 1, 1600.}
|
|
\end{tableii}
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{QueryValue}{key, sub_key}
|
|
Retrieves the unnamed value for a key, as a string
|
|
|
|
\var{key} is an already open key, or one of the predefined
|
|
\constant{HKEY_*} constants.
|
|
|
|
\var{sub_key} is a string that holds the name of the subkey with which
|
|
the value is associated. If this parameter is \code{None} or empty, the
|
|
function retrieves the value set by the \function{SetValue()} method
|
|
for the key identified by \var{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!!!
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{QueryValueEx}{key, value_name}
|
|
Retrieves the type and data for a specified value name associated with
|
|
an open registry key.
|
|
|
|
\var{key} is an already open key, or one of the predefined
|
|
\constant{HKEY_*} constants.
|
|
|
|
\var{value_name} is a string indicating the value to query.
|
|
|
|
The result is a tuple of 2 items:
|
|
|
|
\begin{tableii}{c|p{3in}}{code}{Index}{Meaning}
|
|
\lineii{0}{The value of the registry item.}
|
|
\lineii{1}{An integer giving the registry type for this value.}
|
|
\end{tableii}
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{SaveKey}{key, file_name}
|
|
Saves the specified key, and all its subkeys to the specified file.
|
|
|
|
\var{key} is an already open key, or one of the predefined
|
|
\constant{HKEY_*} constants.
|
|
|
|
\var{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
|
|
\method{LoadKey()}, \method{ReplaceKey()} or
|
|
\method{RestoreKey()} methods.
|
|
|
|
If \var{key} represents a key on a remote computer, the path
|
|
described by \var{file_name} is relative to the remote computer.
|
|
The caller of this method must possess the \constant{SeBackupPrivilege}
|
|
security privilege. Note that privileges are different than permissions
|
|
- see the Win32 documentation for more details.
|
|
|
|
This function passes NULL for \var{security_attributes} to the API.
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{SetValue}{key, sub_key, type, value}
|
|
Associates a value with a specified key.
|
|
|
|
\var{key} is an already open key, or one of the predefined
|
|
\constant{HKEY_*} constants.
|
|
|
|
\var{sub_key} is a string that names the subkey with which the value
|
|
is associated.
|
|
|
|
\var{type} is an integer that specifies the type of the data.
|
|
Currently this must be \constant{REG_SZ}, meaning only strings are
|
|
supported. Use the \function{SetValueEx()} function for support for
|
|
other data types.
|
|
|
|
\var{value} is a string that specifies the new value.
|
|
|
|
If the key specified by the \var{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 \var{key} parameter must have been
|
|
opened with \constant{KEY_SET_VALUE} access.
|
|
\end{funcdesc}
|
|
|
|
|
|
\begin{funcdesc}{SetValueEx}{key, value_name, reserved, type, value}
|
|
Stores data in the value field of an open registry key.
|
|
|
|
\var{key} is an already open key, or one of the predefined
|
|
\constant{HKEY_*} constants.
|
|
|
|
\var{sub_key} is a string that names the subkey with which the
|
|
value is associated.
|
|
|
|
\var{type} is an integer that specifies the type of the data.
|
|
This should be one of the following constants defined in this module:
|
|
|
|
\begin{tableii}{l|p{3in}}{constant}{Constant}{Meaning}
|
|
\lineii{REG_BINARY}{Binary data in any form.}
|
|
\lineii{REG_DWORD}{A 32-bit number.}
|
|
\lineii{REG_DWORD_LITTLE_ENDIAN}{A 32-bit number in little-endian format.}
|
|
\lineii{REG_DWORD_BIG_ENDIAN}{A 32-bit number in big-endian format.}
|
|
\lineii{REG_EXPAND_SZ}{Null-terminated string containing references
|
|
to environment variables (\samp{\%PATH\%}).}
|
|
\lineii{REG_LINK}{A Unicode symbolic link.}
|
|
\lineii{REG_MULTI_SZ}{A sequence of null-terminated strings,
|
|
terminated by two null characters. (Python handles
|
|
this termination automatically.)}
|
|
\lineii{REG_NONE}{No defined value type.}
|
|
\lineii{REG_RESOURCE_LIST}{A device-driver resource list.}
|
|
\lineii{REG_SZ}{A null-terminated string.}
|
|
\end{tableii}
|
|
|
|
\var{reserved} can be anything - zero is always passed to the
|
|
API.
|
|
|
|
\var{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 \constant{KEY_SET_VALUE} access.
|
|
|
|
To open the key, use the \function{CreateKeyEx()} or
|
|
\function{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.
|
|
\end{funcdesc}
|
|
|
|
|
|
|
|
\subsection{Registry Handle Objects \label{handle-object}}
|
|
|
|
This object wraps a Windows HKEY object, automatically closing it when
|
|
the object is destroyed. To guarantee cleanup, you can call either
|
|
the \method{Close()} method on the object, or the
|
|
\function{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 \method{__nonzero__()} - thus
|
|
\begin{verbatim}
|
|
if handle:
|
|
print "Yes"
|
|
\end{verbatim}
|
|
will print \code{Yes} if the handle is currently valid (i.e.,
|
|
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 (eg, using the
|
|
builtin \function{int()} function, in which case the underlying
|
|
Windows handle value is returned. You can also use the
|
|
\method{Detach()} method to return the integer handle, and
|
|
also disconnect the Windows handle from the handle object.
|
|
|
|
\begin{methoddesc}{Close}{}
|
|
Closes the underlying Windows handle.
|
|
|
|
If the handle is already closed, no error is raised.
|
|
\end{methoddesc}
|
|
|
|
|
|
\begin{methoddesc}{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.
|
|
\end{methoddesc}
|