Registry API Reference

This section details the core functions for interacting with the Windows Registry, a hierarchical database that stores low-level settings for the operating system and for applications that opt to use the registry.

Registry Functions Overview

The Windows Registry is organized as a tree of keys and values. Each key can contain subkeys and values. Values store data in various formats, such as strings, binary data, and DWORDs. Kernel-mode drivers and components can access the registry using the following functions:

RegOpenKeyEx

Opens an existing registry key or creates a new key. This is typically the first step before querying or modifying registry values.

NTSTATUS RegOpenKeyEx(HKEY hKey, LPCWSTR lpSubKey, DWORD ulOptions, REGSAM samDesired, PHKEY phkResult);

Parameters

Parameter	Type	Description
hKey	HKEY	Handle to an open key.
lpSubKey	LPCWSTR	Name of the subkey to open.
ulOptions	DWORD	Reserved; must be zero.
samDesired	REGSAM	Access rights to the key.
phkResult	PHKEY	Pointer to the handle of the opened key.

Return Value

If the function succeeds, the return value is STATUS_SUCCESS. Otherwise, it returns an appropriate NTSTATUS error code.

RegQueryValueEx

Retrieves the data and type for the specified registry value. This function is used to read the contents of a registry value.

NTSTATUS RegQueryValueEx(HKEY hKey, LPCWSTR lpValueName, LPDWORD lpReserved, LPDWORD lpType, LPBYTE lpData, LPDWORD lpcbData);

Parameters

Parameter	Type	Description
hKey	HKEY	Handle to the key that contains the value.
lpValueName	LPCWSTR	Name of the registry value to query.
lpReserved	LPDWORD	Reserved; must be NULL.
lpType	LPDWORD	Pointer to a variable that receives the type of the data.
lpData	LPBYTE	Pointer to a buffer that receives the value's data.
lpcbData	LPDWORD	Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by lpData.

Return Value

If the function succeeds, the return value is STATUS_SUCCESS. Otherwise, it returns an appropriate NTSTATUS error code.

RegSetValueEx

Sets the data and parameters for a specified registry value. If the value does not exist, the function creates it.

NTSTATUS RegSetValueEx(HKEY hKey, LPCWSTR lpValueName, DWORD Reserved, DWORD dwType, const BYTE* lpData, DWORD cbData);

Parameters

Parameter	Type	Description
hKey	HKEY	Handle to the key that contains the value.
lpValueName	LPCWSTR	Name of the registry value.
Reserved	DWORD	Reserved; must be zero.
dwType	DWORD	Type of data for the value.
lpData	const BYTE*	Pointer to a buffer containing the data to be stored.
cbData	DWORD	Size, in bytes, of the data pointed to by lpData.

Return Value

If the function succeeds, the return value is STATUS_SUCCESS. Otherwise, it returns an appropriate NTSTATUS error code.

RegCloseKey

Closes the specified registry key and flushes any unwritten information from the buffer to the disk. After calling this function, the handle is no longer valid.

NTSTATUS RegCloseKey(HKEY hKey);

Parameters

Parameter	Type	Description
hKey	HKEY	Handle to the key to be closed.

Return Value

If the function succeeds, the return value is STATUS_SUCCESS. Otherwise, it returns an appropriate NTSTATUS error code.