diff options
Diffstat (limited to 'Doc/lib/libwinreg.tex')
| -rw-r--r-- | Doc/lib/libwinreg.tex | 414 |
1 files changed, 0 insertions, 414 deletions
diff --git a/Doc/lib/libwinreg.tex b/Doc/lib/libwinreg.tex deleted file mode 100644 index d31c3ca..0000000 --- a/Doc/lib/libwinreg.tex +++ /dev/null @@ -1,414 +0,0 @@ -\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 via - \method{handle.Close()}), it is 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{r"\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. - - \note{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{value_name} 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{__bool__()} - thus -\begin{verbatim} - if handle: - print "Yes" -\end{verbatim} - will print \code{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 \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}[PyHKEY]{Close}{} - Closes the underlying Windows handle. - - If the handle is already closed, no error is raised. -\end{methoddesc} - - -\begin{methoddesc}[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. -\end{methoddesc} |