Windows Registry API Reference

This section provides information about the Windows Registry API, a set of functions that allow applications to access and manipulate the Windows registry. The 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 to store configuration settings.

Overview

The Windows Registry API enables developers to programmatically interact with the registry, performing operations such as:

  • Creating, opening, and closing registry keys.
  • Reading and writing registry values.
  • Deleting keys and values.
  • Enumerating subkeys and values.
  • Managing security and access control for registry keys.

Understanding the registry structure and the available API functions is crucial for developing robust and well-configured Windows applications.

Note: Incorrect manipulation of registry values can lead to system instability or application malfunction. Always exercise caution when modifying the registry and consider backing up critical keys before making changes.

Core Registry Functions

The following are some of the most commonly used functions in the Windows Registry API:

RegCreateKeyEx

Creates a specified registry key. If the key already exists, the function opens it and returns its handle. Otherwise, it creates the key.

Syntax:

LSTATUS RegCreateKeyEx(
    HKEY hKey,
    LPCTSTR lpSubKey,
    DWORD Reserved,
    LPCTSTR lpClass,
    DWORD dwOptions,
    REGSAM samDesired,
    LPSECURITY_ATTRIBUTES lpSecurityAttributes,
    PHKEY phkResult,
    LPDWORD lpDisposition
);

Parameters:

Name Type Description
hKey HKEY Handle to an open registry key.
lpSubKey LPCTSTR Name of the subkey to be created or opened.
Reserved DWORD This parameter is reserved and must be zero.
lpClass LPCTSTR Specifies the class of the key. Can be NULL.
dwOptions DWORD Options for the key. Can be REG_OPTION_VOLATILE or REG_OPTION_NON_VOLATILE.
samDesired REGSAM Access mask that specifies the desired security access to the key.
lpSecurityAttributes LPSECURITY_ATTRIBUTES Pointer to a SECURITY_ATTRIBUTES structure.
phkResult PHKEY Pointer to a variable that receives the handle to the opened or created key.
lpDisposition LPDWORD Pointer to a variable that receives one of the following values: REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY.

Return Value: If the function succeeds, the return value is ERROR_SUCCESS. Otherwise, the return value is a system-defined error code.

RegSetValueEx

Sets the data and type of a specified registry value. If the value doesn't exist, the function creates it.

Syntax:

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

Parameters:

Name Type Description
hKey HKEY Handle to an open registry key.
lpValueName LPCTSTR Name of the value to set. Can be NULL for the default value.
Reserved DWORD This parameter is reserved and must be zero.
dwType DWORD Type of data. See registry data types.
lpData const BYTE* Pointer to the buffer that contains 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 ERROR_SUCCESS. Otherwise, the return value is a system-defined error code.

RegQueryValueEx

Retrieves the type and data for the specified registry value name.

Syntax:

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

Parameters:

Name Type Description
hKey HKEY Handle to an open registry key.
lpValueName LPCTSTR Name of the value to query. Can be NULL for the default value.
lpReserved LPDWORD This parameter is reserved and must be NULL.
lpType LPDWORD Pointer to a variable that receives the type of the value.
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 ERROR_SUCCESS. Otherwise, the return value is a system-defined error code.

RegCloseKey

Closes the specified handle to an open registry key. The handle must be closed when it is no longer needed.

Syntax:

LSTATUS RegCloseKey(
    HKEY hKey
);

Parameters:

Name Type Description
hKey HKEY Handle to an open registry key.

Return Value: If the function succeeds, the return value is ERROR_SUCCESS. Otherwise, the return value is a system-defined error code.

Registry Data Types

Registry values can store data in various formats. The following are common data types:

  • REG_SZ: A null-terminated Unicode string.
  • REG_EXPAND_SZ: A null-terminated string that contains unexpanded references to environment variables (e.g., "%SystemRoot%").
  • REG_BINARY: Binary data in any format.
  • REG_DWORD: A 32-bit unsigned integer.
  • REG_MULTI_SZ: An array of null-terminated strings, terminated by two null characters.
  • REG_QWORD: A 64-bit unsigned integer.
Tip: Use the appropriate data type when setting or getting registry values to ensure compatibility and correct interpretation of the data.

Key Registry Constants

Key constants used with the Registry API include:

  • Predefined Keys:
    • HKEY_CLASSES_ROOT
    • HKEY_CURRENT_USER
    • HKEY_LOCAL_MACHINE
    • HKEY_USERS
    • HKEY_CURRENT_CONFIG
    • HKEY_DYN_DATA (deprecated)
  • Disposition Values (for RegCreateKeyEx):
    • REG_CREATED_NEW_KEY
    • REG_OPENED_EXISTING_KEY
  • Key Options (for RegCreateKeyEx):
    • REG_OPTION_VOLATILE: The key and its subkeys are volatile. They are not saved when the system exits.
    • REG_OPTION_NON_VOLATILE: The key and its subkeys are persistent. They are saved when the system exits.

Important Structures

Key structures used with the Registry API include:

  • SECURITY_ATTRIBUTES: Defines the security attributes of an object.