Registry Functions (Win32 API)

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 covers the Win32 API functions used to interact with the registry.

Key Registry Functions

RegOpenKeyEx

Opens an existing key in the registry. If the key does not exist, the function returns an error.

  • Syntax: LONG RegOpenKeyEx(HKEY hKey, LPCTSTR lpSubKey, DWORD ulOptions, REGSAM samDesired, PHKEY phkResult);
  • Parameters:
    • hKey: A handle to an open key.
    • lpSubKey: The name of the subkey to open.
    • ulOptions: Reserved; must be zero.
    • samDesired: Access mask that specifies the desired access rights to the key.
    • phkResult: 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.

    HKEY hKey;
    LONG lRes = RegOpenKeyEx(HKEY_CURRENT_USER, "Software\\MyApp", 0, KEY_READ, &hKey);
    if (lRes == ERROR_SUCCESS) {
        // Key opened successfully
        RegCloseKey(hKey);
    }

RegCreateKeyEx

Creates the specified key under the specified handle. If the key already exists, the function opens it.

  • Syntax: LONG RegCreateKeyEx(HKEY hKey, LPCTSTR lpSubKey, DWORD Reserved, LPTSTR lpClass, DWORD dwOptions, REGSAM samDesired, LPSECURITY_ATTRIBUTES lpSecurityAttributes, PHKEY phkResult, LPDWORD lpDisposition);
  • Parameters:
    • hKey: Handle to an open key.
    • lpSubKey: Name of the subkey to create.
    • Reserved: Reserved; must be zero.
    • lpClass: Specifies the class of the key.
    • dwOptions: Flags that control the key's state.
    • samDesired: Access mask for the key.
    • lpSecurityAttributes: Security attributes.
    • phkResult: Pointer to the key's handle.
    • lpDisposition: Receives information about whether the subkey was created or opened.
  • Return Value: ERROR_SUCCESS on success, nonzero error code on failure.

    HKEY hKey;
    DWORD dwDisposition;
    LONG lRes = RegCreateKeyEx(HKEY_CURRENT_USER, "Software\\MyApp", 0, NULL, REG_OPTION_NON_VOLATILE, KEY_WRITE, NULL, &hKey, &dwDisposition);
    if (lRes == ERROR_SUCCESS) {
        // Key created or opened
        RegCloseKey(hKey);
    }

RegQueryValueEx

Retrieves the data and type for the specified value name associated with an open key in the registry.

  • Syntax: LONG RegQueryValueEx(HKEY hKey, LPCTSTR lpValueName, LPDWORD lpReserved, LPDWORD lpType, LPBYTE lpData, LPDWORD lpcbData);
  • Parameters:
    • hKey: Handle to an open key.
    • lpValueName: Name of the value to query.
    • lpReserved: Reserved; must be NULL.
    • lpType: Pointer to a variable that receives the type code.
    • 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.
  • Return Value: ERROR_SUCCESS on success, nonzero error code on failure.

    HKEY hKey;
    DWORD dwType = REG_SZ;
    DWORD dwSize = 256;
    CHAR szBuffer[256];
    if (RegOpenKeyEx(HKEY_CURRENT_USER, "Software\\MyApp", 0, KEY_READ, &hKey) == ERROR_SUCCESS) {
        if (RegQueryValueEx(hKey, "SettingName", NULL, &dwType, (LPBYTE)szBuffer, &dwSize) == ERROR_SUCCESS) {
            // szBuffer now contains the value
        }
        RegCloseKey(hKey);
    }

RegSetValueEx

Creates or replaces a subkey's value in the registry. If the value does not exist, it is created.

  • Syntax: LONG RegSetValueEx(HKEY hKey, LPCTSTR lpValueName, DWORD Reserved, DWORD dwType, const BYTE* lpData, DWORD cbData);
  • Parameters:
    • hKey: Handle to an open key.
    • lpValueName: Name of the value to set.
    • Reserved: Reserved; must be zero.
    • dwType: Type of data.
    • lpData: Data to be stored.
    • cbData: Size of the data.
  • Return Value: ERROR_SUCCESS on success, nonzero error code on failure.

    HKEY hKey;
    const char* szValue = "Example Value";
    if (RegCreateKeyEx(HKEY_CURRENT_USER, "Software\\MyApp", 0, NULL, REG_OPTION_NON_VOLATILE, KEY_WRITE, NULL, &hKey, NULL) == ERROR_SUCCESS) {
        RegSetValueEx(hKey, "MySetting", 0, REG_SZ, (const BYTE*)szValue, strlen(szValue) + 1);
        RegCloseKey(hKey);
    }

RegCloseKey

Closes a handle to an open key in the registry. Closing a key handle releases the handle and all its child keys.

  • Syntax: LONG RegCloseKey(HKEY hKey);
  • Parameters:
    • hKey: Handle to the key to be closed.
  • Return Value: ERROR_SUCCESS on success, nonzero error code on failure.

    HKEY hKey;
    // ... open a key ...
    RegCloseKey(hKey);

RegDeleteKey

Deletes a subkey and its entries from the registry. The key to be deleted cannot have subkeys.

  • Syntax: LONG RegDeleteKey(HKEY hKey, LPCTSTR lpSubKey);
  • Parameters:
    • hKey: Handle to an open key that identifies the root of the subkey tree.
    • lpSubKey: Name of the subkey to delete.
  • Return Value: ERROR_SUCCESS on success, nonzero error code on failure.

    HKEY hKey;
    if (RegOpenKeyEx(HKEY_CURRENT_USER, "Software", 0, KEY_ALL_ACCESS, &hKey) == ERROR_SUCCESS) {
        RegDeleteKey(hKey, "MyApp"); // Deletes the "MyApp" subkey
        RegCloseKey(hKey);
    }

RegEnumKeyEx

Enumerate the subkeys of the specified open key.

  • Syntax: LONG RegEnumKeyEx(HKEY hKey, DWORD dwIndex, LPTSTR lpName, LPDWORD lpcchName, LPDWORD lpReserved, LPTSTR lpClass, LPDWORD lpcchClass, PFILETIME lpftLastWriteTime);
  • Parameters:
    • hKey: Handle to an open key.
    • dwIndex: Index of the subkey to retrieve.
    • lpName: Buffer to receive the subkey name.
    • lpcchName: Size of the buffer.
    • lpReserved: Reserved; must be NULL.
    • lpClass: Buffer for class name.
    • lpcchClass: Size of the class buffer.
    • lpftLastWriteTime: Pointer to receive the last modified time.
  • Return Value: ERROR_SUCCESS on success. ERROR_NO_MORE_ITEMS if no more subkeys exist. Nonzero error code on failure.

    HKEY hKey;
    DWORD dwIndex = 0;
    TCHAR subKeyName[256];
    DWORD bufSize = sizeof(subKeyName) / sizeof(TCHAR);

    if (RegOpenKeyEx(HKEY_LOCAL_MACHINE, "Software", 0, KEY_READ, &hKey) == ERROR_SUCCESS) {
        while (RegEnumKeyEx(hKey, dwIndex, subKeyName, &bufSize, NULL, NULL, NULL, NULL) == ERROR_SUCCESS) {
            // Process subKeyName
            dwIndex++;
            bufSize = sizeof(subKeyName) / sizeof(TCHAR); // Reset buffer size for next iteration
        }
        RegCloseKey(hKey);
    }

RegEnumValue

Enumerate the values of an open key in the registry.

  • Syntax: LONG RegEnumValue(HKEY hKey, DWORD dwIndex, LPTSTR lpValueName, LPDWORD lpcchValueName, LPDWORD lpReserved, LPDWORD lpType, LPBYTE lpData, LPDWORD lpcbData);
  • Parameters:
    • hKey: Handle to an open key.
    • dwIndex: Index of the value to retrieve.
    • lpValueName: Buffer to receive the value name.
    • lpcchValueName: Size of the value name buffer.
    • lpReserved: Reserved; must be NULL.
    • lpType: Pointer to receive the value's type.
    • lpData: Buffer to receive the value's data.
    • lpcbData: Size of the data buffer.
  • Return Value: ERROR_SUCCESS on success. ERROR_NO_MORE_ITEMS if no more values exist. Nonzero error code on failure.

    HKEY hKey;
    DWORD dwIndex = 0;
    TCHAR valueName[256];
    DWORD valueNameSize = sizeof(valueName) / sizeof(TCHAR);
    DWORD type, dataSize;
    BYTE data[256];

    if (RegOpenKeyEx(HKEY_CURRENT_USER, "Software\\MyApp", 0, KEY_READ, &hKey) == ERROR_SUCCESS) {
        while (RegEnumValue(hKey, dwIndex, valueName, &valueNameSize, NULL, &type, data, &dataSize) == ERROR_SUCCESS) {
            // Process valueName, type, and data
            dwIndex++;
            valueNameSize = sizeof(valueName) / sizeof(TCHAR); // Reset buffer size
            // dataSize will be updated by RegEnumValue
        }
        RegCloseKey(hKey);
    }