Registry Functions
This section details the functions used to interact with the Windows Registry, a hierarchical database used for storing configuration settings and options for the operating system and applications.
Core Registry Functions
RegCreateKeyEx
Creates or opens a specified registry key. If the key already exists, the function opens it. Otherwise, it creates the key. The function returns a handle to the opened or created key.
Syntax
LONG RegCreateKeyEx(
HKEY hKey,
LPCTSTR lpSubKey,
DWORD Reserved,
LPTSTR lpClass,
DWORD dwOptions,
REGSAM samDesired,
LPSECURITY_ATTRIBUTES lpSecurityAttributes,
PHKEY phkResult,
LPDWORD lpdwDisposition
);
Parameters
- hKey: A handle to an open registry key.
- lpSubKey: The name of the registry subkey to be opened or created.
- Reserved: Reserved; must be zero.
- lpClass: Pointer to a buffer that receives the class of the key.
- dwOptions: Flags that specify the type of handle to be created.
- samDesired: The access rights to the key.
- lpSecurityAttributes: Security attributes.
- phkResult: Pointer to a variable that receives the handle to the opened or created key.
- lpdwDisposition: Pointer to a variable that receives a value indicating whether the key was created or opened.
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.
RegOpenKeyEx
Opens an existing registry key and returns a handle to it. This function does not allow the creation of new keys.
Syntax
LONG RegOpenKeyEx(
HKEY hKey,
LPCTSTR lpSubKey,
DWORD ulOptions,
REGSAM samDesired,
PHKEY phkResult
);
Parameters
- hKey: A handle to an open registry key.
- lpSubKey: The name of the registry subkey to be opened.
- ulOptions: Flags that specify options for the handle.
- samDesired: The 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. Otherwise, it is a system error code.
RegCloseKey
Closes a handle to an open registry key. It is essential to close keys when you are finished with them to free up system resources.
Syntax
LONG RegCloseKey(
HKEY hKey
);
Parameters
- hKey: A handle to the open registry key to be closed.
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.
RegQueryValueEx
Retrieves the data and type for the specified registry value. This function allows reading of registry entries.
Syntax
LONG RegQueryValueEx(
HKEY hKey,
LPCTSTR lpValueName,
LPDWORD lpReserved,
LPDWORD lpType,
LPBYTE lpData,
LPDWORD lpcbData
);
Parameters
- hKey: A handle to an open registry key.
- lpValueName: The name of the registry value.
- lpReserved: Reserved; must be NULL.
- lpType: Pointer to a variable that receives the type identifier for the value.
- lpData: Pointer to a buffer that receives the value's data.
- lpcbData: 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, it is a system error code.
RegSetValueEx
Copies a piece of data from a buffer into the specified registry value. If the value does not exist, the function creates it.
Syntax
LONG RegSetValueEx(
HKEY hKey,
LPCTSTR lpValueName,
DWORD Reserved,
DWORD dwType,
const BYTE *lpData,
DWORD cbData
);
Parameters
- hKey: A handle to an open registry key.
- lpValueName: The name of the registry value.
- Reserved: Reserved; must be zero.
- dwType: The data type of the data to be stored.
- lpData: The data to be stored.
- cbData: The size, in bytes, of the data pointed to by lpData.
Return Value
If the function succeeds, the return value is ERROR_SUCCESS. Otherwise, it is a system error code.
RegDeleteKey
Deletes a subkey and all its descendants from the registry. This function is irreversible.
Syntax
LONG RegDeleteKey(
HKEY hKey,
LPCTSTR lpSubKey
);
Parameters
- hKey: A handle to an open registry key.
- lpSubKey: The name of the subkey to be deleted.
Return Value
If the function succeeds, the return value is ERROR_SUCCESS. Otherwise, it is a system error code.
RegEnumKeyEx
Enumerates the subkeys of the specified open registry key. This function is used to iterate through the keys within a given registry node.
Syntax
LONG RegEnumKeyEx(
HKEY hKey,
DWORD dwIndex,
LPTSTR lpName,
LPDWORD lpcchName,
LPDWORD lpReserved,
LPTSTR lpClass,
LPDWORD lpcchClass,
PFILETIME lpftLastWriteTime
);
Parameters
- hKey: A handle to an open registry key.
- dwIndex: The index of the subkey to be retrieved.
- lpName: Pointer to a buffer that receives the name of the subkey.
- lpcchName: Pointer to a variable that specifies the size, in characters, of the buffer pointed to by lpName.
- lpReserved: Reserved; must be zero.
- lpClass: Pointer to a buffer that receives the class of the subkey.
- lpcchClass: Pointer to a variable that specifies the size, in characters, of the buffer pointed to by lpClass.
- lpftLastWriteTime: Pointer to a variable that receives the date and time that the subkey was last written to.
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. Otherwise, it is a system error code.
RegEnumValueEx
Enumerates the values of the specified open registry key. This function is used to iterate through the values associated with a registry key.
Syntax
LONG RegEnumValueEx(
HKEY hKey,
DWORD dwIndex,
LPTSTR lpValueName,
LPDWORD lpcchValueName,
LPDWORD lpReserved,
LPDWORD lpType,
LPBYTE lpData,
LPDWORD lpcbData
);
Parameters
- hKey: A handle to an open registry key.
- dwIndex: The index of the value to be retrieved.
- lpValueName: Pointer to a buffer that receives the name of the value.
- lpcchValueName: Pointer to a variable that specifies the size, in characters, of the buffer pointed to by lpValueName.
- lpReserved: Reserved; must be NULL.
- lpType: Pointer to a variable that receives the type identifier for the value.
- lpData: Pointer to a buffer that receives the value's data.
- lpcbData: 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. If there are no more values to be enumerated, the return value is ERROR_NO_MORE_ITEMS. Otherwise, it is a system error code.