Package that implements winreg for Windows Subsystem for Linux. More...

Classes
class	Commands
	Commands to send to the bridging executable. More...
class	FileNotFoundError
	pypy2 does not define this exception More...
class	PyHKEY
	A Python object representing a win32 registry key. More...
class	WindowsError
	This exception doesn't exist in Cygwin/MSYS, provide it. More...

Functions
	test_string (input_string)
	Raise an exception if the input is not None or a string.
	convert_to_windows_path (path_name)
	Convert a WSL path to windows if needed.
	convert_from_windows_path (path_name)
	Convert an absolute Windows path to WSL.
	find_windows_boot_drive ()
	Using the PATH, determine the boot drive.
	get_windows_user ()
	Determine the name of the user logged into Windows.
	get_exe_path ()
	Determine where the bridge exe resides.
	handleLRESULT ()
	Receive the LRESULT from the bridge.
	create_string_buffer (temp_string, is_binary=False)
	Convert a string into a utf-8 byte stream.
	recv_string (convert_to_string=True)
	Recieve a string from the socket.
	_RegCloseKey (hkey)
	Low level function to call RegCloseKey.
	CloseKey (hkey)
	Closes a previously opened registry key.
	ConnectRegistry (computer_name, key)
	Establishes a connection to a predefined registry handle.
	CreateKey (key, sub_key)
	Creates or opens the specified key.
	CreateKeyEx (key, sub_key, reserved=0, access=KEY_WRITE)
	Creates or opens the specified key.
	DeleteKey (key, sub_key)
	Not implemented.
	DeleteKeyEx (key, sub_key, access=KEY_WOW64_64KEY, reserved=0)
	Deletes the specified key.
	DeleteValue (key, value)
	Removes a named value from a registry key.
	EnumKey (key, index)
	Enumerates subkeys of an open registry key, returning a string.
	EnumValue (key, index)
	Enumerates values of an open registry key, returning a tuple.
	ExpandEnvironmentStrings (str)
	Expands environment variables.
	FlushKey (key)
	Writes all the attributes of a key to the registry.
	LoadKey (key, sub_key, file_name)
	Creates a subkey under the specified key.
	OpenKey (key, sub_key, reserved=0, access=KEY_READ)
	Opens the specified key, returning a handle object.
	OpenKeyEx (key, sub_key, reserved=0, access=KEY_READ)
	Opens the specified key, returning a handle object.
	QueryInfoKey (key)
	Returns information about a key, as a tuple.
	QueryValue (key, sub_key)
	Retrieves the unnamed value for a key, as a string.
	QueryValueEx (key, value_name)
	Retrieves the type and data for a specified value name.
	SaveKey (key, file_name)
	Saves the specified key, and all its subkeys to the specified file.
	SetValue (key, sub_key, type, value)
	Associates a value with a specified key.
	SetValueEx (key, value_name, reserved, type, value)
	Stores data in the value field of an open registry key.
	DisableReflectionKey (key)
	Disables registry reflection.
	EnableReflectionKey (key)
	Restores registry reflection for the specified disabled key.
	QueryReflectionKey (key)
	Determines the reflection state for the specified key.
	get_file_info (path_name, string_name)
	Extract information from a windows exe file version resource.

Variables
	long = int
	Type long for Python 2 compatibility.
	basestring = str
	Type basestring for Python 2 compatibility.
str	_LOCALHOST
	Loopback address.
int	_BUFFER_SIZE
	Transmission buffer size.
	_WIN_DIR
	Directory for the windows executables.
	_EXESUFFIX
	Set the exe suffix for the CPU in use.
	_WIN_EXE
	Patch to the executable to bridge.
	_LISTEN_SOCKET
	Socket used for listening for the exe.
	_LISTEN_PORT
	Semi-random port assigned to the socket by the operating system.
	_EXEC_FP
	Popen object for the bridge executable.
	_CONNECTION_SOCKET
	Connection socket.
	_CONNECTION_ADDR
	Connection socket.

Detailed Description

Package that implements winreg for Windows Subsystem for Linux.

Function Documentation

◆ CloseKey()

wslwinreg.wslapi.CloseKey ( hkey )

Closes a previously opened registry key.

The hkey argument specifies a previously opened key.

Parameters

hkey	PyHKEY object or None.

Note: If hkey is not closed using this method (or via hkey.Close()), it is closed when the hkey object is destroyed by Python.

◆ ConnectRegistry()

wslwinreg.wslapi.ConnectRegistry	(		computer_name,
			key )

Establishes a connection to a predefined registry handle.

Establishes a connection to a predefined registry handle on another computer, and returns a handle object.

Parameters

computer_name	Is the name of the remote computer, of the form r"\\computername". If None, the local computer is used.
key	Is the predefined handle to connect to.

Returns: PyHKEY object

Exception: WindowsError or FileNotFileError

◆ convert_from_windows_path()

wslwinreg.wslapi.convert_from_windows_path ( path_name )

Convert an absolute Windows path to WSL.

If the path is already Linux format, it will be returned unchanged.

Parameters

path_name Absolute Windows pathname

Return: Pathname converted to Linux.

See also: convert_to_windows_path

◆ convert_to_windows_path()

wslwinreg.wslapi.convert_to_windows_path ( path_name )

Convert a WSL path to windows if needed.

If the path is already Windows format, it will be returned unchanged.

Parameters

path_name Windows or Linux pathname

Return: Pathname converted to Windows.

See also: convert_from_windows_path

◆ create_string_buffer()

wslwinreg.wslapi.create_string_buffer	(		temp_string,
			is_binary = False )

Convert a string into a utf-8 byte stream.

Parameters

temp_string	String to convert
is_binary	True if the input in binary, not a string.

◆ CreateKey()

wslwinreg.wslapi.CreateKey	(		key,
			sub_key )

Creates or opens the specified key.

If key is one of the predefined keys, sub_key may be 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.

Parameters

key	Is an already open key, or one of the predefined HKEY_* constants.
sub_key	Is a string that names the key this method opens or creates.

Returns: Handle of the opened key.

Exception: WindowsError or FileNotFileError

◆ CreateKeyEx()

wslwinreg.wslapi.CreateKeyEx	(	key,
		sub_key,
		reserved = 0,
		access = KEY_WRITE )

Creates or opens the specified key.

If key is one of the predefined keys, sub_key may be 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.

Parameters

key	Is an already open key, or one of the predefined HKEY_* constants
sub_key	Is a string that names the key this method opens or creates.
reserved	Is a reserved integer, and must be zero. The default is zero.
access	Os an integer that specifies an access mask that describes the desired security access for the key. Default is common.KEY_WRITE.

Returns: Handle of the opened key.

Exception: WindowsError or FileNotFileError

◆ DeleteKey()

wslwinreg.wslapi.DeleteKey	(		key,
			sub_key )

Not implemented.

Exception: NotImplementedError is always thrown.

◆ DeleteKeyEx()

wslwinreg.wslapi.DeleteKeyEx	(	key,
		sub_key,
		access = KEY_WOW64_64KEY,
		reserved = 0 )

Deletes the specified key.

If the method succeeds, the entire key, including all of its values, is removed.

Note: This method can not delete keys with subkeys.

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.
sub_key	Os a string that must be a subkey of the key identified by the key parameter. This value must not be None, and the key may not have subkeys.
access	Is an integer that specifies an access mask that describes the desired security access for the key. Default is common.KEY_WOW64_64KEY.
reserved	Is a reserved integer, and must be zero. The default is zero.

Exception: WindowsError

◆ DeleteValue()

wslwinreg.wslapi.DeleteValue	(		key,
			value )

Removes a named value from a registry key.

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.
value	Is a string that identifies the value to remove.

Exception: WindowsError or FileNotFileError

◆ DisableReflectionKey()

wslwinreg.wslapi.DisableReflectionKey ( key )

Disables registry reflection.

Disables registry reflection for 32-bit processes running on a 64-bit operating system.

If the key is not on the reflection list, the function succeeds but has no effect. Disabling reflection for a key does not affect reflection of any subkeys.

Parameters

key	Is an already open key, or one of the predefined HKEY_* constants.

Exception: WindowsError

◆ EnableReflectionKey()

wslwinreg.wslapi.EnableReflectionKey ( key )

Restores registry reflection for the specified disabled key.

Restoring reflection for a key does not affect reflection of any subkeys.

Parameters

key	Is an already open key, or one of the predefined HKEY_* constants.

Exception: WindowsError

◆ EnumKey()

wslwinreg.wslapi.EnumKey	(		key,
			index )

Enumerates subkeys of an open registry key, returning a string.

The function retrieves the name of one subkey each time it is called. It is typically called repeatedly until an OSError exception is raised, indicating no more values are available.

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.
index	Is an integer that identifies the index of the key to retrieve.

Exception: WindowsError or FileNotFileError

◆ EnumValue()

wslwinreg.wslapi.EnumValue	(		key,
			index )

Enumerates values of an open registry key, returning a tuple.

The function retrieves the name of one subkey each time it is called. It is typically called repeatedly, until an OSError exception is raised, indicating no more values.

Index	Meaning
0	A string that identifies the value.
1	An object that holds the value data, and whose type depends on the underlying registry type
2	An integer that identifies the type of the value data

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.
index	Is an integer that identifies the index of the value to retrieve.

Returns: A tuple of 3 items.

Exception: WindowsError or FileNotFileError

◆ ExpandEnvironmentStrings()

wslwinreg.wslapi.ExpandEnvironmentStrings ( str )

Expands environment variables.

Expands environment variable placeholders NAME% in strings like REG_EXPAND_SZ.

Parameters

str	String to expand.

Returns: Expanded string

Exception: WindowsError

◆ find_windows_boot_drive()

wslwinreg.wslapi.find_windows_boot_drive ( )

Using the PATH, determine the boot drive.

This function intentionally doesn't use the registry since it's used to determine where the bridge exe file should be located.

Returns: String of the boot drive path

◆ FlushKey()

wslwinreg.wslapi.FlushKey ( key )

Writes all the attributes of a key to the registry.

It is not necessary to call FlushKey() 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 CloseKey(), the FlushKey() method returns only when all the data has been written to the registry. An application should only call FlushKey() if it requires absolute certainty that registry changes are on disk.

Note: If you don’t know whether a FlushKey() call is required, it probably isn’t.

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.

Exception: WindowsError

◆ get_exe_path()

wslwinreg.wslapi.get_exe_path ( )

Determine where the bridge exe resides.

Check if the exe is installed, and if not, install it.

This is done because launching an EXE file from the Linux file system is slow. This corrects the issue

Returns: Pathname of the bridge exe

◆ get_file_info()

wslwinreg.wslapi.get_file_info	(		path_name,
			string_name )

Extract information from a windows exe file version resource.

Given a windows exe file, extract the "StringFileInfo" resource and parse out the data chunk named by string_name.

Full list of resource names: https://docs.microsoft.com/en-us/windows/desktop/menurc/stringfileinfo-block

Examples

file_version = get_file_info("devenv.exe", "FileVersion")

product_version = get_file_info("devenv.exe", "ProductVersion")

Parameters

path_name	Name of the windows file.
string_name	Name of the data chunk to retrieve

Return: None if no record found or an error, or a valid string

◆ get_windows_user()

wslwinreg.wslapi.get_windows_user ( )

Determine the name of the user logged into Windows.

Don't use the registry

Returns: Logged in user name

◆ LoadKey()

wslwinreg.wslapi.LoadKey	(	key,
		sub_key,
		file_name )

Creates a subkey under the specified key.

Creates a subkey under the specified key and stores registration information from a specified file into that subkey.

This file must have been created with the 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 SE_RESTORE_PRIVILEGE privilege.

If key is a handle returned by ConnectRegistry(), then the path specified in fileName is relative to the remote computer.

Parameters

key	Is a handle returned by ConnectRegistry() or one of the constants common.HKEY_USERS or common.HKEY_LOCAL_MACHINE.
sub_key	Is a string that identifies the sub_key to load
file_name	Is the name of the file to load registry data from.

Exception: WindowsError or FileNotFileError

◆ OpenKey()

wslwinreg.wslapi.OpenKey	(	key,
		sub_key,
		reserved = 0,
		access = KEY_READ )

Opens the specified key, returning a handle object.

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.
sub_key	Is a string that identifies the sub_key to open
reserved	Is a reserved integer, and must be zero. Default is zero.
access	Is an integer that specifies an access mask that describes the desired security access for the key. Default is KEY_READ.

Returns: A new handle to the specified key.

Exception: WindowsError or FileNotFileError

◆ OpenKeyEx()

wslwinreg.wslapi.OpenKeyEx	(	key,
		sub_key,
		reserved = 0,
		access = KEY_READ )

Opens the specified key, returning a handle object.

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.
sub_key	Is a string that identifies the sub_key to open
reserved	Is a reserved integer, and must be zero. Default is zero.
access	Is an integer that specifies an access mask that describes the desired security access for the key. Default is KEY_READ.

Returns: A new handle to the specified key.

Exception: WindowsError or FileNotFileError

◆ QueryInfoKey()

wslwinreg.wslapi.QueryInfoKey ( key )

Returns information about a key, as a tuple.

Index	Meaning
0	An integer giving the number of sub keys this key has.
1	An integer giving the number of values this key has.
2	An integer giving when the key was last modified (if available) as 100’s of nanoseconds since Jan 1, 1601.

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.

Returns: A tuple of 3 items.

Exception: WindowsError or FileNotFileError

◆ QueryReflectionKey()

wslwinreg.wslapi.QueryReflectionKey ( key )

Determines the reflection state for the specified key.

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.

Returns: True if reflection is disabled.

◆ QueryValue()

wslwinreg.wslapi.QueryValue	(		key,
			sub_key )

Retrieves the unnamed value for a key, as a string.

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, so always use QueryValueEx() if possible.

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.
sub_key	Is a string that holds the name of the subkey with which the value is associated. If this parameter is None or empty, the function retrieves the value set by the SetValue() method for the key identified by key.

Exception: WindowsError or FileNotFileError

◆ QueryValueEx()

wslwinreg.wslapi.QueryValueEx	(		key,
			value_name )

Retrieves the type and data for a specified value name.

Retrieves the type and data for a specified value name associated with an open registry key.

Index	Meaning
0	The value of the registry item.
1	An integer giving the registry type for this value.

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.
value_name	Is a string indicating the value to query.

Returns: A tuple of 2 items.

Exception: WindowsError or FileNotFileError

◆ recv_string()

wslwinreg.wslapi.recv_string ( convert_to_string = True )

Recieve a string from the socket.

Returns: UTF-8 string.

◆ SaveKey()

wslwinreg.wslapi.SaveKey	(		key,
			file_name )

Saves the specified key, and all its subkeys to the specified file.

If key represents a key on a remote computer, the path described by file_name is relative to the remote computer. The caller of this method must possess the SeBackupPrivilege security privilege.

This function passes NULL for security_attributes to the API.

Note: Privileges are different than permissions.

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.
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 LoadKey() method.

Exception: WindowsError or FileNotFileError

◆ SetValue()

wslwinreg.wslapi.SetValue	(	key,
		sub_key,
		type,
		value )

Associates a value with a specified key.

If the key specified by the 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 key parameter must have been opened with common.KEY_SET_VALUE access.

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.
sub_key	Is a string that names the subkey with which the value is associated.
type	is an integer that specifies the type of the data. Currently this must be REG_SZ, meaning only strings are supported. Use the SetValueEx() function for support for other data types.
value	Is a string that specifies the new value.

Exception: TypeError, WindowsError or FileNotFileError

◆ SetValueEx()

wslwinreg.wslapi.SetValueEx	(	key,
		value_name,
		reserved,
		type,
		value )

Stores data in the value field of an open registry key.

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 KEY_SET_VALUE access.

To open the key, use the CreateKeyEx() or OpenKeyEx() 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.

Parameters

key	Is an already open key, or any one of the predefined HKEY_* constants.
value_name	Is a string that names the subkey with which the value is associated.
reserved	can be anything – zero is always passed to the API.
type	Is an integer that specifies the type of the data.
value	Is a string that specifies the new value.

Exception: WindowsError or FileNotFileError

◆ test_string()

wslwinreg.wslapi.test_string ( input_string )

Raise an exception if the input is not None or a string.

Parameters

input_string String to test.

Exception: TypeError

Variable Documentation

◆ _CONNECTION_ADDR

wslwinreg.wslapi._CONNECTION_ADDR

protected

Connection socket.

Connection address.

Classes

Functions

Variables

Detailed Description

Function Documentation

◆ CloseKey()

◆ ConnectRegistry()

◆ convert_from_windows_path()

◆ convert_to_windows_path()

◆ create_string_buffer()

◆ CreateKey()

◆ CreateKeyEx()

◆ DeleteKey()

◆ DeleteKeyEx()

◆ DeleteValue()

◆ DisableReflectionKey()

◆ EnableReflectionKey()

◆ EnumKey()

◆ EnumValue()

◆ ExpandEnvironmentStrings()

◆ find_windows_boot_drive()

◆ FlushKey()

◆ get_exe_path()

◆ get_file_info()

◆ get_windows_user()

◆ LoadKey()

◆ OpenKey()

◆ OpenKeyEx()

◆ QueryInfoKey()

◆ QueryReflectionKey()

◆ QueryValue()

◆ QueryValueEx()

◆ recv_string()

◆ SaveKey()

◆ SetValue()

◆ SetValueEx()

◆ test_string()

Variable Documentation

◆ _CONNECTION_ADDR