diff options
Diffstat (limited to 'Doc/lib')
| -rw-r--r-- | Doc/lib/lib.tex | 1 | ||||
| -rw-r--r-- | Doc/lib/libwinreg.tex | 412 |
2 files changed, 413 insertions, 0 deletions
diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 549acdc..e04527e 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -275,6 +275,7 @@ and how to embed it in other applications. \input{windows} % MS Windows ONLY \input{libmsvcrt} +\input{libwinreg} \input{libwinsound} \input{libundoc} diff --git a/Doc/lib/libwinreg.tex b/Doc/lib/libwinreg.tex new file mode 100644 index 0000000..785a108 --- /dev/null +++ b/Doc/lib/libwinreg.tex @@ -0,0 +1,412 @@ +\section{\module{winreg} -- + Windows registry access} + +\declaremodule{extension}{winreg} + \platform{Windows} +\modulesynopsis{Routines and objects for manipulating the Windows registry.} +\sectionauthor{Mark Hammond}{MarkH@ActiveState.com} + +These functions exposes 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. + + +\subsection{Registry Operations \label{registry-operations}} + +\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 \code{'\\\\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: + \item[value_name] + A string that identifies the value name + \item[value_data] + An object that holds the value data, and whose type depends + on the underlying registry type. + \item[data_type] is an integer that identifies the type of the + value data. + +\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: + \item[num_subkeys] + An integer that identifies the number of sub keys this key has. + \item[num_values] + An integer that identifies the number of values this key has. + \item [last_modified] + A long integer that identifies when the key was last modified (if available) + as 100's of nanoseconds since Jan 1, 1600. +\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: + \item [value] + The value of the registry item. + \item [type_id] + An integer that identifies the registry type for this value. +\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: + \item[\constant{REG_BINARY}] + Binary data in any form. + \item[\constant{REG_DWORD}] + A 32-bit number. + \item[\constant{REG_DWORD_LITTLE_ENDIAN}] + A 32-bit number in little-endian format. + \item[\constant{REG_DWORD_BIG_ENDIAN}] + A 32-bit number in big-endian format. + \item[\constant{REG_EXPAND_SZ}] + A null-terminated string that contains unexpanded references + to environment variables (for example, \code{\%PATH\%}) + \item[\constant{REG_LINK}] + A Unicode symbolic link. + \item[\constant{REG_MULTI_SZ}] + A sequence (eg, list, sequence) of null-terminated strings, + terminated by two null characters. (Note that Python handles + this termination automatically) + \item[\constant{REG_NONE}] + No defined value type. + \item[\constant{REG_RESOURCE_LIST}] + A device-driver resource list. + \item[\constant{REG_SZ}] + A null-terminated string. + + \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 __nonzero__ - thus + \begin{verbatim} + if handle: + print "Yes" + \end{verbatim} + will print \code{Yes} if the handle is currently valid (ie, + 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} |