3.1.5.10 BaseRegEnumKey (Opnum 9)

  • Article

The BaseRegEnumKey method is called by the client in order to enumerate a subkey. In response, the server returns a requested subkey.

 error_status_t BaseRegEnumKey(
   [in] RPC_HKEY hKey,
   [in] DWORD dwIndex,
   [in] PRRP_UNICODE_STRING lpNameIn,
   [out] PRRP_UNICODE_STRING lpNameOut,
   [in, unique] PRRP_UNICODE_STRING lpClassIn,
   [out] PRPC_UNICODE_STRING* lplpClassOut,
   [in, out, unique] PFILETIME lpftLastWriteTime
 );

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: The index of the subkey to retrieve, as specified in section 3.1.1.1.

lpNameIn: A pointer to an RRP_UNICODE_STRING structure (section 2.2.4) that contains the key name to be retrieved, as specified in section 3.1.1.1. 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. The Length field MUST be set to 0.

lpNameOut: A pointer to an RRP_UNICODE_STRING structure that receives the name of the retrieved key, as specified in section 3.1.1.1. All fields MUST be set to 0.

lpClassIn: A pointer to an RRP_UNICODE_STRING structure (section 2.2.4) that contains the class to be retrieved, as specified in section 3.1.1.6. This is used by the server to determine the maximum length for the output class parameter and to allocate space accordingly. The content is ignored.

lplpClassOut: A pointer to a PRPC_UNICODE_STRING structure ([MS-DTYP] section 2.3.10), that receives the class of the retrieved key, as specified in section 3.1.1.6. This parameter is optional.

lpftLastWriteTime: MUST be the time when the value was last written (set or created).

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_ENUMERATE_SUB_KEYS access rights.

0x0000000E

ERROR_OUTOFMEMORY

Not enough storage is available to complete this operation.

0x00000057

ERROR_INVALID_PARAMETER

A parameter is incorrect.

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.

0x000000EA

ERROR_MORE_DATA

The size of the buffer is not large enough to hold the requested data.

Server Operations

If the registry server can no longer service registry requests because server shutdown has been initiated, the server MUST return ERROR_WRITE_PROTECT.

If the dwIndex parameter is beyond the range of subkeys, the server MUST return ERROR_NO_MORE_ITEMS to indicate that enumeration is complete.

If the lplpClassOut parameter does not contain enough space for the class name, the server MUST return ERROR_MORE_DATA.

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.

The lpNameIn parameter specifies (in the MaxmimumLength member of the RRP_UNICODE_STRING structure) the length of the buffer allocated by the RPC client. This string is transferred as an in parameter to the server. Its maximum length is used to allocate the output Unicode string (lpNameOut) that transfers data back to the client.

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

The server MUST copy the name of the retrieved subkey (as specified in section 3.1.1.1), including the terminating null character, to the buffer that is pointed to by the lpNameOut parameter in the client request. The server MUST not copy the full key hierarchy to the buffer. If a class is associated with the key, the server MUST copy this class to the buffer that is pointed to by the lpClassOut parameter. The server MUST return the time a value was last modified in the lpftLastWriteTime parameter.

The caller MUST have KEY_ENUMERATE_SUB_KEYS 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.