Tcl Windows API extension

This module contains commands dealing with the Windows registry and supplants the registry package that is included with the Tcl core distribution. The commands in the Tcl registry package are in most cases easier to use and may in many cases be more performant as well. This package is useful to fill in missing capabilities there such as accessing security descriptors, receiving change notifications and back up / restore. The package also provides some utility commands for iteration etc and certain bulk operations may also be more efficient through the explicit ues of registry handles in this package.

Predefined keys

The following registry key handles are predefined: HKEY_CLASSES_ROOT (or HKCR), HKEY_CURRENT_USER (or HKCU), HKEY_LOCAL_MACHINE (or HKLM), HKEY_CURRENT_CONFIG (or HKCC), HKEY_USERS (or HKU), HKEY_PERFORMANCE_DATA, HKEY_PERFORMANCE_TEXT, HKEY_PERFORMANCE_NLSTEXT or HKEY_CURRENT_USER_LOCAL_SETTINGS. These may be directly passed as key handles without an explicit call to reg_key_open or reg_key_create.

Registry data types

The data stored in the registry may be one of several types listed below. When setting or retrieving registry data, the value is always paired with its type.

binary	Binary data represented in Tcl as a binary string.
dword	32-bit integer in little-endian format represented in Tcl as a decimal string.
dword_be	32-bit integer in big-endian format represented in Tcl as a decimal string.
expand_sz	Same as the sz type but expected to contain environment variables that should be expanded.
link	Symbolic link and represented in Tcl as a binary string.
multi_sz	List of strings represented in Tcl as such.
qword	64-bit little-endian format integer represented in Tcl as a decimal string.
resource_descriptor	Resource descriptor represented in Tcl as a binary string.
resource_list	Resource list represented in Tcl as a binary string.
resource_requirements_list	Resource requirements list represented in Tcl as a binary string.
sz	Null-terminated text represented as a Tcl string.

Command may return registry value either in raw or cooked form. The former is returned as a pair consisting of a data type from the list above and the corresponding data value. A cooked value returns only the data value which is also transformed based on the type. In particular, data of type dword_be are converted to native format, expand_sz have embedded environment variables expanded.

Registry commands

reg_connect SYSTEM HPREDEFINE

Returns a handle to a predefined registry key on a remote system. SYSTEM specifies the name of the remote system. HPREDEFINE must be one of the predefined keys HKEY_USERS, HKEY_LOCAL_MACHINE or HKEY_PERFORMANCE_DATA.

reg_disable_current_user_cache

Disables the caching of the HKEY_CURRENT_USER handle for the current process.

reg_iterator HKEY ?SUBKEYPATH?

Returns an iterator command that can be invoked to iterate over all keys in the tree rooted at HKEY. If a non-empty SUBKEYPATH argument is specified, it must a path to a subkey under HKEY and the iteration is carried out over its subtree instead.

The returned iterator command should be invoked with zero or one argument. If invoked with no arguments or the argument next, the iterator returns the next item in the iteration. If invoked with an argument of sibling, the iterator returns the next key at the same level at the current level skipping over the children of the key that was last returned. The parentsibling is similar except that it skips the remaining keys at the same level as the current level and returns the parent's sibling. Finally, the argument stop will end the iteration (even if more items remain). Any further attempt to invoke the iterator command will result in an error being raised.

The return value from the iterator invocation is a list of two elements. The first element is the handle to the current key. This handle must not be closed or modified in any way. The second element is the key path to the key as a list of key names starting with SUBKEYPATH or HKEY if the former was not specified.

The iterator will return an empty list when no more items remain. Invoking it again will raise an error.

reg_key_close HKEY

Releases the passed registry key handle. HKEY must not be one of the predefined registry handles.

reg_key_copy HFROM HTO ?-subkey SUBKEYPATH? ?-copysecd BOOL?

Copies the subtree under a registry key to another registry key. The source key is specified by HFROM which must be a handle to a registry key. If the -subkey option is specified it must be a path to subkey under HFROM and the source tree is then copied from there. The target key identified by its handle HTO must have been opened with the appropriate access permissions.

The -copysecd option controls whether the security descriptors in the source tree are also to be copied. If true, the descriptors are copied as well. The default is false. The option must be false on Windows XP and Windows 2003 as otherwise the copy will fail.

reg_key_create HKEY SUBKEYPATH ?options?

Returns a handle to a registry key. HKEY must be a handle to a registry key as returned by a prior call to reg_key_open, reg_key_create etc. or a predefined key handle such as HKEY_LOCAL_MACHINE. SUBKEYPATH is the path to the subkey to be created under HKEY. It is not an error if the subkey already exists. In that case, it is opened and its handle returned. The following options may be specified:

-access ACCESSRIGHTS	Specifies the desired access rights and may be specified as a list of integer access rights flags or symbols as described in Access Rights. Defaults to generic_read.
-backup BOOL	If true, the key opened with access required for backup and restore. The -access option is ignored. Default is false.
-disposition VARNAME	If specified, VARNAME is treated as a variable name in caller's context and is set to created if the key was created and existed if it was already present.
-inherit BOOL	If true, the returned handle is inheritable by child processes. Defaults to false.
-secd SECURITY_DESCRIPTOR	Specifies a security descriptor to be attached to the file or device if it has to be created. Defaults to a null security descriptor which results in the process' default security descriptor being applied.
-volatile BOOL	If true, the key is only stored in memory and not preserved to disk when the registry hive is unloaded. Default is false.

The returned key handle should be released by calling the reg_key_close command.

reg_key_current_user ?options?

Returns a handle to the HKEY_CURRENT_USER key for the user that the current thread is impersonating. Note this is not necessarily the same as the HKEY_CURRENT_USER handle cached for the process. If the user profile is not loaded, the default profile is used.

The following options may be specified:

-access ACCESSRIGHTS

Specifies the desired access rights and may be specified as a list of integer access rights flags or symbols as described in Access Rights. Defaults to generic_read.

reg_key_delete HKEY SUBKEYPATH

Deletes the key identified by the key path SUBKEYPATH under the key specified by the handle HKEY and any values it contains. The key must not have any subkeys. No error is raised if the key does not exist.

reg_key_export HKEY FILEPATH ?options?

Exports a key and its contents to the file FILEPATH. The following options may be specified.

-format FORMAT	Specifies the format for the file. FORMAT must be one of win2k or xp. Default is xp which is not readable on earlier (pre-XP) Windows systems.
-secd SECD	Specifies a security descriptor to use when creating the file.

reg_key_import HKEY FILEPATH ?options?

Imports an exported registry key from a file. The following options may be specified.

-force BOOL	If true, the file is imported even if there are open handles under HKEY. Default is false.
-volatile BOOL	If true, a new volatile hive is created into which the file is imported. In this case, HKEY must be HKEY_USERS or HKEY_LOCAL_MACHINE. Default is false.

reg_key_load HKEY SUBKEYPATH REGFILE

Creates a key SUBKEYPATH under HKEY and loads the contents of the file REGFILE under it. HKEY must be one of the predefined keys HKEY_LOCAL_MACHINE or HKEY_USERS or a handle returned by reg_connect. REGFILE must be a file in the format saved by reg_key_export. The reg_key_unload command may be used to undo the operation.

Note the caller process must be running with SE_BACKUP_NAME and SE_RESTORE_NAME privileges.

reg_key_unload HKEY SUBKEYPATH

Unloads the registry hive at key path SUBKEYPATH under the key with handle HKEY. HKEY must be one of the predefined keys HKEY_LOCAL_MACHINE or HKEY_USERS or a handle returned by reg_connect. This reverses the effect of the reg_key_load command. Note the caller process must be running with SE_BACKUP_NAME and SE_RESTORE_NAME privileges.

reg_key_monitor HKEY HEVENT ?options?

Monitors a registry key for changes. When a change is detected the event HEVENT is set. HEVENT must be a handle to an event as returned by create_event. The event will be signalled when the key changes. The caller can wait on the passed event or register a callback using the wait_on_handle command.

Note the following important points about asynchronous operation:

The event is signalled only once. To continue to receive notifications, the command must be called again on the handle.
Moreover, the command must not be called on the key handle again until the previously registered notification request has been signalled.

The following options control the types of changes that are monitored.

-attr BOOL	Monitors changes in key attributes like security descriptors.
-keys BOOL	Monitors addition and deletion of immediate child keys to the specified key.
-secd BOOL	Monitors changes to the security attributes.
-subtree BOOL	Monitors the entire tree below the specified key. If false (default), only monitors the specified key.
-values BOOL	Monitors changes to the values in the key including additions and deletions.

If none of the options -attr, -keys, -secd and -values are specified as true, all are enabled.

reg_key_open HKEY SUBKEYPATH ?options?

Returns a handle to a registry key. HKEY must be a handle to a registry key as returned by a prior call to reg_key_open, reg_key_create etc. or a predefined key handle such as HKEY_LOCAL_MACHINE. SUBKEYPATH is the path to the subkey under HKEY whose handle is to be returned. The following options may be specified:

-access ACCESSRIGHTS

Specifies the desired access rights and may be specified as a list of integer access rights flags or symbols as described in Access Rights. Defaults to generic_read.

The command will raise an error if the specified key does not exist. The returned key handle should be released by calling the reg_key_close command.

reg_key_override HPREDEFINED HKEY

Maps a predefined key with handle HPREDEFINE to the key with handle HKEY. This will cause all access to HPREDEFINED to be redirected to HKEY. The override can be reversed by calling reg_key_override_undo. HPREDEFINED must be one of the predefined keys HKEY_CLASSES_ROOT, HKEY_CURRENT_CONFIG, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_USERS or HKEY_PERFORMANCE_DATA.

reg_key_override_undo HPREDEFINED

Undoes the effect of a previous call to reg_key_override. HPREDEFINED must be one of the predefined keys HKEY_CLASSES_ROOT, HKEY_CURRENT_CONFIG, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_USERS or HKEY_PERFORMANCE_DATA.

reg_key_prune HKEY SUBKEYPATH

Deletes the tree rooted at the key identified by the key path SUBKEYPATH under the key specified by the handle HKEY. No error is raised if the key does not exist.

reg_key_user_classes_root USERTOKEN ?options?

Returns a handle to the merged HKEY_CLASSES_ROOT key for the user corresponding to the passed USERTOKEN which must be a user token as returned by open_user_token, open_process_token, open_thread_token etc. The following options may be specified:

-access ACCESSRIGHTS

Specifies the desired access rights and may be specified as a list of integer access rights flags or symbols as described in Access Rights. Defaults to generic_read.

reg_keys HKEY ?SUBKEYPATH?

Returns the list of keys under the key SUBKEYPATH under the handle HKEY. If SUBKEYPATH is not specified or is empty, keys under HKEY are returned.

reg_tree HKEY ?SUBKEYPATH?

Returns a list of key paths of the keys in the subtree under a registry key. If SUBKEYPATH is specified, it identifies the path under HKEY for the subtree. If SUBTREE is not specified or empty the paths under HKEY itself are returned.

The returned paths are all relative to root of the subtree. Note that the empty string corresponding to the root is also returned.

reg_tree_values HKEY ?SUBKEYPATH?

Returns a registry subtree in the form of a nested dictionary mapping keys to their values. SUBKEYPATH is the registry path relative to HKEY iterate over. If unspecified, the root of the tree is HKEY itself.

The keys of the returned dictionary are the relative key paths in the subtree. Thus the tree includes an empty string as a dictionary key corresponding to the root of the subtree. The dictionary content for each key is itself a dictionary mapping value names contained in the key to their content in cooked form.

reg_tree_values_raw HKEY ?SUBKEYPATH?

Returns a registry subtree in the form of a nested dictionary mapping keys to their values. SUBKEYPATH is the registry path relative to HKEY iterate over. If unspecified, the root of the tree is HKEY itself.

The keys of the returned dictionary are the relative key paths in the subtree. The corresponding dictionary element is itself a dictionary mapping value names contained in the key to their content in raw form as a type and data pair.

reg_value HKEY ?SUBKEYPATH? VALUENAME

Returns the cooked data value for a registry value. If SUBKEYPATH is not specified, the returned data is from the value VALUENAME under HKEY which is a handle to a registry key. If SUBKEYPATH is specified, it must be a registry path under HKEY and VALUENAME is retrieved from that key.

reg_value_delete HKEY ?SUBKEYPATH? VALUENAME

If the optional SUBKEYPATH argument is not specified, the command deletes the specified registry value under the key specified by the handle HKEY. If SUBKEYPATH is specified, it should be a key path under HKEY. In this case the value is deleted from that key.

reg_value_names HKEY ?SUBKEYPATH?

Returns the list of names of values under the key specified by the handle HKEY or if SUBKEYPATH is specified and non-empty, the value names under that subkey.

reg_value_raw HKEY ?SUBKEYPATH? VALUENAME

Returns a pair consisting of the type and data for a registry value. If SUBKEYPATH is not specified, the returned data is from the value VALUENAME under HKEY which is a handle to a registry key. If SUBKEYPATH is specified, it must be a registry path under HKEY and VALUENAME is retrieved from that key.

reg_value_set HKEY ?SUBKEYPATH? VALUENAME TYPE DATA

Stores the data DATA as a registry value of type TYPE. If SUBKEYPATH is not specified, the data is stored as VALUENAME under HKEY which is a handle to a registry key. If SUBKEYPATH is specified, it must be a registry path under HKEY and the data is stored in VALUENAME under that key.

reg_values HKEY ?SUBKEYPATH?

Returns a dictionary keyed by the value names in the specified registry key HKEY or under its subkey SUBKEYPATH if specified and non-empty. The value data is in cooked form.

reg_values_raw HKEY ?SUBKEYPATH?

Returns a dictionary keyed by the value names in the specified registry key HKEY or under its subkey SUBKEYPATH if specified and non-empty. The value data is in raw form as a pair containing the data type and data value.

reg_walk HKEY ?-subkey SUBKEYPATH? ?-callback CMDPREFIX? ?-cbdata CBDATA?

The command iterates over all keys in the tree rooted at HKEY. If the -subkey option is specified, it must be a path to a subkey under HKEY and the tree walk begins at that key.

The -callback option specifies a callback to be invoked for each key in the tree. If unspecified, the callback defaults to printing the relative path of the current key to standard output.

The -cbdata option specifies any context data to be passed to the first invocation of the callback and defaults to the empty string.

The callback is invoked with three arguments. The first argument is the value returned on the previous invocation of the callback or the value of the -cbdata option for the first invocation. The second argument is the handle to the current key. The third argument is the path to the current key relative to the root as a Tcl list. The callback must not close the passed handle or store it for later use.

The iteration will normally terminate when there are no untraversed keys in the tree. The callback can change this behavior by returning a non-0 return code (not result!) as below.

return	This is a normal return. The iteration will continue with the next key.
return -code continue VALUE	The iteration will skip over the key's children and continue with its siblings.
return -code break VALUE	The iteration will skip over the key's siblings as well as children and continue with siblings of key's parent.
return -code return VALUE	The iteration will stop without error even though more keys may remain.
error MESSAGE	The iteration terminates with the same error exception that was thrown.

The command returns the result of the last callback invocation as the result of the command.

Registry

SYNOPSIS

DESCRIPTION

Predefined keys

Registry data types

Registry commands

COPYRIGHT

TWAPI 5.0 Documentation