Registry Functions

The Windows Registry is a hierarchical database that stores low-level settings for the Microsoft Windows operating system and for applications that opt to use the registry. This section provides reference documentation for the API functions used to access and manipulate the registry.

Key Functions for Registry Operations

  • RegOpenKeyEx: Opens an existing registry key.
  • RegCreateKeyEx: Creates a new registry key or opens an existing one.
  • RegCloseKey: Closes an open handle to a registry key.
  • RegQueryValueEx: Retrieves the data and type of a specified registry value.
  • RegSetValueEx: Sets the data and extended types of a specified registry value.
  • RegDeleteKey: Deletes a subkey and its entries from the registry.
  • RegEnumKeyEx: Enumerates the subkeys of the specified registry key.
  • RegEnumValue: Enumerates the values of a specified registry key.

Registry Structure

The registry is organized into a tree-like structure. The top-level keys are called hives, and under these are subkeys and values. Each value has a name, a type, and data.

Working with Registry Keys

Before accessing any registry key, you must open a handle to it. You can use RegOpenKeyEx to open an existing key or RegCreateKeyEx to create a new one or open an existing one. Always close the key handle using RegCloseKey when you are finished to release system resources.

Opening a Registry Key: RegOpenKeyEx

This function opens an existing registry key. If the key does not exist, the function fails.


LSTATUS RegOpenKeyEx(
  HKEY                        hKey,
  LPCSTR                      lpSubKey,
  DWORD                       ulOptions,
  REGSAM                      samDesired,
  PHKEY                       phkResult
);

Parameters:

Name Type Description
hKey HKEY A handle to an open registry key. Typically, one of the predefined keys like HKEY_CURRENT_USER.
lpSubKey LPCSTR The name of the subkey to open.
ulOptions DWORD This parameter is reserved and must be zero.
samDesired REGSAM A bitmask that specifies the desired access rights to the key. Common values include KEY_READ and KEY_WRITE.
phkResult PHKEY A pointer to a variable that receives the handle to the opened key.

Return Value:

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in Winerror.h.

Important: Always check the return value of registry functions to ensure operations were successful.

Working with Registry Values

Once a key is open, you can read or write values associated with it. RegQueryValueEx retrieves the data and type of a specified value, while RegSetValueEx sets the data and type of a specified value.

Querying a Registry Value: RegQueryValueEx


LSTATUS RegQueryValueEx(
  HKEY     hKey,
  LPCSTR   lpValueName,
  LPDWORD  lpReserved,
  LPDWORD  lpType,
  LPBYTE   lpData,
  LPDWORD  lpcbData
);

Parameters:

Name Type Description
hKey HKEY A handle to an open registry key.
lpValueName LPCSTR The name of the registry value to query. If this parameter is NULL or an empty string, the function retrieves the type and data of the key's default value.
lpReserved LPDWORD This parameter is reserved and must be NULL.
lpType LPDWORD A pointer to a variable that receives the type of the value. Can be NULL.
lpData LPBYTE A pointer to a buffer that receives the value's data. Can be NULL.
lpcbData LPDWORD A pointer to a variable that specifies the size, in bytes, of the buffer pointed to by lpData. When the function returns, this variable contains the actual size of the data copied to lpData.

Setting a Registry Value: RegSetValueEx


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

Parameters:

Name Type Description
hKey HKEY A handle to an open registry key.
lpValueName LPCSTR The name of the registry value to set. If NULL, the value is the default value for the key.
Reserved DWORD This parameter is reserved and must be zero.
dwType DWORD The type of data to store in the value. Common types include REG_SZ, REG_DWORD, REG_BINARY.
lpData const BYTE * A pointer to the buffer containing the data to be stored.
cbData DWORD The size, in bytes, of the data pointed to by lpData.

Related Topics