Windows Registry Functions (Win32 API)

The Windows Registry is a hierarchical database that stores configuration settings and options for the operating system, hardware, and applications. The Win32 API provides a set of powerful functions to programmatically access, modify, and manage registry entries. Understanding these functions is crucial for system administration, application deployment, and low-level system development.

Key Registry Concepts

Core Registry Functions

RegOpenKeyEx

Opens an existing registry key or creates a new one. This is typically the first step before performing any operations on a key.

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

Parameters:

  • hKey: Handle to an open key (e.g., HKEY_CURRENT_USER).
  • lpSubKey: Path to the subkey to open.
  • ulOptions: Reserved; must be zero.
  • samDesired: Access mask specifying desired access rights (e.g., KEY_READ, KEY_WRITE).
  • phkResult: Pointer to receive the handle of the opened key.

Return Value: ERROR_SUCCESS on success, or a non-zero error code otherwise.

Open Key Handle Access Rights

RegCreateKeyEx

Creates a new registry key or opens an existing one. If the key already exists, the function opens it and returns its handle.

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

Parameters:

  • hKey: Handle to an open key.
  • lpSubKey: Path to the subkey to create or open.
  • Reserved: Reserved; must be zero.
  • dwOptions: Specifies options for the key (e.g., REG_OPTION_VOLATILE).
  • samDesired: Access mask specifying desired access rights.
  • phkResult: Pointer to receive the handle of the created or opened key.
  • lpDisposition: Pointer to a variable that receives one of the following values: REG_CREATED_NEW_KEY or REG_OPENED_EXISTING_KEY.

Return Value: ERROR_SUCCESS on success.

Create Key Open Existing Disposition

RegQueryValueEx

Retrieves the data and type of a specified value under an open registry key.

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

Parameters:

  • hKey: Handle to an open key.
  • lpValueName: Name of the 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.
  • lpType: Pointer to a variable that receives the type of the value.
  • lpData: Pointer to a buffer that receives the value's data.
  • lpcbData: Pointer to a variable that specifies the size of the buffer pointed to by lpData, in bytes.

Return Value: ERROR_SUCCESS on success.

Read Value Query Data Value Type

RegSetValueEx

Sets the data and attributes of a specified registry value. If the value does not exist, it is created.

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

Parameters:

  • hKey: Handle to an open key.
  • lpValueName: Name of the value to set.
  • dwType: Type of data to be stored in the value.
  • lpData: Pointer to the buffer containing the data to be stored.
  • cbData: Size of the data in the buffer pointed to by lpData, in bytes.

Return Value: ERROR_SUCCESS on success.

Write Value Set Data Create Value

RegDeleteKey

Deletes a subkey and its subkeys from the registry. This function can only delete keys that have no open handles.

LONG RegDeleteKey(
    HKEY hKey,
    LPCSTR lpSubKey
);

Parameters:

  • hKey: Handle to an open key.
  • lpSubKey: Name of the subkey to delete.

Return Value: ERROR_SUCCESS on success.

Delete Key Remove Subkey

RegCloseKey

Closes the specified registry key and flushes any changes to disk.

LONG RegCloseKey(
    HKEY hKey
);

Parameters:

  • hKey: Handle to an open key that is to be closed.

Return Value: ERROR_SUCCESS on success.

Close Handle Release Resources

Example Scenario: Modifying a User Preference

Let's say you want to store a user's favorite color preference in the registry. The following pseudocode illustrates how you might do this using the Win32 API:

// Assume hKey is a handle to HKEY_CURRENT_USER obtained via RegOpenKeyEx or similar
            HKEY hKey;
            LONG result = RegOpenKeyEx(HKEY_CURRENT_USER, L"Software\\MyApp\\Settings", 0, KEY_WRITE, &hKey);

            if (result == ERROR_SUCCESS) {
                const WCHAR* favoriteColor = L"Blue";
                result = RegSetValueEx(
                    hKey,
                    L"FavoriteColor",       // Value name
                    0,                      // Reserved
                    REG_SZ,                 // Value type (String)
                    (const BYTE*)favoriteColor, // Data
                    (wcslen(favoriteColor) + 1) * sizeof(WCHAR) // Size in bytes
                );

                if (result == ERROR_SUCCESS) {
                    // Successfully set the registry value
                }

                RegCloseKey(hKey); // Always close the key handle
            }
User Settings Application Configuration REG_SZ

Important Considerations