24    Registry

The registry is a database that COM components use to store and retrieve configuration data.

The registry stores data in binary files. To manipulate registry data, an application must use the registry functions. This chapter describes the registry and the functions that applications use to access and manipulate the data stored there. The data stored in the registry varies according to the platform that is used. This chapter contains a description of registry entries that can exist on any platform.

24.1    Structure of the Registry

The registry stores data in a hierarchically structured tree. Each node in the tree is called a key. Each key can contain both subkeys and data entries called values. Sometimes, the presence of a key is all the data that an application requires; other times, an application opens a key and uses the values associated with the key. A key can have any number of values, and the values can be in any form.

Each key has a name consisting of one or more printable ANSI characters--that is, characters ranging from values 32 through 127. Key names cannot include a space, a backslash (\), or a wildcard character (* or ?). Key names beginning with a period (.) are reserved. The name of each subkey is unique with respect to the key that is immediately above it in the hierarchy. Key names are not localized into other languages, although values may be.

24.2    Registry Storage Space

Although there are few technical limits to the type and size of data an application can store in the registry, certain practical guidelines exist to promote system efficiency. An application should store configuration and initialization data in the registry, but other kinds of data should be stored elsewhere.

Generally, data consisting of more than one or two kilobytes (K) should be stored as a file and referred to by using a key in the registry rather than being stored as a value. Instead of duplicating large pieces of data in the registry, an application should save the data as a file and refer to the file. Executable binary code should never be stored in the registry.

A value entry uses much less registry space than a key. To save space, an application should group similar data together as a structure and store the structure as a value rather than storing each of the structure members as a separate key. (Storing the data in binary form allows an application to store data in one value that would otherwise be made up of several incompatible types.)

24.3    Predefined Keys

An application must open a key before it can add data to the registry. To open a key, an application must supply the handle of another key in the registry that is already open. The system defines standard handles that are always open. An application can use these predefined handles as entry points to the registry.

The system provides two predefined keys at the root of the registry: HKEY_LOCAL_MACHINE and HKEY_USERS. In addition, the system defines two subkeys: HKEY_CLASSES_ROOT (a subkey of HKEY_LOCAL_MACHINE) and HKEY_CURRENT_USER (a subkey of HKEY_USERS). These registry handles are valid for all Win32 implementations of the registry, although the use of the handles may vary from platform to platform.

Predefined keys help an application navigate in the registry and make it possible to develop tools that allow a system administrator to manipulate categories of data. Applications that add data to the registry should always work within the framework of predefined keys, so administrative tools can find and use the new data.

These predefined keys are used as entry points to the registry.

Table 24-1:  Registry Entry Points

The use of HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, and HKEY_USERS varies depending on the implementation of the registry. In addition, other predefined handles have been defined for specific Windows platforms.

24.4    Opening, Creating, and Closing Keys

Before an application can add data to the registry, it must create or open a key. To create or open a key, an application always refers to the key as a subkey of a currently open key. The four predefined keys (HKEY_LOCAL_MACHINE, HKEY_CLASSES_ROOT, HKEY_USERS, and HKEY_CURRENT_USER) are always open. An application uses the RegOpenKeyEx() function to open a key and the RegCreateKeyEx() function to create a key.

An application can use the RegCloseKey() function to close a key and write the data it contains into the registry. RegCloseKey() does not necessarily write the data to the registry before returning; it can take as much as several seconds for the cache to be flushed to the hard disk. If an application must explicitly write registry data to the hard disk, it can use the RegFlushKey() function. RegFlushKey(), however, uses many system resources and should be called only when absolutely necessary.

24.5    Writing and Deleting Registry Data

An application can use either the RegSetValue or RegSetValueEx() function to associate a value and its data with a key. RegSetValue works only with strings (values having the REG_SZ type). RegSetValueEx(), however, can write values with any type of data. Either of these functions can create a key and its value at the same time.

To delete a value from a key, an application can use the RegDeleteValue() function. To delete a key, it can use the RegDeleteKey() function. A deleted key is not removed until the last handle to it has been closed. Subkeys and values cannot be created under a deleted key.

To change a key's security information, an application can use the RegSetKeySecurity() function.

24.6    Retrieving Data from the Registry

To retrieve data from the registry, an application typically enumerates the subkeys of a key until it finds a particular one and then retrieves data from the value or values associated with it. An application can call the RegEnumKeyEx() function to enumerate the subkeys of a given key. RegEnumKeyEx() returns a subkey and its class.

To retrieve detailed data about a particular subkey, an application can call the RegQueryInfoKey() function. The RegGetKeySecurity() function retrieves a copy of the security descriptor protecting a key.

An application can use the RegEnumValue() function to enumerate the values for a given key, and the RegQueryValueEx() function to retrieve a particular value for a key. An application typically calls RegEnumValue() to determine the value names and then RegQueryValueEx() to retrieve the data for the names.

RegQueryValueEx() differ in how they treat . If an unnamed value contains an unexpanded environment variable (for example, %PATH%), RegQueryValue expands the variable into the storage buffer provided as one of its parameters. RegQueryValueEx() does not expand unexpanded references to environment variables.

24.7    Registry Files

Applications can save part of the registry in a file and then load the contents of the file back into the registry. A registry file is useful when a large amount of data is being manipulated, when many entries are being made in the registry, or when the data is transitory and must be loaded and then unloaded again. Applications that back up and restore parts of the registry are likely to use registry files.

To save a key and its subkeys and values to a registry file, an application can call the RegSaveKey() function. To write the registry file back to the registry, an application can use the RegLoadKey(), RegReplaceKey(), or RegRestoreKey() function.

RegLoadKey() loads registry data from a specified file into a specified subkey under HKEY_USERS or HKEY_LOCAL_MACHINE on the calling application's computer or on a remote computer. The function creates the specified subkey if it does not already exist. After calling this function, an application can use the RegUnLoadKey() function to restore the registry to its previous state.

RegReplaceKey() replaces a key and all its subkeys and values in the registry with the data contained in a specified file. The new data takes effect the next time the system is started.

RegRestoreKey() loads registry data from a specified file into a specified key on the calling application's computer or on a remote computer. This function replaces the subkeys and values below the specified key with the subkeys and values that follow the top-level key in the file.

24.8    The Registry API Descriptions

RegCloseKey()

NAME

RegCloseKey() - The RegCloseKey() function releases the handle of the specified key.

Synopsis

#include <winreg.h>

LONG RegCloseKey((
        HKEY hKey );

Description

The handle for a specified key should not be used after it has been closed, because it will no longer be valid. Key handles should not be left open any longer than necessary.

The RegCloseKey() function does not necessarily write information to the registry before returning; it can take as much as several seconds for the cache to be flushed to the hard disk. If an application must explicitly write registry information to the hard disk, it can use the RegFlushKey() function. RegFlushKey(), however, uses many system resources and should be called only when necessary.

Parameters

hKey

Identifies the open key to close.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is a nonzero error code defined in

WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegCreateKeyEx(), RegDeleteKey(), RegFlushKey(), RegOpenKeyEx(), RegSetValueEx()  

RegConnectRegistry()

NAME

RegConnectRegistry() - The RegConnectRegistry() function establishes a connection to a predefined registry handle on another computer.

Synopsis

#include <winreg.h>

LONG RegConnectRegistry((
        LPTSTR lpMachineName,
        HKEY hKey,
        PHKEY phkResult );

Description

When a handle returned by RegConnectRegistry() is no longer needed, it should be closed by calling RegCloseKey().

Parameters

lpMachineName

Points to a NULL-terminated string containing the name of the remote computer. The string has the following form:

\\computername

If lpMachineName is NULL, the local computer name is used.

hKey

Specifies the one of the following predefined registry handles on the remote computer:

• HKEY_LOCAL_MACHINE

• HKEY_USERS

You cannot specify the HKEY_CLASSES_ROOT or HKEY_CURRENT_USER value for this parameter.

phkResult

Points to a variable that receives a key handle identifying the predefined handle on the remote computer.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegCloseKey()  

RegCreateKeyEx()

NAME

RegCreateKeyEx() - The RegCreateKeyEx() function creates the specified key. If the key already exists in the registry, the function opens it.

Synopsis

#include <winreg.h>

LONG RegCreateKeyEx((
        HKEY hKey,
        LPCTSTR lpSubKey,
        DWORD Reserved,
        LPTSTR lpClass,
        DWORD dwOptions,
        REGSAM samDesired,
        LPSECURITY_ATTRIBUTES lpSecurityAttributes,
        PHKEY phkResult,
        LPDWORD lpdwDisposition );

Description

The key that the RegCreateKeyEx() function creates has no values. An application can use the RegSetValue or RegSetValueEx() function to set key values.

The key identified by the hKey parameter must have been opened with KEY_CREATE_SUB_KEY access. To open the key, use the RegCreateKeyEx() or RegOpenKeyEx() function.

An application cannot create a key under HKEY_USERS or HKEY_LOCAL_MACHINE.

An application can use RegCreateKeyEx() to temporarily lock a portion of the registry. When the locking process creates a new key, it receives the disposition value REG_CREATED_NEW_KEY, indicating that it ``owns'' the lock. Another process attempting to create the same key receives the disposition value REG_OPENED_EXISTING_KEY, indicating that another process already owns the lock.

Parameters

hKey

Identifies a currently open key or one of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

The key opened or created by the RegCreateKeyEx() function is a subkey of the key identified by the hKey parameter.

lpSubKey

Points to a NULL-terminated string specifying the name of a subkey that this function opens or creates. The subkey specified must be a subkey of the key identified by the hKey parameter. This subkey must not begin with the backslash character (`\'). This parameter cannot be NULL.

Reserved

Reserved; must be zero.

lpClass

Points to a NULL-terminated string that specifies the class (object type) of this key. This parameter is ignored if the key already exists.

dwOptions

Specifies special options for the key. This parameter can be one of the following values.

1.  RegCreateKeyEx dwOptions Values

samDesired

Specifies an access mask that specifies the desired security access for the new key. This parameter can be a combination of the following values:

2.  RegCreateKeyEx samDesired Values

lpSecurityAttributes

Pointer to a SECURITY_ATTRIBUTES structure that determines whether the returned handle can be inherited by child processes. If lpSecurityAttributes is NULL, the handle cannot be inherited.

Windows NT: The lpSecurityDescriptor member of the structure specifies a security descriptor for the new key. If lpSecurityAttributes is NULL, the key gets a default security descriptor.

Windows 95: The lpSecurityDescriptor member of the structure is ignored.

The SECURITY_ATTRIBUTES structure has the following form:

typedef struct _SECURITY_ATTRIBUTES { // sa 
    DWORD  nLength; 
    LPVOID lpSecurityDescriptor; 
    BOOL   bInheritHandle; 
} SECURITY_ATTRIBUTES;

For a full description of this structure, see the Microsoft Win32 Programmer's Reference, Volume 5.

phkResult

Points to a variable that receives the handle of the opened or created key.

lpdwDisposition

Points to a variable that receives one of the following disposition values:

3.  RegCreateKeyEx lpdwDisposition Values

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegCloseKey(), RegDeleteKey(), RegOpenKeyEx(), RegSaveKey(), SECURITY_ATTRIBUTES  

RegDeleteKey()

NAME

RegDeleteKey() - The RegDeleteKey() function deletes a named subkey from the specified registry key. The subkey to be deleted cannot have any subkeys.

Synopsis

#include <winreg.h>

LONG RegDeleteKey((
        HKEY hKey,
        LPCTSTR lpSubKey );

Description

Windows 95: The RegDeleteKey() function deletes a subkey and all its descendants.

Windows NT: The RegDeleteKey() function deletes the specified subkey. The subkey to be deleted must not have subkeys.

If the function succeeds, RegDeleteKey() removes the specified key from the registry. The entire key, including all of its values, is removed.

To open the key, use the RegCreateKeyEx() or RegOpenKeyEx() function.

Parameters

hKey

Identifies a currently open key or one of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

The key specified by the lpSubKey parameter must be a subkey of the key identified by hKey.

lpSubKey

Points to a NULL-terminated string specifying the name of the key to delete. This parameter cannot be NULL.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegCloseKey(), RegCreateKeyEx(), RegOpenKeyEx()  

RegDeleteValue()

NAME

RegDeleteValue() - The RegDeleteValue() function removes a named value from the specified registry key.

Synopsis

#include <winreg.h>

LONG RegDeleteValue((
        HKEY hKey,
        LPCTSTR lpValueName );

Description

The key identified by the hKey parameter must have been opened with KEY_SET_VALUE access (KEY_WRITE access includes KEY_SET_VALUE access).

Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

lpValueName

Points to a NULL-terminated string that names the value to remove. If this parameter is NULL or points to an empty string, the value set by the RegSetValue function is removed.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegSetValueEx()  

RegEnumKeyEx()

NAME

RegEnumKeyEx() - The RegEnumKeyEx() function enumerates subkeys of the specified open registry key. The function retrieves information about one subkey each time it is called. Unlike the RegEnumKey function, RegEnumKeyEx() retrieves the class name of the subkey and the time it was last modified.

Synopsis

#include <winreg.h>

LONG RegEnumKeyEx((
        HKEY hKey,
        DWORD dwIndex,
        LPTSTR lpName,
        LPDWORD lpcbName,
        LPDWORD lpReserved,
        LPTSTR lpClass,
        LPDWORD lpcbClass,
        PFILETIME lpftLastWriteTime );

Description

To enumerate subkeys, an application should initially call the RegEnumKeyEx() function with the dwIndex parameter set to zero. The application should then increment the dwIndex parameter and call RegEnumKeyEx() until there are no more subkeys (until the function returns ERROR_NO_MORE_ITEMS).

The application can also set dwIndex to the index of the last subkey on the first call to the function and decrement the index until the subkey with the index 0 is enumerated. To retrieve the index of the last subkey, use the RegQueryInfoKey() function.

While an application is using the RegEnumKeyEx() function, it should not make calls to any registration functions that might change the key being enumerated.

The key identified by hKey must have been opened with KEY_ENUMERATE_SUB_KEYS access (KEY_READ includes KEY_ENUMERATE_SUB_KEYS). Use the RegCreateKeyEx() or RegOpenKeyEx() function to open the key.

Parameters

hKey

Identifies a currently open key or one of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

The enumerated keys are subkeys of the key identified by hKey.

dwIndex

Specifies the index of the subkey to retrieve. This parameter should be zero for the first call to the RegEnumKeyEx() function and then incremented for subsequent calls. Because subkeys are not ordered, any new subkey will have an arbitrary index. This means that the function may return subkeys in any order.

lpName

Points to a buffer that receives the name of the subkey, including the terminating NULL character. The function copies only the name of the subkey, not the full key hierarchy, to the buffer.

lpcbName

Points to a variable that specifies the size, in characters, of the buffer specified by the lpName parameter. This size should include the terminating NULL character. When the function returns, the variable pointed to by lpcbName contains the number of characters stored in the buffer. The count returned does not include the terminating NULL character.

lpReserved

Reserved; must be NULL.

lpClass

Points to a buffer that contains the class of the enumerated subkey when the function returns. This parameter can be NULL if the class is not required.

lpcbClass

Points to a variable that specifies the size, in characters, of the buffer specified by the lpClass parameter. The size should include the terminating NULL character. When the function returns, lpcbClass contains the number of characters stored in the buffer. The count returned does not include the terminating NULL character. This parameter can be NULL only if lpClass is NULL.

lpftLastWriteTime

Points to a variable that receives the time the enumerated subkey was last written to.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegCreateKeyEx(), RegDeleteKey(), RegOpenKeyEx(), RegQueryInfoKey()  

RegEnumValue()

NAME

RegEnumValue() - The RegEnumValue() function enumerates the values for the specified open registry key. The function copies one indexed value name and data block for the key each time it is called.

Synopsis

#include <winreg.h>

LONG RegEnumValue((
        HKEY hKey,
        DWORD dwIndex,
        LPTSTR lpValueName,
        LPDWORD lpcbValueName,
        LPDWORD lpReserved,
        LPDWORD lpType,
        LPBYTE lpData,
        LPDWORD lpcbData );

Description

To enumerate values, an application should initially call the RegEnumValue() function with the dwIndex parameter set to zero. The application should then increment dwIndex and call the RegEnumValue() function until there are no more values (until the function returns ERROR_NO_MORE_ITEMS).

The application can also set dwIndex to the index of the last value on the first call to the function and decrement the index until the value with index 0 is enumerated. To retrieve the index of the last value, use the RegQueryInfoKey() function.

While using RegEnumValue(), an application should not call any registration functions that might change the key being queried.

The key identified by the hKey parameter must have been opened with KEY_QUERY_VALUE access. To open the key, use the RegCreateKeyEx() or RegOpenKeyEx() function.

To determine the maximum size of the name and data buffers, use the RegQueryInfoKey() function.

Parameters

hKey

Identifies a currently open key or one of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

The enumerated values are associated with the key identified by hKey.

dwIndex

Specifies the index of the value to retrieve. This parameter should be zero for the first call to the RegEnumValue() function and then be incremented for subsequent calls.

Because values are not ordered, any new value will have an arbitrary index. This means that the function may return values in any order.

lpValueName

Points to a buffer that receives the name of the value, including the terminating NULL character.

lpcbValueName

Points to a variable that specifies the size, in characters, of the buffer pointed to by the lpValueName parameter. This size should include the terminating NULL character. When the function returns, the variable pointed to by lpcbValueName contains the number of characters stored in the buffer. The count returned does not include the terminating NULL character.

lpReserved

Reserved; must be NULL.

lpType

Points to a variable that receives the type code for the value entry. The type code can be one of the following values:

1.  RegEnumValue lpType Values

The lpType parameter can be NULL if the type code is not required.

lpData

Points to a buffer that receives the data for the value entry. This parameter can be NULL if the data is not required.

lpcbData

Points to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter. When the function returns, the variable pointed to by the lpcbData parameter contains the number of bytes stored in the buffer. This parameter can be NULL, only if lpData is NULL.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegCreateKeyEx(), RegEnumKeyEx(), RegOpenKeyEx(), RegQueryInfoKey()  

RegFlushKey()

NAME

RegFlushKey() - The RegFlushKey() function writes all the attributes of the specified open key into the registry.

Synopsis

#include <winreg.h>

LONG RegFlushKey((
        HKEY hKey );

Description

It is not necessary to call RegFlushKey() to change a key. Registry changes are flushed to disk by the registry using its lazy flusher. Registry changes are also flushed to disk at system shutdown.

Unlike RegCloseKey(), the RegFlushKey() function returns only when all the data has been written to the registry.

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.

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.

Parameters

hKey

Identifies a currently open key or one of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegCloseKey(), RegDeleteKey()  

RegGetKeySecurity()

NAME

RegGetKeySecurity() - The RegGetKeySecurity() function retrieves a copy of the security descriptor protecting the specified open registry key.

Synopsis

#include <winreg.h>

LONG RegGetKeySecurity((
        HKEY hKey,
        SECURITY_INFORMATION SecurityInformation,
        PSECURITY_DESCRIPTOR pSecurityDescriptor,
        LPDWORD lpcbSecurityDescriptor );

Description

If the buffer specified by the pSecurityDescriptor parameter is too small, the function returns ERROR_INSUFFICIENT_BUFFER and the lpcbSecurityDescriptor parameter contains the number of bytes required for the requested security descriptor.

To read the security descriptor for the specified key, the calling process must have been granted READ_CONTROL access when the key was opened, or it must be the owner of the key. (READ_CONTROL access is granted by the KEY_READ, KEY_WRITE, KEY_EXECUTE, and KEY_ALL_ACCESS access rights.) In addition, the caller must have the SE_SECURITY_NAME privilege to read the system access-control list (SACL).

For more information about security, see Chapter 10.

Parameters

hKey

Identifies an open key for which to retrieve the security descriptor.

SecurityInformation

Specifies a SECURITY_INFORMATION structure that indicates the requested security information. The SECURITY_INFORMATION structure has the following form:

typedef DWORD SECURITY_INFORMATION;

For a full description of this structure, see the Microsoft Win32 Programmer's Reference, Volume 5.

pSecurityDescriptor

Points to a buffer that receives a copy of the requested security descriptor.

lpcbSecurityDescriptor

Points to a variable that specifies the size, in bytes, of the buffer pointed to by the pSecurityDescriptor parameter. When the function returns, the variable contains the number of bytes written to the buffer.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegDeleteKey(), RegOpenKeyEx(), RegSetKeySecurity(), SECURITY_INFORMATION  

RegLoadKey()

NAME

RegLoadKey() - The RegLoadKey() function creates a subkey under HKEY_USER or HKEY_LOCAL_MACHINE and stores registration information from a specified file into that subkey. This registration information is in the form of a hive. A hive is a discrete body of keys, subkeys, and values that is rooted at the top of the registry hierarchy. A hive is backed by a single file and .LOG file.

Synopsis

#include <winreg.h>

LONG RegLoadKey((
        HKEY hKey,
        LPCTSTR lpSubKey,
        LPCTSTR lpFile );

Description

If hKey is a handle returned by RegConnectRegistry(), then the path specified in lpFile is relative to the remote computer.

Parameters

hKey

Specifies the key where the subkey will be created. This can be a predefined reserved handle value, or a handle returned by a call to RegConnectRegistry(). The predefined reserved handle values are: HKEY_LOCAL_MACHINE HKEY_USERS

This function always loads information at the top of the registry hierarchy. The HKEY_CLASSES_ROOT and HKEY_CURRENT_USER handle values cannot be specified for this parameter, because they represent subsets of the HKEY_LOCAL_MACHINE and HKEY_USERS handle values, respectively.

lpSubKey

Points to a NULL-terminated string that specifies the name of the key to be created under hKey. This subkey is where the registration information from the file will be loaded.

lpFile

Points to a NULL-terminated string containing the name of a file that has registration information. This file must have been created with the RegSaveKey() function. Under the file allocation table (FAT) file system, the filename may not have an extension.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegConnectRegistry(), RegDeleteKey(), RegReplaceKey(), RegRestoreKey(), RegSaveKey(), RegUnloadKey  

RegNotifyChangeKeyValue()

NAME

RegNotifyChangeKeyValue() - The RegNotifyChangeKeyValue() function notifies the caller about changes to the attributes or contents of a specified registry key. Note that the function does not notify the caller if the specified key is deleted.

Synopsis

#include <winreg.h>

LONG RegNotifyChangeKeyValue((
        HKEY hKey,
        BOOL bWatchSubtree,
        DWORD dwNotifyFilter,
        HANDLE hEvent,
        BOOL fAsynchronous );

Description

If the key identified by the hKey parameter is closed, the event is signaled. This means that an application should not depend on the key being open after returning from a wait operation on the event.

RegNotifyChangeKeyValue() does not work with remote handles. If RegNotifyChangeKeyValue() is called with an hKey value that is a remote handle, it returns ERROR_INVALID_HANDLE.

Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

bWatchSubtree

Specifies a flag that indicates whether to report changes in the specified key and all of its subkeys or only in the specified key. If this parameter is TRUE, the function reports changes in the key and its subkeys. If the parameter is FALSE, the function reports changes only in the key.

dwNotifyFilter

Specifies a set of flags that control which changes should be reported. This parameter can be a combination of the following values:

1.  RegNotifyChangeKeyValue dwNotifyFilter Values

hEvent

Identifies an event. If the fAsynchronous parameter is TRUE, the function returns immediately and changes are reported by signaling this event. If fAsynchronous is FALSE, hEvent is ignored.

fAsynchronous

Specifies a flag that indicates how the function reports changes. If this parameter is TRUE, the function returns immediately and reports changes by signaling the specified event. When this parameter is FALSE, the function does not return until a change has occurred.

If hEvent does not specify a valid event, the fAsynchronous parameter cannot be TRUE.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegDeleteKey(), RegEnumKeyEx(), RegEnumValue(), RegQueryInfoKey(), RegQueryValueEx()  

RegOpenKeyEx()

NAME

RegOpenKeyEx() - The RegOpenKeyEx() function opens the specified key.

Synopsis

#include <winreg.h>

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

Description

Unlike the RegCreateKeyEx() function, the RegOpenKeyEx() function does not create the specified key if the key does not exist in the registry.

Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

lpSubKey

Points to a NULL-terminated string containing the name of the subkey to open. If this parameter is NULL or a pointer to an empty string, the function will open a new handle of the key identified by the hKey parameter. In this case, the function will not close the handles previously opened.

ulOptions

Reserved; must be zero.

samDesired

Specifies an access mask that describes the desired security access for the new key. This parameter can be a combination of the following values:

1.  RegOpenKeyEx samDesired Values

phkResult

Points to a variable that receives the handle of the opened key.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegCloseKey(), RegCreateKeyEx(), RegDeleteKey(),  

RegQueryInfoKey()

NAME

RegQueryInfoKey() - The RegQueryInfoKey() function retrieves information about a specified registry key.

Synopsis

#include <winreg.h>

LONG RegQueryInfoKey( (
        HKEY hKey,
        LPTSTR lpClass,
        LPDWORD lpcbClass,
        LPDWORD lpReserved,
        LPDWORD lpcSubKeys,
        LPDWORD lpcbMaxSubKeyLen,
        LPDWORD lpcbMaxClassLen,
        LPDWORD lpcValues,
        LPDWORD lpcbMaxValueNameLen,
        LPDWORD lpcbMaxValueLen,
        LPDWORD lpcbSecurityDescriptor,
        PFILETIME lpftLastWriteTime );

Description

The key identified by the hKey parameter must have been opened with KEY_QUERY_VALUE access (KEY_READ access includes KEY_QUERY_VALUE access).

Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

lpClass

Points to a buffer that receives the key's class name. This parameter can be NULL.

lpcbClass

Points to a variable that specifies the size, in characters, of the buffer pointed to by the lpClass parameter. This size should include the terminating NULL character. When the function returns, this variable contains the length of the class string stored in the buffer. The count returned does not include the terminating NULL character. If the buffer is not big enough, the function returns ERROR_MORE_DATA, and the variable contains the size of the string, in characters, without counting the NULL character.

If lpClass is NULL, lpcbClass can be NULL.

lpReserved

Reserved; must be NULL.

lpcSubKeys

Points to a variable that receives the number of subkeys contained by the specified key. This parameter can be NULL.

lpcbMaxSubKeyLen

Points to a variable that receives the length, in characters, of the key's subkey with the longest name. The count returned does not include the terminating NULL character. This parameter can be NULL.

lpcbMaxClassLen

Points to a variable that receives the length, in characters, of the longest string specifying a subkey class. The count returned does not include the terminating NULL character. This parameter can be NULL.

lpcValues

Points to a variable that receives the number of values associated with the key. This parameter can be NULL.

lpcbMaxValueNameLen

Points to a variable that receives the length, in characters, of the key's longest value name. The count returned does not include the terminating NULL character. This parameter can be NULL.

lpcbMaxValueLen

Points to a variable that receives the length, in bytes, of the longest data component among the key's values. This parameter can be NULL.

lpcbSecurityDescriptor

Points to a variable that receives the length, in bytes, of the key's security descriptor. This parameter can be NULL.

lpftLastWriteTime

Pointer to a FILETIME structure. This parameter can be NULL.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

FILETIME, RegDeleteKey(), RegEnumKeyEx(), RegEnumValue(), RegQueryValueEx()  

RegQueryMultipleValues()

NAME

RegQueryMultipleValues() - The RegQueryMultipleValues() function retrieves the type and data for a list of value names associated with an open registry key.

Synopsis

#include <winreg.h>

LONG RegQueryMultipleValues((
        HKEY hKey,
        PVALENT val_list,
        DWORD num_vals,
        LPTSTR lpValueBuf,
        LPDWORD ldwTotsize );

Description

The RegQueryMultipleValues() function allows an application to query one or more values of a static or dynamic key. If the target key is a static key, the system provides all of the values in an atomic fashion. To prevent excessive serialization, the aggregate data returned by the function can not exceed one megabyte.

If the target key is a dynamic key, its provider must provide all the values in an atomic fashion. This means the provider should fill the results buffer synchronously, providing a consistent view of all the values in the buffer while avoiding excessive serialization. The provider can provide at most one megabyte of total output data during an atomic call to this function.

RegQueryMultipleValues() is supported remotely; that is, the hKey parameter passed to the function can refer to a remote computer.

Parameters

hKey

Identifies a currently open key or any of the pre-defined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

val_list

Address of an array of VALENT structures that describe one or more value entries. On input, the ve_valuename member of each structure must contain a pointer to the name of a value to retrieve. The function fails if any of the specified values do not exist in the specified key.

If the function succeeds, each element of the array contains the information for the specified value.

num_vals

Specifies the number of elements in the val_list array.

lpValueBuf

Pointer to a buffer. If the function succeeds, the buffer receives the data for each value.

If lpValueBuf is NULL, the function returns success, and ldwTotsize returns the required size, in bytes, of the buffer.

ldwTotsize

Pointer to a value that specifies the size, in bytes, of the buffer pointed to by the lpValueBuf parameter. If the function succeeds, ldwTotsize returns the number of bytes copied to the buffer. If the function fails because the buffer is too small, ldwTotsize receives the required size, in bytes.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS.

If the function fails, the return value is one of the following error codes:

ERROR_CANTREAD

RegQueryMultipleValues() cannot instantiate or access the provider of the dynamic key.

ERROR_MORE_DATA

The buffer pointed to by lpValueBuf was too small. In this case, ldwTotsize returns the required buffer size.

ERROR_TRANSFER_TOO_LONG

The total length of the requested data (size of the val_list array + ldwTotSize) is more than the system limit of one megabyte.

See Also

VALENT  

RegQueryValueEx()

NAME

RegQueryValueEx() - The RegQueryValueEx() function retrieves the type and data for a specified value name associated with an open registry key.

Synopsis

#include <winreg.h>

LONG RegQueryValueEx((
        HKEY hKey,
        LPTSTR lpValueName,
        LPDWORD lpReserved,
        LPDWORD lpType,
        LPBYTE lpData,
        LPDWORD lpcbData );

Description

The key identified by hKey must have been opened with KEY_QUERY_VALUE access. To open the key, use the RegCreateKeyEx() or RegOpenKeyEx() function.

This function does not expand the environment-variable names in the value data when the value type is REG_EXPAND_SZ.

If the value data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, and the ANSI version of this function is used (either by explicitly calling RegQueryValueExA or by not defining UNICODE before including the WINDOWS.H file), this function converts the stored Unicode string to an ANSI string before copying it to the buffer pointed to by lpData.

Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

lpValueName

Points to a NULL-terminated string containing the name of the value to be queried.

lpReserved

Reserved; must be NULL.

lpType

Points to a variable which receives the key's value type. The value returned through this parameter will be one of the following:

1.  RegQueryValueEx lpType Values

The lpType parameter can be NULL if the type is not required.

lpData

Points to a buffer that receives the value's data. This parameter can be NULL if the data is not required.

lpcbData

Pointer to a variable that specifies the size, in bytes, of the buffer pointed to by the lpData parameter. When the function returns, this variable contains the size of the data copied to lpData.

If the data has the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type, then lpcbData will also include the size of the terminating NULL character.

The lpcbData parameter can be NULL only if lpData is NULL.

If the buffer specified by lpData parameter is not large enough to hold the data, the function returns the value ERROR_MORE_DATA, and stores the required buffer size, in bytes, into the variable pointed to by lpcbData.

If lpData is NULL, and lpcbData is non-NULL, the function returns ERROR_SUCCESS, and stores the size of the data, in bytes, in the variable pointed to by lpcbData. This lets an application determine the best way to allocate a buffer for the value's data.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegCreateKeyEx(), RegEnumKeyEx(), RegOpenKeyEx(), RegQueryInfoKey()  

RegReplaceKey()

NAME

RegReplaceKey() - The RegReplaceKey() function replaces the file backing a key and all its subkeys with another file, so that when the system is next started, the key and subkeys will have the values stored in the new file.

Synopsis

#include <winreg.h>

LONG RegReplaceKey((
        HKEY hKey,
        LPCTSTR lpSubKey,
        LPCTSTR lpNewFile,
        LPCTSTR lpOldFile );

Description

The file specified by the lpNewFile parameter remains open until the system is restarted.

If hKey is a handle returned by RegConnectRegistry(), then the paths specified in lpNewFile and lpOldFile are relative to the remote computer.

Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

lpSubKey

Points to a NULL-terminated string containing the name of a key whose subkeys and values are replaced by this function. This key must be a subkey of the key identified by the hKey parameter. This parameter can be NULL.

The selected key must be the root of a hive; that is, it must be an immediate descendent of HKEY_LOCAL_MACHINE or HKEY_USERS.

lpNewFile

Points to a NULL-terminated string containing the name of the file with registration information. This file is typically created by using the RegSaveKey() function. Under the file allocation table (FAT) file system, the filename may not have an extension.

lpOldFile

Points to a NULL-terminated string containing the name of a file that receives a backup copy of the registry information being replaced. If this file is created under the FAT file system, it should not have an extension.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegConnectRegistry(), RegDeleteKey(), RegLoadKey(), RegRestoreKey()  

RegRestoreKey()

NAME

RegRestoreKey() - The RegRestoreKey() function reads the registry information in a specified file and copies it over the specified key. This registry information may be in the form of a key and multiple levels of subkeys.

Synopsis

#include <winreg.h>

LONG RegRestoreKey((
        HKEY hKey,
        LPCTSTR lpFile,
        DWORD dwFlags );

Description

If any subkeys of the hKey parameter are open, RegRestoreKey() fails. The function also fails if the calling process does not have the SE_RESTORE_NAME privilege.

This function replaces the keys and values below the specified key with the keys and values that are subsidiary to the top-level key in the file, no matter what the name of the top-level key in the file might be. For example, hKey might identify a key A with subkeys B and C, while the lpFile parameter specifies a file containing key X with subkeys Y and Z. After a call to RegRestoreKey(), the registry would contain key A with subkeys Y and Z. The value entries of A would be replaced by the value entries of X.

The new information in the file specified by lpFile overwrites the contents of the key specified by the hKey parameter, except for the key name.

If hKey represents a key in a remote computer, the path described by lpFile is relative to the remote computer.

Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

Any information contained in this key and its descendent keys is overwritten by the information in the file pointed to by the lpFile parameter.

lpFile

Points to a NULL-terminated string containing the name of the file with registry information. This file is typically created by using the RegSaveKey() function. Under the file allocation table (FAT) file system, the filename may not have an extension.

dwFlags

Specifies a flag indicating whether the key is volatile. (A volatile key is valid only until the next time the system is started.) This parameter is optional; if no value is specified, the key is not volatile.

This parameter can be the REG_WHOLE_HIVE_VOLATILE flag set. Instead of restoring the given key, this flag causes a new, volatile (memory only) set of registry information to be created. (A hive is a large set of registry information, typically containing all of the pertinent information for part of the system. For example, HKEY_LOCAL_MACHINE\Hardware is a volatile hive.)

If REG_WHOLE_HIVE_VOLATILE is specified, the key identified by the hKey parameter must be either the HKEY_USERS or HKEY_LOCAL_MACHINE value.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegDeleteKey(), RegLoadKey(), RegReplaceKey(), RegSaveKey()  

RegSaveKey()

NAME

RegSaveKey() - The RegSaveKey() function saves the specified key and all of its subkeys and values to a new file.

Synopsis

#include <winreg.h>

LONG RegSaveKey((
        HKEY hKey,
        LPCTSTR lpFile,
        LPSECURITY_ATTRIBUTES lpSecurityAttributes );

Description

If hKey represents a key on a remote computer, the path described by lpFile is relative to the remote computer.

The RegSaveKey() function saves only nonvolatile keys. It does not save volatile keys. A key is made volatile or nonvolatile at its creation; see RegCreateKeyEx().

Parameters

hKey

Specifies a handle of the key where the save operation is to begin, or any of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

lpFile

Points to a NULL-terminated string containing the name of the file in which the specified key and subkeys are saved.

If this filename includes an extension, it cannot be used on file allocation table (FAT) file systems by the RegLoadKey(), RegReplaceKey(), or RegRestoreKey() function.

lpSecurityAttributes

This parameter is ignored.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegCreateKeyEx(), RegDeleteKey(), RegLoadKey(), RegReplaceKey(), RegRestoreKey(), SECURITY_ATTRIBUTES  

RegSetKeySecurity()

NAME

RegSetKeySecurity() - The RegSetKeySecurity() function sets the security of an open registry key.

Synopsis

#include <winreg.h>

LONG RegSetKeySecurity((
        HKEY hKey,
        SECURITY_INFORMATION SecurityInformation,
        PSECURITY_DESCRIPTOR pSecurityDescriptor );

Description

This function succeeds only if the following conditions are met:

• If the key's owner or group is being set, the caller must have WRITE_OWNER permission or have the SE_TAKE_OWNERSHIP_NAME privilege.

• If the key's discretionary access-control list (DACL) is being set, the caller must have WRITE_DAC permission or be the object's owner.

• If the key's system access-control list (SACL) is being set, the caller must have the SE_SECURITY_NAME privilege.

If hKey is one of the predefined keys, the predefined key should be closed with RegCloseKey(). That ensures that the new security information is in effect the next time the predefined key is referenced.

Parameters

hKey

Identifies an open key for which the security descriptor is set.

SecurityInformation

Specifies a SECURITY_INFORMATION structure that indicates the contents of the supplied security descriptor.

Because subkeys are not ordered, any new subkey will have an arbitrary index. This means the function may return subkeys in any order.

pSecurityDescriptor

Points to a SECURITY_DESCRIPTOR structure that specifies the security attributes to set for the specified key.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegCloseKey(), RegDeleteKey(), RegGetKeySecurity(), SECURITY_INFORMATION  

RegSetValueEx()

NAME

RegSetValueEx() - The RegSetValueEx() function stores data in the value field of an open registry key. It can also set additional value and type information for the specified key.

Synopsis

#include <winreg.h>

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

Description

Value lengths are limited by available memory. Long values (more than 2048 bytes) should be stored as files with the filenames stored in the registry. This helps the registry perform efficiently. Application elements such as icons, bitmaps, and executable files should be stored as files and not be placed in the registry.

The key identified by the hKey parameter must have been opened with KEY_SET_VALUE access. To open the key, use the RegCreateKeyEx() or RegOpenKeyEx() function.

If dwType is the REG_SZ, REG_MULTI_SZ or REG_EXPAND_SZ type and the ANSI version of this function is used (either by explicitly calling RegSetValueExA or by not defining UNICODE before including the WINDOWS.H file), the data pointed to by the lpData parameter must be an ANSI character string. The string is converted to Unicode before it is stored in the registry.

Parameters

hKey

Identifies a currently open key or any of the following predefined reserved handle values:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_CONFIG

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

lpValueName

Points to a string containing the name of the value to set. If a value with this name is not already present in the key, the function adds it to the key.

If this parameter is NULL or points to an empty string and the dwType parameter is the REG_SZ type, this function sets the same value the RegSetValue function would set.

Reserved

Reserved; must be zero.

dwType

Specifies the type of information to be stored as the value's data. This parameter can be one of the following values:

1.  RegSetValueEx dwType Values

lpData

Points to a buffer containing the data to be stored with the specified value name.

cbData

Specifies the size, in bytes, of the information pointed to by the lpData parameter. If the data is of type REG_SZ, REG_EXPAND_SZ, or REG_MULTI_SZ, cbData must include the size of the terminating NULL character.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegCreateKeyEx(), RegFlushKey(), RegOpenKeyEx(), RegQueryValueEx(),  

RegUnLoadKey()

NAME

RegUnLoadKey() - The RegUnLoadKey() function unloads the specified key and subkeys from the registry.

Synopsis

#include <winreg.h>

LONG RegUnLoadKey((
        HKEY hKey,
        LPCTSTR lpSubKey );

Description

This function removes a hive from the registry but does not modify the file containing the registry information. A hive is a discrete body of keys, subkeys, and values that is rooted at the top of the registry hierarchy.

Parameters

hKey

Specifies the key to be unloaded. This can be a predefined reserved handle value, or a handle returned by a call to RegConnectRegistry(). The predefined reserved handle values are:

• HKEY_LOCAL_MACHINE

• HKEY_USERS

lpSubKey

Points to a NULL-terminated string containing the name of the subkey to be unloaded. The key referred to by the lpSubKey parameter must have been created by using the RegLoadKey() function.

Return Values

If the function succeeds, the return value is ERROR_SUCCESS. If the function fails, the return value is a nonzero error code defined in WINERROR.H. You can use the FormatMessage function with the FORMAT_MESSAGE_FROM_SYSTEM flag to get a generic description of the error.

See Also

RegConnectRegistry(), RegDeleteKey(), RegLoadKey(), RegRestoreKey()

24.9    Registry Structures

24.9.1    VALENT

The VALENT structure contains information about a registry value. The RegQueryMultipleValues() function uses this structure.

typedef struct value_ent {
    LPTSTR   ve_valuename;
    DWORD ve_valuelen;
    DWORD ve_valueptr;
    DWORD ve_type;
}VALENT;

Members

ve_valuename

Pointer to a NULL-terminated string. Before calling RegQueryMultipleValues(), set this member to point to the name of a value to retrieve.

ve_valuelen

Specifies the size, in bytes, of the data pointed to by ve_valueptr.

ve_valueptr

Pointer to the data for the value entry. This is a pointer to the value's data returned in the lpValueBuf buffer filled in by RegQueryMultipleValues().

ve_type

Specifies the type code for the value entry. The type code can be one of the following values:

Table 24-2:  VALENT ve_type Values

See Also

RegQueryMultipleValues()