Added preliminary documentation for the winreg module,
by Mark Hammond <markh@activestate.com>.
Limited markup & consistency revisions by FLD.
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}