Registry management functions can query and modify
key/value pairs and data and also create new subkeys and key/value
pairs. Key handles of type HKEY are used both to specify a key and to obtain new keys.
Values are typed; there are several types to select from, such as
strings, double words, and expandable strings whose parameters can be
replaced with environment variables.
Key Management
Key management functions allow you to open named keys, enumerate subkeys of an open key, and create new keys.
RegOpenKeyEx
The first function, RegOpenKeyEx,
opens a named subkey. Starting from one of the predefined reserved key
handles, you can traverse the registry and obtain a handle to any
subordinate key.
LONG RegOpenKeyEx (
HKEY hKey,
LPCTSTR lpSubKey,
DWORD ulOptions,
REGSAM samDesired,
PHKEY phkResult)
|
The parameters for this
first function are explained individually. For later functions, as the
conventions become familiar, it is sometimes sufficient to survey them
quickly.
hKey identifies a currently open key or one of the predefined reserved key handles. phkResult points to a variable of type HKEY that is to receive the handle to the newly opened key.
lpSubKey is the subkey name you want to open. The subkey name can be a path, such as Microsoft\WindowsNT\CurrentVersion. A NULL subkey name causes a new, duplicate key for hKey to be opened.
ulOptions is reserved and must be 0.
samDesired is the access mask describing the security for the new key. Access constants include KEY_ALL_ACCESS, KEY_WRITE, KEY_QUERY_VALUE, and KEY_ENUMERATE_SUBKEYS.
The return is normally ERROR_SUCCESS. Any other result indicates an error. Close an open key handle with RegCloseKey, which takes the handle as its single parameter.
RegEnumKeyEx
RegEnumKeyEx enumerates subkey names of an open registry key, much as FindFirstFile and FindNextFile enumerate directory contents. This function retrieves the key name, class string (rarely used), and time of last modification.
LONG RegEnumKeyEx (
HKEY hKey,
DWORD dwIndex,
LPTSTR lpName,
LPDWORD lpcbName,
LPDWORD lpReserved,
LPTSTR lpClass,
LPDWORD lpcbClass
PFILETIME lpftLastWriteTime)
|
dwIndex should be 0
on the first call and then should be incremented on each subsequent
call. The value name and its size, along with the class string and its
size, are returned. Note that there are two count parameters, lpcbName (the subkey name) and lpcbClass, which are used for both input and output for buffer size. This behavior is familiar from GetCurrentDirectory , and we’ll see it again with RegEnumValue. lpClass and lpcbClass are, however, rarely used and should almost always be NULL.
The function returns ERROR_SUCCESS or an error number.
RegCreateKeyEx
You can also create new keys using RegCreateKeyEx. Keys can be given security attributes in the same way as with directories and files .
LONG RegCreateKeyEx (
HKEY hKey,
LPCTSTR lpSubKey,
DWORD Reserved,
LPTSTR lpClass,
DWORD dwOptions,
REGSAM samDesired,
LPSECURITY_ATTRIBUTES lpSecurityAttributes,
PHKEY phkResult,
LPDWORD lpdwDisposition)
|
The individual parameters are as follows:
lpSubKey is the name of the new subkey under the open key indicated by the handle hKey.
lpClass is a user-defined class type for the key. Use NULL, as recommended by MSDN.
The dwOptions flag is usually 0 (or, equivalently, REG_OPTION_NON_VOLATILE, the default). Another, mutually exclusive value is REG_OPTION_VOLATILE.
Nonvolatile registry information is stored in a file and preserved when
Windows restarts. Volatile registry keys are kept in memory and will
not be restored.
samDesired is the same as for RegOpenKeyEx.
lpSecurityAttributes can be NULL or can point to a security attribute. The rights can be selected from the same values as those used with samDesired.
lpdwDisposition points to a DWORD that indicates whether the key already existed (REG_OPENED_EXISTING_KEY) or was created (REG_CREATED_NEW_KEY).
To delete a key, use RegDeleteKey. The two parameters are an open key handle and a subkey name.
Value and Data Management
These functions allow you to get and set the data corresponding to a value name.
RegEnumValue
RegEnumValue enumerates the value names and corresponding data for a specified open key. Specify an Index, originally 0,
which is incremented in subsequent calls. On return, you get the string
with the value name as well as its size. You also get the data and its
type and size.
LONG RegEnumValue (
HKEY hKey,
DWORD dwIndex,
LPTSTR lpValueName,
LPDWORD lpcbValueName,
LPDWORD lpReserved,
LPDWORD lpType,
LPBYTE lpData,
LPDWORD lpcbData)
|
The data is returned in the buffer indicated by lpData. The result size can be found from lpcbData.
The data type, pointed to by lpType, has numerous possibilities, including REG_BINARY, REG_DWORD, REG_SZ (a string), and REG_EXPAND_SZ (an expandable string with parameters replaced by environment variables). See MSDN for a list of all the data types.
Test the function’s return result to determine whether you have enumerated all the keys. The result will be ERROR_SUCCESS if you have found a valid key.
RegQueryValueEx
is similar except that you specify a value name rather than an index.
If you know the value names, you can use this function. If you do not
know the names, you can scan with RegEnumValue.
RegSetValueEx
Set the data corresponding to a named value within an open key using RegSetValueEx, supplying the key, value name, data type, and data.
LONG RegSetValueEx (
HKEY hKey,
LPCTSTR lpValueName,
DWORD Reserved,
DWORD dwType,
CONST BYTE * lpData,
CONST cbData)
|
Finally, delete named values using the function RegDeleteValue. There are just two parameters: an open registry key and the value name, just as in the first two RegSetValueEx parameters.
