Opening and Creating Keys
You open a registry key with a call to this function:
LONG RegOpenKeyEx ( HKEY hKey,
LPCWSTR lpszSubKey,
DWORD ulOptions,
REGSAM samDesired,
PHKEY phkResult);
hKey :The first parameter is the key that contains the second parameter, the subkey. This first key must be either one of the root key constants or a previously opened key.
lpszSubKey:The subkey to open is specified as a text string that contains the key to open. This subkey string can contain multiple levels of subkeys as long as each subkey is separated by a backslash. For example, to open the subkey HKEY_LOCAL_MACHINE/Software/Microsoft/Pocket Word, an application could either call RegOpenKeyEx with HKEY_LOCAL_MACHINE as the key and Software/Microsoft/Pocket Word as the subkey or open the Software/Microsoft key and then make a call with that opened handle to RegOpenKeyEx, specifying the subkey Pocket Word. Key and value names aren't case specific.
ulOptions、samDesired :Windows CE ignores the ulOptions and samDesired parameters. To remain compatible with future versions of the operating system that might use security features, these parameters should be set to 0 for ulOptions and NULL for samDesired.
phkResult :The phkResult parameter should point to a variable that will receive the handle to the opened key.
The function, if successful, returns a value of ERROR_SUCCESS and an error code if it fails.
Another method for opening a key is
LONG RegCreateKeyEx (HKEY hKey,
LPCWSTR lpszSubKey,
DWORD Reserved,
LPWSTR lpszClass,
DWORD dwOptions,
REGSAM samDesired,
LPSECURITY_ATTRIBUTES lpSecurityAttributes,
PHKEY phkResult,
LPDWORD lpdwDisposition);
The difference between RegCreateKeyEx and RegOpenKeyEx, aside from the extra parameters, is that RegCreateKeyEx creates the key if it didn't exist before the call.
The first two parameters, the key handle and the subkey name, are the same as in RegOpenKeyEx.
The Reserved parameter should be set to 0.
The lpClass parameter points to a string that contains the class name of the key if it's to be created. This parameter can be set to NULL if no class name needs to be specified.
The dwOptions and samDesired and lpSecurityAttributes parameters should be set to 0, NULL, and NULL respectively.
The phkResult parameter points to the variable that receives the handle to the opened or newly created key.
The lpdwDisposition parameter points to a variable that's set to indicate whether the key was opened or created by the call.
Closing Keys
You close a registry key by calling
LONG RegCloseKey (HKEY hKey);
When a registry key is closed, Windows CE flushes any unwritten key data to the registry before returning from the call.
Reading Registry Values
You can query registry values by first opening the key containing the values of interest and calling this function:
LONG RegQueryValueEx (HKEY hKey,
LPCWSTR lpszValueName,
LPDWORD lpReserved,
LPDWORD lpType,
LPBYTE lpData,
LPDWORD lpcbData);
The hKey parameter is the handle of the key opened by RegCreateKeyEx or RegOpenKeyEx.
The lpszValueName parameter is the name of the value that's being queried.
The lpType parameter is a pointer to a variable that receives the variable type.
The lpData parameter points to the buffer to receive the data, while the lpcbData parameter points to a variable that receives the size of the data. If RegQueryValueEx is called with the lpData parameter equal to NULL, Windows returns the size of the data but doesn't return the data itself. This allows applications to first query the size and type of the data before actually receiving it.
Writing Registry Values
You set a registry value by calling
LONG RegSetValueEx (HKEY hKey,
LPCWSTR lpszValueName,
DWORD Reserved,
DWORD dwType,
const BYTE *lpData,
DWORD cbData);
the handle to the open key followed by the name of the value to set.
The function also requires that you pass the type of data, the data itself, and the size of the data. The data type parameter is simply a labeling aid for the application that eventually reads the data. Data in the registry is stored in a binary format and returned in that same format. Specifying a different type has no effect on how the data is stored in the registry or how it's returned to the application. However, given the availability of third-party registry editors, you should make every effort to specify the appropriate data type in the registry.
The data types can be one of the following:
· REG_SZ A zero-terminated Unicode string
· REG_EXPAND_SZ A zero-terminated Unicode string with embedded environment variables
· REG_MULTI_SZ A series of zero-terminated Unicode strings terminated by two zero characters
· REG_DWORD A 4-byte binary value
· REG_BINARY Free-form binary data
· REG_DWORD_BIG_ENDIAN A DWORD value stored in big-endian format
· REG_DWORD_LITTLE_ENDIAN Equivalent to REG_DWORD
· REG_LINK A Unicode symbolic link
· REG_RESOURCE_LIST A device driver resource list
Deleting Keys and Values
You delete a registry key by calling
LONG RegDeleteKey (HKEY hKey, LPCWSTR lpszSubKey);
The parameters are the handle to the open key and the name of the subkey you plan to delete. For the deletion to be successful, the key must not be currently open. You can delete a value by calling
LONG RegDeleteValue (HKEY hKey, LPCWSTR lpszValueName);
You can clean a wealth of information about a key by calling this function:
LONG RegQueryInfoKey (HKEY hKey,
LPWSTR lpszClass,
LPDWORD lpcchClass,
LPDWORD lpReserved,
LPDWORD lpcSubKeys,
LPDWORD lpcchMaxSubKeyLen,
LPDWORD lpcchMaxClassLen,
LPDWORD lpcValues,
LPDWORD lpcchMaxValueNameLen,
LPDWORD lpcbMaxValueData,
LPDWORD lpcbSecurityDescriptor,
PFILETIME lpftLastWriteTime);
The only input parameter to this function is the handle to a key. The function returns the class of the key, if any, as well as the maximum lengths of the subkeys and values under the key. The last two parameters, the security attributes and the last write time, are unsupported under Windows CE and should be set to NULL.
Enumerating Registry Keys
In some instances, you'll find it helpful to be able to query a key to see what subkeys and values it contains. You accomplish this with two different functions: one to query the subkeys, another to query the values. The first function
LONG RegEnumKeyEx ( HKEY hKey,
DWORD dwIndex,
LPWSTR lpszName,
LPDWORD lpcchName,
LPDWORD lpReserved,
LPWSTR lpszClass,
LPDWORD lpcchClass,
PFILETIME lpftLastWriteTime);
enumerates the subkeys of a registry key through repeated calls. The parameters to pass the function are the handle of the opened key and an index value. To enumerate the first subkey, the dwIndex parameter should be 0. For each subsequent call to RegEnumKeyEx, dwIndex should be incremented to get the next subkey. When there are no more subkeys to be enumerated, RegEnumKeyEx returns ERROR_NO_MORE_ITEMS.
For each call to RegEnumKeyEx, the function returns the name of the subkey and its classname. The last write time parameter isn't supported under Windows CE.
Values within a key can be enumerated with a call to this function:
LONG RegEnumValue ( HKEY hKey,
DWORD dwIndex,
LPWSTR lpszValueName,
LPDWORD lpcchValueName,
LPDWORD lpReserved,
LPDWORD lpType,
LPBYTE lpData,
LPDWORD lpcbData);
Like RegEnumKey, this function is called repeatedly, passing index values to enumerate the different values stored under the key. When the function returns ERROR_NO_MORE_ITEMS, no more values are under the key. RegEnumValue returns the name of the values and the data stored in each value, as well as its data type and the size of the data.
RegFlushKey
This function writes all the attributes of the specified open registry key into the registry.
LONG RegFlushKey( HKEY hKey );
hKey
[in] Handle to a currently open key or one of the following predefined reserved handle values:
· HKEY_CLASSES_ROOT
· HKEY_CURRENT_USER
· HKEY_LOCAL_MACHINE
· HKEY_USERS
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value is a nonzero error code. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.
When RegFlushKey is called, all previous changes to the registry are committed by flushing data to persistent storage. The implementation of this function is OEM-dependent. The RegFlushKey function may also write out parts of or all of the other keys. Calling this function excessively can have a negative effect on an application's performance.
By default, Windows CE does not support a lazy flush of the registry, though the OEM may choose to implement a lazy-flush or power-down flush. It is important that applications call RegFlushKey to save important registry information. Call RegFlushKey after a group of changes have been made, but not for every individual registry change. Frequent calling of RegFlushKey can degrade performance.
An application should only call RegFlushKey if it requires absolute certainty that registry changes are on disk. In general, RegFlushKey rarely, if ever, need be used.