Added preliminary documentation for the winreg module,

by Mark Hammond <markh@activestate.com>.

Limited markup & consistency revisions by FLD.

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}