RegQueryMultipleValues
The RegQueryMultipleValues
function retrieves the type and data for a list of value names associated with
an open registry key.
LONG RegQueryMultipleValues(
|
HKEY hKey, |
// handle of key to
query |
|
PVALENT val_list, |
// address of array
of value entry structures |
|
DWORD num_vals, |
// size of array of
value entry structures |
|
LPTSTR lpValueBuf, |
// address of
buffer for value information |
|
LPDWORD ldwTotsize |
// address of size
of value buffer |
|
); |
|
Parameters
hKey
Identifies a
currently open key or any of the pre-defined reserved handle values:
HKEY_CLASSES_ROOT
HEY_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:
|
Value |
Meaning |
|
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. |
Remarks
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.
See Also