3.1.5.11 BaseRegEnumValue (Opnum 10)

The BaseRegEnumValue method is called by the client. In response, the server enumerates the value at the specified index for the specified registry key.

 error_status_t BaseRegEnumValue(
   [in] RPC_HKEY hKey,
   [in] DWORD dwIndex,
   [in] PRRP_UNICODE_STRING lpValueNameIn,
   [out] PRPC_UNICODE_STRING lpValueNameOut,
   [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: 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.

dwIndex: MUST be the index of the value to be retrieved, as specified in section 3.1.1.5.

lpValueNameIn: A pointer to an RRP_UNICODE_STRING structure that contains the value name to be retrieved, as specified in section 3.1.1.5. This is used by the server to determine the maximum length for the output name parameter and to allocate space accordingly. The content is ignored, and only the maximum length is significant.

lpValueNameOut: A pointer to an RPC_UNICODE_STRING structure that receives the retrieved value name, as specified in section 3.1.1.5.

lpType: An optional pointer to a buffer that receives the REG_VALUE_TYPE of the value (as specified in section 3.1.1.5), or it MUST be NULL.

lpData: An optional pointer to a buffer that receives the data of the value entry.

lpcbData: A pointer to a variable that MUST contain the size of the buffer that is pointed to by lpData. MUST NOT be NULL if lpData is present.

lpcbLen: MUST specify the number of bytes to transmit to the client.

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.
0x0000000E ERROR_OUTOFMEMORY	Not enough storage is available to complete this operation.
0x00000057 ERROR_INVALID_PARAMETER	A parameter is incorrect.
0x0000007A ERROR_INSUFFICIENT_BUFFER	The data area passed to a system call is too small.
0x000000EA ERROR_MORE_DATA	More data is available.
0x00000103 ERROR_NO_MORE_ITEMS	No more data is available.
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.

The server MUST first validate that the hKey parameter is currently an open handle which MUST have been opened previously using one of the methods specified in section 3.1.5. If the hKey parameter is not an already opened handle, the server MUST return ERROR_INVALID_PARAMETER.

In response to this request from the client, for a successful operation, the server MUST return the value and data at the index that is specified by the dwIndex parameter for the key that is specified by the hKey parameter in the client request.

Only the maximum length field of the lpValueNameIn is used to determine the buffer length to be allocated by the service. Specify a string with a zero length but maximum length set to the largest buffer size needed to hold the value names.

The server MUST return the value name (as specified in section 3.1.1.5) in the lpValueNameOut parameter and the type of the value in the lpType parameter. The type of the value MUST be one of the values that are specified by REG_VALUE_TYPE in section 3.1.1.5.

If the request contains a pointer to a buffer in the lpData parameter, the server MUST return the data of the value entry, if present. The lpcbData parameter represents the size of this buffer. If the size is sufficient to hold the data, the server MUST return the number of BYTES that are returned in the lpData parameter. If the size is insufficient to hold the data of the value entry, the server MUST return 122 (ERROR_INSUFFICIENT_BUFFER) to indicate that the buffer was insufficient.

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]) to indicate an error.

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

If the output buffer is too small to contain the value, the server MUST return ERROR_MORE_DATA. The call SHOULD be repeated with a larger output buffer.

If the input index is beyond the number of values for a key, the server MUST return ERROR_NO_MORE_ITEMS. This signals the end of enumeration to the caller.