3.1.5.26 BaseRegQueryMultipleValues (Opnum 29)

The BaseRegQueryMultipleValues method is called by the client. In response, the server returns the type and data for a client-specified list of value names that are associated with the specified registry key.

 error_status_t BaseRegQueryMultipleValues(
   [in] RPC_HKEY hKey,
   [in, size_is(num_vals), length_is(num_vals)] 
     PRVALENT val_listIn,
   [out, size_is(num_vals), length_is(num_vals)] 
     PRVALENT val_listOut,
   [in] DWORD num_vals,
   [in, out, unique, size_is(*ldwTotsize), length_is(*ldwTotsize)] 
     char* lpvalueBuf,
   [in, out, ref] LPDWORD ldwTotsize
 );

hKey: A handle to a key that MUST have been opened previously by using one of the open methods that are specified in section 3.1.5: OpenClassesRoot, OpenCurrentUser, OpenLocalMachine, OpenPerformanceData, OpenUsers, BaseRegCreateKey, BaseRegOpenKey, OpenCurrentConfig, OpenPerformanceText, OpenPerformanceNlsText.

val_listIn: A pointer to an array of RVALENT structures, one for each value to be queried. The array holds the list of value names for which the type and data MUST be returned.

val_listOut: A pointer to an array of RVALENT structures, one for each value to be queried.

num_vals: The size in bytes of the val_list array.

lpvalueBuf: Returns the data for each value that is specified by the val_listOut parameter.

ldwTotsize: The value that indicates the length in bytes of the lpvalueBuf parameter.

If lpvalueBuf is not large enough to contain all the data, it returns the size of the lpvalueBuf parameter that is required to return all the requested data.

Return Values: The method returns 0 (ERROR_SUCCESS) to indicate success; otherwise, it returns a nonzero error code, as specified in [MS-ERREF] section 2.2. The most common error codes are listed in the following table.

Return value/code	Description
0x00000005 ERROR_ACCESS_DENIED	The caller does not have KEY_QUERY_VALUE access rights.
0x00000057 ERROR_INVALID_PARAMETER	A parameter is incorrect.
0x00000078 ERROR_CALL_NOT_IMPLEMENTED	This function is not supported on this system.
0x00000013 ERROR_WRITE_PROTECT	A read or write operation was attempted to a volume after it was dismounted. The server can no longer service registry requests because server shutdown has been initiated.

Server Operations

If the registry server can no longer service registry requests because server shutdown has been initiated (SHUTDOWNINPROGRESS is set to TRUE), the server MUST return ERROR_WRITE_PROTECT.

In response to this request from the client, for a successful operation, the server MUST return the data that is associated with the values that are specified in the RVALENT parameter val_listIn of the client request for the key that is specified by the hKey parameter.

The server MUST return the data that is associated with the specified values in the buffer pointed to by the lpvalueBuf parameter of the response. For each of the requested values, in the response, the server MUST include the size, type, and pointer to the lpvalueBuf offset of the data that is associated with that value in the ve_valuelen, ve_type, and ve_valueptr parameters of the RVALENT structure, respectively.

The server MUST return the size in bytes of the data that is returned in the lpvalueBuf parameter in the ldwTotsize parameter.

The caller MUST have KEY_QUERY_VALUE access rights to invoke this method. For more information, see section 2.2.4.

The server MUST return 0 to indicate success or an appropriate error code (as specified in [MS-ERREF] section 2.2).

If the caller does not have access, the server MUST return ERROR_ACCESS_DENIED.

If any one of the parameters ldwTotsize and val_listOut is NULL, the server MUST return ERROR_INVALID_PARAMETER.

If the parameter num_vals has a value greater than zero and the parameter val_listIn is NULL, then the server MUST return ERROR_INVALID_PARAMETER.

For each of the RVALENT structures returned by calling parameter val_listIn: if the return value is greater than zero and the buffer is NULL, the server MUST return ERROR_INVALID_PARAMETER.