Kernel-User Base Services
This section describes the functions that allow applications to access and manipulate the Windows Registry.
Creates or opens a specified key in the registry. If the key already exists, the function opens it.
| Parameter | Type | Description |
|---|---|---|
hKey |
HKEY |
A handle to an open key. |
lpSubKey |
LPCTSTR |
The name of the subkey to open or create. |
Reserved |
DWORD |
Must be zero. |
lpClass |
LPCTSTR |
User-defined class type or NULL. |
dwOptions |
DWORD |
Flags that specify the type of key to create. |
lpSecurityAttributes |
const LPSECURITY_ATTRIBUTES |
Security attributes or NULL. |
phkResult |
PHKEY |
Receives a handle to the opened or created key. |
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.
Use RegCloseKey to close the handle obtained from this function.
Opens the specified key in the registry. Applications need to call the RegCloseKey function to close the handle to the key when they are finished with it.
| Parameter | Type | Description |
|---|---|---|
hKey |
HKEY |
A handle to an open key. |
lpSubKey |
LPCTSTR |
The name of the subkey to open. |
ulOptions |
DWORD |
This parameter is reserved and must be zero. |
samDesired |
REGSAM |
A REGSAM value that specifies the access rights for the key to be opened. |
phkResult |
PHKEY |
A pointer to a variable that receives the handle to the opened key. |
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.
The samDesired parameter can be one of the following values:
KEY_QUERY_VALUEKEY_SET_VALUEKEY_CREATE_SUB_KEYKEY_ENUMERATE_SUB_KEYSKEY_NOTIFYKEY_READ (Combination of other read access rights)KEY_WRITE (Combination of other write access rights)KEY_ALL_ACCESS (Full access)Closes a handle to an open key in the registry. Do not call RegCloseKey on a handle that was not opened by RegCreateKeyEx or RegOpenKeyEx.
| Parameter | Type | Description |
|---|---|---|
hKey |
HKEY |
A handle to the key to be closed. |
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.
Closing a key handle does not affect the key itself or any subkeys it might contain. It simply invalidates the handle.
Deletes a subkey from the registry. Note that a key must have no subkeys to be deleted. This function allows you to delete a key from a remote computer.
| Parameter | Type | Description |
|---|---|---|
hKey |
HKEY |
A handle to an open key. |
lpSubKey |
LPCTSTR |
The name of the subkey to delete. |
samDesired |
REGSAM |
Access mask that specifies the desired access rights. For deleting a key, KEY_WOW64_64KEY is often used for 64-bit access on a 32-bit system. |
Reserved |
DWORD |
This parameter is reserved and must be zero. |
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a non-zero error code.
For 64-bit versions of Windows, the samDesired parameter can be used to specify whether the key is accessed by the 32-bit or 64-bit registry view. For more information, see Registry Reflection.
Sets the data and parameters for a specified registry value. If the value does not exist, it is created.
| Parameter | Type | Description |
|---|---|---|
hKey |
HKEY |
A handle to an open key. |
lpValueName |
LPCTSTR |
The name of the value to set. |
Reserved |
DWORD |
Reserved; must be zero. |
dwType |
DWORD |
The type of data for the value. Common types include REG_SZ, REG_DWORD, REG_BINARY. |
lpData |
const BYTE* |
A pointer to the buffer that contains the data to be stored in the value. |
cbData |
DWORD |
The size, in bytes, of the data in the buffer pointed to by lpData. |
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a non-zero error code.
If the value specified by lpValueName does not exist, RegSetValueEx creates it. If the value already exists, the existing value and its data are replaced.
Retrieves the data and type for a specified registry value.
| Parameter | Type | Description |
|---|---|---|
hKey |
HKEY |
A handle to an open key. |
lpValueName |
LPCTSTR |
The name of the registry value to query. |
Reserved |
LPDWORD |
Reserved; must be NULL. |
lpType |
LPDWORD |
A pointer to a variable that receives the type of the value. |
lpData |
LPBYTE |
A pointer to a buffer that receives the value's data. |
cbData |
LPDWORD |
A pointer to a variable that specifies the size, in bytes, of the buffer pointed to by lpData. |
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a non-zero error code.
To determine the required buffer size, call RegQueryValueEx with lpData as NULL and cbData as 0. The function will return ERROR_SUCCESS and store the required buffer size in cbData.
Deletes a registry value.
| Parameter | Type | Description |
|---|---|---|
hKey |
HKEY |
A handle to an open key. |
lpValueName |
LPCTSTR |
The name of the value to delete. |
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a non-zero error code.
This function deletes a value entry from the registry. The default value of a key cannot be deleted.
Enumerates the subkeys of the specified registry key. The function retrieves the name, class, and other information about one subkey each time it is called.
| Parameter | Type | Description |
|---|---|---|
hKey |
HKEY |
A handle to an open key. |
dwIndex |
DWORD |
The index of the subkey to retrieve. |
lpName |
LPTSTR |
A pointer to a buffer that receives the name of the subkey. |
lpcchName |
LPDWORD |
A pointer to a variable that specifies the size, in characters, of the buffer pointed to by lpName. |
lpReserved |
LPDWORD |
Reserved; must be NULL. |
lpClass |
LPTSTR |
A pointer to a buffer that receives the class of the subkey. |
lpcchClass |
LPDWORD |
A pointer to a variable that specifies the size, in characters, of the buffer pointed to by lpClass. |
lpInformation |
LPVOID |
A pointer to a REG_KEY_INFORMATION structure that receives information about the key. |
lpftLastWriteTime |
LPFILETIME |
A pointer to a buffer that receives the last write time of the subkey. |
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a non-zero error code. If there are no more subkeys to be enumerated, ERROR_NO_MORE_ITEMS is returned.
Enumerates the subkeys of the specified registry key. The function retrieves the name and data of one value each time it is called.
| Parameter | Type | Description |
|---|---|---|
hKey |
HKEY |
A handle to an open key. |
dwIndex |
DWORD |
The index of the value to retrieve. |
lpValueName |
LPTSTR |
A pointer to a buffer that receives the name of the value. |
lpcchValueName |
LPDWORD |
A pointer to a variable that specifies the size, in characters, of the buffer pointed to by lpValueName. |
lpReserved |
LPDWORD |
Reserved; must be NULL. |
lpType |
LPDWORD |
A pointer to a variable that receives the type of the value. |
lpData |
LPBYTE |
A pointer to a buffer that receives the value's data. |
cbData |
LPDWORD |
A pointer to a variable that specifies the size, in bytes, of the buffer pointed to by lpData. |
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a non-zero error code. If there are no more values to be enumerated, ERROR_NO_MORE_ITEMS is returned.
Retrieves the handle to the open key and its information, including the number of subkeys and the number of values for the specified registry key.
| Parameter | Type | Description |
|---|---|---|
hKey |
HKEY |
A handle to an open key. |
lpClass |
LPTSTR |
A pointer to a buffer that receives the class of the key. |
lpcchClass |
LPDWORD |
A pointer to a variable that specifies the size, in characters, of the buffer pointed to by lpClass. |
lpReserved |
LPDWORD |
Reserved; must be NULL. |
lpcSubKeys |
LPDWORD |
A pointer to a variable that receives the number of subkeys. |
lpcchMaxSubKeyLen |
LPDWORD |
A pointer to a variable that receives the size of the largest subkey name. |
lpcchMaxClassLen |
LPDWORD |
A pointer to a variable that receives the size of the largest class name. |
lpcValues |
LPDWORD |
A pointer to a variable that receives the number of values. |
lpcchMaxValueNameLen |
LPDWORD |
A pointer to a variable that receives the size of the largest value name. |
lpcchMaxValueLen |
LPDWORD |
A pointer to a variable that receives the size of the largest value data. |
lpftLastWriteTime |
LPFILETIME |
A pointer to a buffer that receives the last write time of the key. |
lpInformation |
LPVOID |
Reserved; must be NULL. |
If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a non-zero error code.