Windows API Reference - Registry Functions

Home > Registry

Registry Functions

These functions provide access to the Windows Registry, a hierarchical database that stores configuration settings and options for the operating system and applications.

Accessing and Manipulating Registry Keys and Values

RegOpenKeyEx
Opens an existing registry key.
RegCreateKeyEx
Creates a new registry key or opens an existing one.
RegCloseKey
Closes an open registry key.
RegDeleteKeyEx
Deletes a registry key and its subkeys (if on a 64-bit system, it can delete the 32-bit or 64-bit view).
RegEnumKeyEx
Enumerates the subkeys of a registry key.
RegSetValueEx
Sets the data and type of a specified registry value.
RegQueryValueEx
Retrieves the type and data for the specified registry value.
RegDeleteValue
Deletes a registry value.

Registry Value Types

Registry values can store data in various formats. Common types include:

REG_SZ: A null-terminated string.
REG_EXPAND_SZ: A null-terminated string that contains unexpanded references to environment variables.
REG_DWORD: A 32-bit unsigned integer.
REG_QWORD: A 64-bit unsigned integer.
REG_BINARY: Binary data in any form.
REG_MULTI_SZ: An array of null-terminated strings, terminated by a single null character.

`RegOpenKeyEx`

Opens an existing registry key.

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

Parameters

Parameter	Description
`hKey`	A handle to an open registry key. This handle is obtained by calling `RegCreateKeyEx` or `RegOpenKeyEx`, or it can be one of the predefined keys.
`lpSubKey`	The name of the registry subkey to be opened.
`ulOptions`	Reserved; must be zero.
`samDesired`	A mask that specifies the access rights for the key. This parameter can be one of the following values: `KEY_QUERY_VALUE` `KEY_SET_VALUE` `KEY_CREATE_SUB_KEY` `KEY_ENUMERATE_SUB_KEYS` `KEY_NOTIFY` `KEY_CREATE_LINK` `KEY_WOW64_64KEY` `KEY_WOW64_32KEY`
`phkResult`	A pointer to a variable that receives a handle to the opened registry key.

Return Value
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a non-zero error code defined in Winerror.h.

`RegCreateKeyEx`

Creates a new registry key or opens an existing one.

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

Parameters

Parameter	Description
`hKey`	A handle to an open registry key.
`lpSubKey`	The name of the registry subkey to be created or opened.
`Reserved`	Reserved; must be zero.
`lpClass`	The user-defined class type of the key being created. This parameter can be NULL.
`dwOptions`	Flags that specify various attribute options for the key. This parameter can be `REG_OPTION_VOLATILE` or `REG_OPTION_NON_VOLATILE`.
`samDesired`	A mask that specifies the access rights for the key to be opened or created. See `RegOpenKeyEx` for possible values.
`lpSecurityAttributes`	A pointer to a `SECURITY_ATTRIBUTES` structure that specifies the security descriptors for the new key.
`phkResult`	A pointer to a variable that receives a handle to the created or opened key.
`lpDisposition`	A pointer to a variable that receives one of the following values: `REG_CREATED_NEW_KEY` `REG_OPENED_EXISTING_KEY`

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

`RegCloseKey`

Closes an open registry key.

LONG RegCloseKey(
      HKEY        hKey
    );

Parameters

Parameter	Description
`hKey`	A handle to the registry key to be closed. This handle must have been obtained by calling `RegCreateKeyEx` or `RegOpenKeyEx`.

Return Value
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a non-zero error code.

`RegDeleteKeyEx`

Deletes a registry key and its subkeys.

LONG RegDeleteKeyEx(
      HKEY        hKey,
      LPCSTR      lpSubKey,
      REGSAM      samDesired,
      DWORD       Reserved
    );

Parameters

Parameter	Description
`hKey`	A handle to an open registry key. The access mask associated with this handle must include `DELETE`.
`lpSubKey`	The name of the subkey to be deleted.
`samDesired`	A mask that specifies the access rights for the key. Use `KEY_WOW64_64KEY` to delete the 64-bit view of the subkey, or `KEY_WOW64_32KEY` to delete the 32-bit view.
`Reserved`	Reserved; must be zero.

Return Value
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a non-zero error code.

`RegEnumKeyEx`

Enumerates the subkeys of a registry key.

LONG RegEnumKeyEx(
      HKEY        hKey,
      DWORD       dwIndex,
      LPSTR       lpName,
      LPDWORD     lpcchName,
      LPWORD      lpReserved,
      LPSTR       lpClass,
      LPDWORD     lpcchClass,
      PFILETIME   lpftLastWriteTime
    );

Parameters

Parameter	Description
`hKey`	A handle to an open registry key.
`dwIndex`	The index of the subkey to retrieve. This parameter is used to iterate through the subkeys.
`lpName`	A pointer to a buffer that receives the name of the subkey.
`lpcchName`	On input, the size in characters of the buffer pointed to by `lpName`. On output, the number of characters copied to the buffer, not including the terminating null character.
`lpReserved`	Reserved; must be NULL.
`lpClass`	A pointer to a buffer that receives the class of the subkey. Can be NULL.
`lpcchClass`	On input, the size in characters of the buffer pointed to by `lpClass`. On output, the number of characters copied to the buffer.
`lpftLastWriteTime`	A pointer to a `FILETIME` structure that receives the last write time of the subkey.

Return Value
If the function succeeds, the return value is ERROR_SUCCESS. If there are no more subkeys to be enumerated, the return value is ERROR_NO_MORE_ITEMS.

`RegSetValueEx`

Sets the data and type of a specified registry value.

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

Parameters

Parameter	Description
`hKey`	A handle to an open registry key.
`lpValueName`	The name of the registry value to be set. If a value with this name does not exist, the function creates it.
`Reserved`	Reserved; must be zero.
`dwType`	The data type of the value. See "Registry Value Types" for common types.
`lpData`	A pointer to the buffer that contains the data to be stored in the given value.
`cbData`	The size, in bytes, of the data pointed to by the `lpData` parameter.

Return Value
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a non-zero error code.

`RegQueryValueEx`

Retrieves the type and data for the specified registry value.

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

Parameters

Parameter	Description
`hKey`	A handle to an open registry key.
`lpValueName`	The name of the registry value to query.
`lpReserved`	Reserved; must be NULL.
`lpType`	A pointer to a variable that receives the type of the data.
`lpData`	A pointer to a buffer that receives the data. If this parameter is NULL, the function returns the size of the data buffer in `pcbData`.
`pcbData`	On input, the size in bytes of the buffer pointed to by `lpData`. On output, the number of bytes copied to the buffer.

Return Value
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a non-zero error code.

`RegDeleteValue`

Deletes a registry value.

LONG RegDeleteValue(
      HKEY        hKey,
      LPCSTR      lpValueName
    );

Parameters

Parameter	Description
`hKey`	A handle to an open registry key. The access mask associated with `hKey` must include `DELETE`.
`lpValueName`	The name of the registry value to be deleted.

Return Value
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a non-zero error code.