Package that implements winreg for MSYS and Cygwin. More...

Classes
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
	winerror_to_string (winerror)
	Convert a windows integer error code into a descriptive string.
	check_LRESULT (return_code)
	Test LRESULT for an error code and raise exception on error condition.
	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)
	Deletes the specified key.
	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.
	convert_to_windows_path (path_name)
	Convert a MSYS/Cygwin path to windows if needed.
	convert_from_windows_path (path_name)
	Convert an absolute Windows path to Cygwin/MSYS2.
	get_file_info (path_name, string_name)
	Extract information from a windows exe file version resource.

Variables
	kernel32
	Loaded instance of the Windows dll kernel32.
	advapi32
	Loaded instance of the Windows dll advapi32.
	version
	Loaded instance of the Windows dll version.
	long = int
	Type long for Python 2 compatibility.
	FormatMessageW = cdll.kernel32.FormatMessageW
	WINBASEAPI DWORD WINAPI FormatMessageW(DWORD,LPCVOID,DWORD,DWORD,LPWSTR, DWORD, va_list*)
	restype
	Returns DWORD.
	argtypes
	Argument list for FormatMessageW()
	GetLastError = cdll.kernel32.GetLastError
	WINBASEAPI DWORD WINAPI GetLastError(void);.
	LocalFree = cdll.kernel32.LocalFree
	WINBASEAPI HLOCAL WINAPI LocalFree(HLOCAL);.
	ExpandEnvironmentStringsW = cdll.kernel32.ExpandEnvironmentStringsW
	WINBASEAPI DWORD WINAPI ExpandEnvironmentStringsW(LPCWSTR lpSrc, LPWSTR lpDst, DWORD nSize);.
	RegCloseKey = cdll.advapi32.RegCloseKey
	WINADVAPI LONG WINAPI RegCloseKey(HKEY);.
	RegConnectRegistryW = cdll.advapi32.RegConnectRegistryW
	WINADVAPI LONG WINAPI RegConnectRegistryW(LPCWSTR,HKEY,PHKEY);.
	RegCreateKeyW = cdll.advapi32.RegCreateKeyW
	WINADVAPI LONG WINAPI RegCreateKeyW(HKEY,LPCWSTR,PHKEY);.
	RegCreateKeyExW = cdll.advapi32.RegCreateKeyExW
	WINADVAPI LONG WINAPI RegCreateKeyW(HKEY,LPCWSTR,DWORD, LPWSTR, DWORD, REGSAM, LPCVOID, PHKEY, LPDWORD);.
	RegDeleteKeyW = cdll.advapi32.RegDeleteKeyW
	WINADVAPI LONG WINAPI RegDeleteKeyW(HKEY,LPCWSTR);.
	RegDeleteKeyExW = cdll.advapi32.RegDeleteKeyExW
	WINADVAPI LONG WINAPI RegDeleteKeyW(HKEY,LPCWSTR,REGSAM,DWORD);.
	RegDeleteValueW = cdll.advapi32.RegDeleteValueW
	WINADVAPI LONG WINAPI RegDeleteValueW(HKEY,LPCWSTR);.
	RegEnumKeyExW = cdll.advapi32.RegEnumKeyExW
	WINADVAPI LONG WINAPI RegEnumKeyExW(HKEY,DWORD,LPWSTR,PDWORD,PDWORD, LPWSTR,PDWORD,PFILETIME);.
	RegQueryInfoKeyW = cdll.advapi32.RegQueryInfoKeyW
	WINADVAPI LONG WINAPI RegQueryInfoKeyW(HKEY,LPWSTR,PDWORD,PDWORD,PDWORD, PDWORD,PDWORD,PDWORD,PDWORD,PDWORD, PDWORD,PFILETIME);.
	RegEnumValueW = cdll.advapi32.RegEnumValueW
	WINADVAPI LONG WINAPI RegEnumValueW(HKEY,DWORD,LPWSTR,PDWORD,PDWORD,PDWORD, LPBYTE,PDWORD);.
	RegFlushKey = cdll.advapi32.RegFlushKey
	WINADVAPI LONG WINAPI RegFlushKey(HKEY);.
	RegLoadKeyW = cdll.advapi32.RegLoadKeyW
	WINADVAPI LONG WINAPI RegLoadKeyW(HKEY,LPCWSTR,LPCWSTR)
	RegOpenKeyExW = cdll.advapi32.RegOpenKeyExW
	WINADVAPI LONG WINAPI RegOpenKeyExW(HKEY,LPCWSTR,DWORD,REGSAM,PHKEY)
	RegQueryReflectionKey = cdll.advapi32.RegQueryReflectionKey
	WINADVAPI LONG RegQueryReflectionKey(HKEY, LPDWORD)
	RegDisableReflectionKey = cdll.advapi32.RegDisableReflectionKey
	WINADVAPI LONG RegDisbleReflectionKey(HKEY)
	RegEnableReflectionKey = cdll.advapi32.RegEnableReflectionKey
	WINADVAPI LONG RegEnableReflectionKey(HKEY)
	RegQueryValueW = cdll.advapi32.RegQueryValueW
	WINADVAPI LONG WINAPI RegQueryValueW(HKEY,LPCWSTR,LPWSTR,PLONG);.
	RegQueryValueExW = cdll.advapi32.RegQueryValueExW
	WINADVAPI LONG WINAPI RegQueryValueExW(HKEY,LPCWSTR,LPDWORD,LPDWORD,LPBYTE, LPDWORD);.
	RegSaveKeyW = cdll.advapi32.RegSaveKeyW
	WINADVAPI LONG WINAPI RegSaveKeyW(HKEY,LPCWSTR,LPSECURITY_ATTRIBUTES);.
	RegSetValueW = cdll.advapi32.RegSetValueW
	WINADVAPI LONG WINAPI RegSetValueW(HKEY,LPCWSTR,DWORD,LPCWSTR,DWORD);.
	RegSetValueExW = cdll.advapi32.RegSetValueExW
	WINADVAPI LONG WINAPI RegSetValueExW(HKEY,LPCWSTR,DWORD,DWORD,const BYTE*, DWORD);.
	GetFileVersionInfoSizeW = cdll.version.GetFileVersionInfoSizeW
	WINADVAPI DWORD WINAPI GetFileVersionInfoSizeW(LPCWSTR, LPDWORD);.
	GetFileVersionInfoW = cdll.version.GetFileVersionInfoW
	WINADVAPI BOOL WINAPI GetFileVersionInfoW(LPCWSTR, DWORD, DWORD, LPVOID);.
	VerQueryValueW = cdll.version.VerQueryValueW
	WINADVAPI BOOL WINAPI VerQueryValueW(LPCVOID, LPCWSTR, LPVOID, PUINT);.

Properties
	PROPERTY_HACK = property
	Hack to allow Sphinx to not crash.

Detailed Description

Package that implements winreg for MSYS and Cygwin.

Function Documentation

◆ check_LRESULT()

wslwinreg.cygwinapi.check_LRESULT ( return_code )

Test LRESULT for an error code and raise exception on error condition.

If the input value is zero, return the value. If the input is a non-zero code, raise a WindowsError() exception unless it's ERROR_FILE_NOT_FOUND. In the latter case, raise a FileNotFoundError.

Parameters

return_code Windows integer error code.

Returns: Error code, usually zero.

Exception: WindowsError or FileNotFoundError

◆ CloseKey()

wslwinreg.cygwinapi.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.cygwinapi.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.cygwinapi.convert_from_windows_path ( path_name )

Convert an absolute Windows path to Cygwin/MSYS2.

If the path is already Cygwin/MSYS2 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.cygwinapi.convert_to_windows_path ( path_name )

Convert a MSYS/Cygwin 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

◆ CreateKey()

wslwinreg.cygwinapi.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.cygwinapi.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.cygwinapi.DeleteKey	(		key,
			sub_key )

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 one of the predefined HKEY_* constants.
sub_key	Is 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.

Exception: WindowsError

◆ DeleteKeyEx()

wslwinreg.cygwinapi.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.cygwinapi.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.cygwinapi.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.cygwinapi.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.cygwinapi.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.cygwinapi.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.cygwinapi.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

◆ FlushKey()

wslwinreg.cygwinapi.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_file_info()

wslwinreg.cygwinapi.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

◆ LoadKey()

wslwinreg.cygwinapi.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.cygwinapi.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.cygwinapi.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.cygwinapi.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.cygwinapi.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.cygwinapi.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.cygwinapi.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

◆ SaveKey()

wslwinreg.cygwinapi.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.cygwinapi.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.cygwinapi.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

◆ winerror_to_string()

wslwinreg.cygwinapi.winerror_to_string ( winerror )

Convert a windows integer error code into a descriptive string.

Call FormatMessageW() in Windows to perform the actual work.

Parameters

winerror Integer error code from Windows

Returns: String describing the error.

Classes

Functions

Variables

Properties

Detailed Description

Function Documentation

◆ check_LRESULT()

◆ CloseKey()

◆ ConnectRegistry()

◆ convert_from_windows_path()

◆ convert_to_windows_path()

◆ CreateKey()

◆ CreateKeyEx()

◆ DeleteKey()

◆ DeleteKeyEx()

◆ DeleteValue()

◆ DisableReflectionKey()

◆ EnableReflectionKey()

◆ EnumKey()

◆ EnumValue()

◆ ExpandEnvironmentStrings()

◆ FlushKey()

◆ get_file_info()

◆ LoadKey()

◆ OpenKey()

◆ OpenKeyEx()

◆ QueryInfoKey()

◆ QueryReflectionKey()

◆ QueryValue()

◆ QueryValueEx()

◆ SaveKey()

◆ SetValue()

◆ SetValueEx()

◆ winerror_to_string()