Export (0) Print
Expand All

RegQueryMultipleValues function

Retrieves the type and data for a list of value names associated with an open registry key.

Syntax


LONG WINAPI RegQueryMultipleValues(
  _In_         HKEY hKey,
  _Out_        PVALENT val_list,
  _In_         DWORD num_vals,
  _Out_opt_    LPTSTR lpValueBuf,
  _Inout_opt_  LPDWORD ldwTotsize
);

Parameters

hKey [in]

A handle to an open registry key. The key must have been opened with the KEY_QUERY_VALUE access right. For more information, see Registry Key Security and Access Rights.

This handle is returned by the RegCreateKeyEx, RegCreateKeyTransacted, RegOpenKeyEx, or RegOpenKeyTransacted function. It can also be one of the following predefined keys:

HKEY_CLASSES_ROOT
HKEY_CURRENT_CONFIG
HKEY_CURRENT_USER
HKEY_LOCAL_MACHINE
HKEY_PERFORMANCE_DATA
HKEY_USERS
val_list [out]

A pointer to 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 [in]

The number of elements in the val_list array.

lpValueBuf [out, optional]

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

If lpValueBuf is NULL, the value pointed to by the ldwTotsize parameter must be zero, in which case the function returns ERROR_MORE_DATA and ldwTotsize receives the required size of the buffer, in bytes.

ldwTotsize [in, out, optional]

A pointer to a variable that specifies the size of the buffer pointed to by the lpValueBuf parameter, in bytes. If the function succeeds, ldwTotsize receives 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 value

If the function succeeds, the return value is ERROR_SUCCESS.

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

Return codeDescription
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 receives the required buffer size.

ERROR_TRANSFER_TOO_LONG

The total size 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 cannot 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.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Winreg.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

Unicode and ANSI names

RegQueryMultipleValuesW (Unicode) and RegQueryMultipleValuesA (ANSI)

See also

Registry Functions
Registry Overview
VALENT

 

 

Community Additions

ADD
Show:
© 2014 Microsoft