Doc/lib/libwinreg.tex

   1 \section{\module{_winreg} --
   2          Windows registry access}
   3
   4 \declaremodule[-winreg]{extension}{_winreg}
   5   \platform{Windows}
   6 \modulesynopsis{Routines and objects for manipulating the Windows registry.}
   7 \sectionauthor{Mark Hammond}{MarkH@ActiveState.com}
   8
   9 \versionadded{2.0}
  10
  11 These functions expose the Windows registry API to Python.  Instead of
  12 using an integer as the registry handle, a handle object is used to
  13 ensure that the handles are closed correctly, even if the programmer
  14 neglects to explicitly close them.
  15
  16 This module exposes a very low-level interface to the Windows
  17 registry; it is expected that in the future a new \code{winreg}
  18 module will be created offering a higher-level interface to the
  19 registry API.
  20
  21 This module offers the following functions:
  22
  23
  24 \begin{funcdesc}{CloseKey}{hkey}
  25  Closes a previously opened registry key.
  26  The hkey argument specifies a previously opened key.
  27
  28  Note that if \var{hkey} is not closed using this method, (or the
  29  \method{handle.Close()} closed when the \var{hkey} object is
  30  destroyed by Python.
  31 \end{funcdesc}
  32
  33
  34 \begin{funcdesc}{ConnectRegistry}{computer_name, key}
  35   Establishes a connection to a predefined registry handle on
  36   another computer, and returns a \dfn{handle object}
  37
  38  \var{computer_name} is the name of the remote computer, of the
  39  form \samp{\e\e computername}.  If \code{None}, the local computer
  40  is used.
  41
  42  \var{key} is the predefined handle to connect to.
  43
  44  The return value is the handle of the opened key.
  45  If the function fails, an \exception{EnvironmentError} exception is
  46  raised.
  47 \end{funcdesc}
  48
  49
  50 \begin{funcdesc}{CreateKey}{key, sub_key}
  51  Creates or opens the specified key, returning a \dfn{handle object}
  52
  53  \var{key} is an already open key, or one of the predefined
  54  \constant{HKEY_*} constants.
  55
  56  \var{sub_key} is a string that names the key this method opens
  57  or creates.
  58
  59  If \var{key} is one of the predefined keys, \var{sub_key} may
  60  be \code{None}. In that case, the handle returned is the same key handle
  61  passed in to the function.
  62
  63  If the key already exists, this function opens the existing key
  64
  65  The return value is the handle of the opened key.
  66  If the function fails, an \exception{EnvironmentError} exception is
  67  raised.
  68 \end{funcdesc}
  69
  70 \begin{funcdesc}{DeleteKey}{key, sub_key}
  71  Deletes the specified key.
  72
  73  \var{key} is an already open key, or any one of the predefined
  74  \constant{HKEY_*} constants.
  75
  76  \var{sub_key} is a string that must be a subkey of the key
  77  identified by the \var{key} parameter.  This value must not be
  78  \code{None}, and the key may not have subkeys.
  79
  80  \emph{This method can not delete keys with subkeys.}
  81
  82  If the method succeeds, the entire key, including all of its values,
  83  is removed.  If the method fails, an \exception{EnvironmentError}
  84  exception is raised.
  85 \end{funcdesc}
  86
  87
  88 \begin{funcdesc}{DeleteValue}{key, value}
  89   Removes a named value from a registry key.
  90
  91  \var{key} is an already open key, or one of the predefined
  92  \constant{HKEY_*} constants.
  93
  94  \var{value} is a string that identifies the value to remove.
  95 \end{funcdesc}
  96
  97
  98 \begin{funcdesc}{EnumKey}{key, index}
  99   Enumerates subkeys of an open registry key, returning a string.
 100
 101  \var{key} is an already open key, or any one of the predefined
 102  \constant{HKEY_*} constants.
 103
 104  \var{index} is an integer that identifies the index of the key to
 105  retrieve.
 106
 107  The function retrieves the name of one subkey each time it
 108  is called.  It is typically called repeatedly until an
 109  \exception{EnvironmentError} exception
 110  is raised, indicating, no more values are available.
 111 \end{funcdesc}
 112
 113
 114 \begin{funcdesc}{EnumValue}{key, index}
 115   Enumerates values of an open registry key, returning a tuple.
 116
 117  \var{key} is an already open key, or any one of the predefined
 118  \constant{HKEY_*} constants.
 119
 120  \var{index} is an integer that identifies the index of the value
 121  to retrieve.
 122
 123  The function retrieves the name of one subkey each time it is
 124  called. It is typically called repeatedly, until an
 125  \exception{EnvironmentError} exception is raised, indicating
 126  no more values.
 127
 128  The result is a tuple of 3 items:
 129  \item[value_name]
 130  A string that identifies the value name
 131  \item[value_data]
 132  An object that holds the value data, and whose type depends
 133  on the underlying registry type.
 134  \item[data_type] is an integer that identifies the type of the
 135  value data.
 136
 137 \end{funcdesc}
 138
 139
 140 \begin{funcdesc}{FlushKey}{key}
 141   Writes all the attributes of a key to the registry.
 142
 143  \var{key} is an already open key, or one of the predefined
 144  \constant{HKEY_*} constants.
 145
 146  It is not necessary to call RegFlushKey to change a key.
 147  Registry changes are flushed to disk by the registry using its lazy
 148  flusher.  Registry changes are also flushed to disk at system
 149  shutdown.  Unlike \function{CloseKey()}, the \function{FlushKey()} method
 150  returns only when all the data has been written to the registry.
 151  An application should only call \function{FlushKey()} if it requires absolute
 152  certainty that registry changes are on disk.
 153
 154  \emph{If you don't know whether a \function{FlushKey()} call is required, it
 155  probably isn't.}
 156
 157 \end{funcdesc}
 158
 159
 160 \begin{funcdesc}{RegLoadKey}{key, sub_key, file_name}
 161  Creates a subkey under the specified key and stores registration
 162  information from a specified file into that subkey.
 163
 164  \var{key} is an already open key, or any of the predefined
 165  \constant{HKEY_*} constants.
 166
 167  \var{sub_key} is a string that identifies the sub_key to load
 168
 169  \var {file_name} is the name of the file to load registry data from.
 170   This file must have been created with the \function{SaveKey()} function.
 171   Under the file allocation table (FAT) file system, the filename may not
 172   have an extension.
 173
 174  A call to LoadKey() fails if the calling process does not have the
 175  \constant{SE_RESTORE_PRIVILEGE} privilege. Note that privileges
 176  are different than permissions - see the Win32 documentation for
 177  more details.
 178
 179  If \var{key} is a handle returned by \function{ConnectRegistry()},
 180  then the path specified in \var{fileName} is relative to the
 181  remote computer.
 182
 183  The Win32 documentation implies \var{key} must be in the
 184  \constant{HKEY_USER} or \constant{HKEY_LOCAL_MACHINE} tree.
 185  This may or may not be true.
 186 \end{funcdesc}
 187
 188
 189 \begin{funcdesc}{OpenKey}{key, sub_key\optional{, res\code{ = 0}}\optional{, sam\code{ = \constant{KEY_READ}}}}
 190   Opens the specified key, returning a \dfn{handle object}
 191
 192  \var{key} is an already open key, or any one of the predefined
 193  \constant{HKEY_*} constants.
 194
 195  \var{sub_key} is a string that identifies the sub_key to open
 196
 197  \var{res} is a reserved integer, and must be zero.  The default is zero.
 198
 199  \var{sam} is an integer that specifies an access mask that describes
 200  the desired security access for the key.  Default is \constant{KEY_READ}
 201
 202  The result is a new handle to the specified key
 203
 204  If the function fails, \exception{EnvironmentError} is raised.
 205 \end{funcdesc}
 206
 207
 208 \begin{funcdesc}{OpenKeyEx}{}
 209   The functionality of \function{OpenKeyEx()} is provided via
 210   \function{OpenKey()}, by the use of default arguments.
 211 \end{funcdesc}
 212
 213
 214 \begin{funcdesc}{QueryInfoKey}{key}
 215  Returns information about a key, as a tuple.
 216
 217  \var{key} is an already open key, or one of the predefined
 218  \constant{HKEY_*} constants.
 219
 220  The result is a tuple of 3 items:
 221  \item[num_subkeys]
 222  An integer that identifies the number of sub keys this key has.
 223  \item[num_values]
 224  An integer that identifies the number of values this key has.
 225  \item [last_modified]
 226  A long integer that identifies when the key was last modified (if available)
 227  as 100's of nanoseconds since Jan 1, 1600.
 228 \end{funcdesc}
 229
 230
 231 \begin{funcdesc}{QueryValue}{key, sub_key}
 232  Retrieves the unnamed value for a key, as a string
 233
 234  \var{key} is an already open key, or one of the predefined
 235  \constant{HKEY_*} constants.
 236
 237  \var{sub_key} is a string that holds the name of the subkey with which
 238  the value is associated.  If this parameter is \code{None} or empty, the
 239  function retrieves the value set by the \function{SetValue()} method
 240  for the key identified by \var{key}.
 241
 242  Values in the registry have name, type, and data components. This
 243  method retrieves the data for a key's first value that has a NULL name.
 244  But the underlying API call doesn't return the type, Lame Lame Lame,
 245  DO NOT USE THIS!!!
 246 \end{funcdesc}
 247
 248
 249 \begin{funcdesc}{QueryValueEx}{key, value_name}
 250   Retrieves the type and data for a specified value name associated with
 251   an open registry key.
 252
 253  \var{key} is an already open key, or one of the predefined
 254  \constant{HKEY_*} constants.
 255
 256  \var{value_name} is a string indicating the value to query.
 257
 258  The result is a tuple of 2 items:
 259  \item [value]
 260  The value of the registry item.
 261  \item [type_id]
 262  An integer that identifies the registry type for this value.
 263 \end{funcdesc}
 264
 265
 266 \begin{funcdesc}{SaveKey}{key, file_name}
 267   Saves the specified key, and all its subkeys to the specified file.
 268
 269  \var{key} is an already open key, or one of the predefined
 270  \constant{HKEY_*} constants.
 271
 272  \var{file_name} is the name of the file to save registry data to.
 273   This file cannot already exist. If this filename includes an extension,
 274   it cannot be used on file allocation table (FAT) file systems by the
 275   \method{LoadKey()}, \method{ReplaceKey()} or
 276   \method{RestoreKey()} methods.
 277
 278  If \var{key} represents a key on a remote computer, the path
 279  described by \var{file_name} is relative to the remote computer.
 280  The caller of this method must possess the \constant{SeBackupPrivilege}
 281  security privilege.  Note that privileges are different than permissions
 282  - see the Win32 documentation for more details.
 283
 284  This function passes NULL for \var{security_attributes} to the API.
 285 \end{funcdesc}
 286
 287
 288 \begin{funcdesc}{SetValue}{key, sub_key, type, value}
 289  Associates a value with a specified key.
 290
 291  \var{key} is an already open key, or one of the predefined
 292  \constant{HKEY_*} constants.
 293
 294  \var{sub_key} is a string that names the subkey with which the value
 295  is associated.
 296
 297  \var{type} is an integer that specifies the type of the data.  Currently this
 298  must be \constant{REG_SZ}, meaning only strings are supported.
 299  Use the \function{SetValueEx()} function for support for other data types.
 300
 301  \var{value} is a string that specifies the new value.
 302
 303  If the key specified by the \var{sub_key} parameter does not exist,
 304  the SetValue function creates it.
 305
 306  Value lengths are limited by available memory. Long values (more than
 307  2048 bytes) should be stored as files with the filenames stored in
 308  the configuration registry.  This helps the registry perform efficiently.
 309
 310  The key identified by the \var{key} parameter must have been
 311  opened with \constant{KEY_SET_VALUE} access.
 312 \end{funcdesc}
 313
 314
 315 \begin{funcdesc}{SetValueEx}{key, value_name, reserved, type, value}
 316   Stores data in the value field of an open registry key.
 317
 318  \var{key} is an already open key, or one of the predefined
 319  \constant{HKEY_*} constants.
 320
 321  \var{sub_key} is a string that names the subkey with which the
 322  value is associated.
 323
 324  \var{type} is an integer that specifies the type of the data.
 325  This should be one of:
 326  \item[\constant{REG_BINARY}]
 327         Binary data in any form.
 328  \item[\constant{REG_DWORD}]
 329         A 32-bit number.
 330  \item[\constant{REG_DWORD_LITTLE_ENDIAN}]
 331         A 32-bit number in little-endian format.
 332  \item[\constant{REG_DWORD_BIG_ENDIAN}]
 333         A 32-bit number in big-endian format.
 334  \item[\constant{REG_EXPAND_SZ}]
 335         A null-terminated string that contains unexpanded references
 336         to environment variables (for example, \code{\%PATH\%})
 337  \item[\constant{REG_LINK}]
 338         A Unicode symbolic link.
 339  \item[\constant{REG_MULTI_SZ}]
 340         A sequence (eg, list, sequence) of null-terminated strings,
 341         terminated by two null characters. (Note that Python handles
 342         this termination automatically)
 343  \item[\constant{REG_NONE}]
 344         No defined value type.
 345  \item[\constant{REG_RESOURCE_LIST}]
 346         A device-driver resource list.
 347  \item[\constant{REG_SZ}]
 348         A null-terminated string.
 349
 350  \var{reserved} can be anything - zero is always passed to the
 351  API.
 352
 353  \var{value} is a string that specifies the new value.
 354
 355  This method can also set additional value and type information for the
 356  specified key.  The key identified by the key parameter must have been
 357  opened with \constant{KEY_SET_VALUE} access.
 358
 359  To open the key, use the \function{CreateKeyEx()} or
 360  \function{OpenKey()} methods.
 361
 362  Value lengths are limited by available memory. Long values (more than
 363  2048 bytes) should be stored as files with the filenames stored in
 364  the configuration registry.  This helps the registry perform efficiently.
 365 \end{funcdesc}
 366
 367
 368
 369 \subsection{Registry handle objects \label{handle-object}}
 370
 371  This object wraps a Windows HKEY object, automatically closing it when
 372  the object is destroyed.  To guarantee cleanup, you can call either
 373  the \method{Close()} method on the object, or the
 374  \function{CloseKey()} function.
 375
 376  All registry functions in this module return one of these objects.
 377
 378  All registry functions in this module which accept a handle object
 379  also accept an integer, however, use of the handle object is
 380  encouraged.
 381
 382  Handle objects provide semantics for \method{__nonzero__()} - thus
 383 \begin{verbatim}
 384     if handle:
 385         print "Yes"
 386 \end{verbatim}
 387  will print \code{Yes} if the handle is currently valid (i.e.,
 388  has not been closed or detached).
 389
 390  The object also support comparison semantics, so handle
 391  objects will compare true if they both reference the same
 392  underlying Windows handle value.
 393
 394  Handle objects can be converted to an integer (eg, using the
 395  builtin \function{int()} function, in which case the underlying
 396  Windows handle value is returned.  You can also use the
 397  \method{Detach()} method to return the integer handle, and
 398  also disconnect the Windows handle from the handle object.
 399
 400 \begin{methoddesc}{Close}{}
 401   Closes the underlying Windows handle.
 402
 403   If the handle is already closed, no error is raised.
 404 \end{methoddesc}
 405
 406
 407 \begin{methoddesc}{Detach}{}
 408   Detaches the Windows handle from the handle object.
 409
 410  The result is an integer (or long on 64 bit Windows) that holds
 411  the value of the handle before it is detached.  If the
 412  handle is already detached or closed, this will return zero.
 413
 414  After calling this function, the handle is effectively invalidated,
 415  but the handle is not closed.  You would call this function when
 416  you need the underlying Win32 handle to exist beyond the lifetime
 417  of the handle object.
 418 \end{methoddesc}