3.1.5.17 BaseRegQueryValue (Opnum 17)

  • Article

The BaseRegQueryValue method is called by the client. In response, the server returns the data that is associated with the named value of a specified registry open key. If a value name is not specified, the server returns the data that is associated with the default value of the specified registry open key.

 error_status_t BaseRegQueryValue(
   [in] RPC_HKEY hKey,
   [in] PRRP_UNICODE_STRING lpValueName,
   [in, out, unique] LPDWORD lpType,
   [in, out, unique, size_is(lpcbData ? *lpcbData :0), length_is(lpcbLen ? *lpcbLen : 0), range(0, 0x4000000)] 
     LPBYTE lpData,
   [in, out, unique] LPDWORD lpcbData,
   [in, out, unique] LPDWORD lpcbLen
 );

hKey: On input, 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.

lpValueName: On input, the client sets lpValueName to a pointer to an RRP_UNICODE_STRING structure that MUST contain the name of the value, as specified in section 3.1.1. If the client sets lpValueName to NULL, the server MUST fail this method and return ERROR_INVALID_PARAMETER.

lpType: On input, the client sets lpType to a pointer to a variable to receive the type code of a value entry. On output, the server MUST set this parameter to NULL if the value specified by the lpValueName parameter is not found. If the client sets lpType to NULL, the server MUST fail this method and return ERROR_INVALID_PARAMETER.

lpData: On input, the client sets lpData to a pointer to a buffer to receive the data of the value entry.

lpcbData: A pointer to a variable that, on input, contains the size in bytes of the buffer that is pointed to by the lpData parameter. On output, the variable receives the number of bytes that are returned in lpData. This length variable MUST be set to 0 by the server if the client provides NULL for the lpData parameter.

If the client sets lpcbData to NULL, the server MUST fail this method and return ERROR_INVALID_PARAMETER.

lpcbLen: A pointer to a variable that contains the number of bytes to transmit to the client. On input, the client MUST allocate the memory for this parameter and the pointer value of this parameter MUST not be NULL. On output, the server MUST set this parameter to the size (in bytes) of the buffer pointed to by the lpData parameter. If the client sets lpcbLen to NULL, the server MUST fail this method and return ERROR_INVALID_PARAMETER.

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.

0x00000002

ERROR_FILE_NOT_FOUND

The value specified by lpValueName was not found. If lpValueName was not specified, the default value has not been defined.

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.

0x000000EA

ERROR_MORE_DATA

The data to be returned is larger than the buffer provided.

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 value that is specified by the lpValueName parameter for the key that is specified by the hKey parameter.

If, on input, the lpValueName parameter in the client request is an empty string, the server MUST return the data that is associated with the default value, as specified in section 3.1.1.5.

The server MUST return, on output, a pointer to a variable to specify the value type in the lpType parameter. The value of lpType MUST be one of the values that is specified by REG_VALUE_TYPES (as specified in section 3.1.1.5), or it MUST be NULL.

If the client sets the lpValueName parameter to NULL, the server MUST fail the method and return ERROR_INVALID_PARAMETER.

If the client sets the lpData parameter to NULL on input, the server assumes the client request is to determine the actual size of the data contained in the value indicated by lpValueName, such that an adequate-sized buffer can be provided by the client in a subsequent call to BaseRegQueryValue. If the client sets the lpData parameter to NULL on input, the server MUST return ERROR_SUCCESS and return the actual size of the data of the value indicated by lpValueName in the lpcbData parameter.

The server MUST return, on output, the data that is associated with the specified value in the buffer that is pointed to by the lpData parameter. If the size, in bytes, of the data that is associated with the specified value is too large to fit in the buffer pointed to by the lpData parameter with size specified by the lpcbData parameter, the server MUST return ERROR_MORE_DATA. The server MUST, on output, update the value of the variable pointed to by the lpcbData parameter to the actual size of the data associated with the specified value. This enables the client to determine the correct size of the lpData parameter in a subsequent call to BaseRegQueryValue.

The server, on output, MUST return (in the value that is pointed to by the lpcbData parameter) the size in bytes of the data that is returned in the lpData parameter. If the lpData parameter is NULL, the server SHOULD<21> set the value of the lpcbData parameter to NULL.

If the server operation is not successful, the server MUST set the value of the variable pointed to by lpcbLen to 0.

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

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