3.1.5.16 BaseRegQueryInfoKey (Opnum 16)

The BaseRegQueryInfoKey method is called by the client. In response, the server returns relevant information on the key that corresponds to the specified key handle.

 error_status_t BaseRegQueryInfoKey(
   [in] RPC_HKEY hKey,
   [in] PRRP_UNICODE_STRING lpClassIn,
   [out] PRPC_UNICODE_STRING lpClassOut,
   [out] LPDWORD lpcSubKeys,
   [out] LPDWORD lpcbMaxSubKeyLen,
   [out] LPDWORD lpcbMaxClassLen,
   [out] LPDWORD lpcValues,
   [out] LPDWORD lpcbMaxValueNameLen,
   [out] LPDWORD lpcbMaxValueLen,
   [out] LPDWORD lpcbSecurityDescriptor,
   [out] 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.

lpClassIn: A pointer to an RRP_UNICODE_STRING structure that contains the class of the key to be retrieved, as specified in section 3.1.1.6. This string is optional; it is saved but is not used by the registry.

lpClassOut: A pointer to an RPC_UNICODE_STRING structure that receives the class of this key, as specified in section 3.1.1.6.

lpcSubKeys: A pointer to a DWORD that MUST receive the count of the subkeys of the specified key.

lpcbMaxSubKeyLen: A pointer to a DWORD that receives the size of the key's subkey with the longest name, or a greater size, as the number of TCHAR elements.

TCHAR elements are defined as follows.

 #ifdef UNICODE
 #typedef WCHAR TCHAR;
 #endif
  

lpcbMaxClassLen: A pointer to a DWORD that receives the size of the longest string that specifies a subkey class, or a greater size, in Unicode characters.

lpcValues: A pointer to a DWORD that receives the number of values that are associated with the key.

lpcbMaxValueNameLen: A pointer to a DWORD that receives the size of the key's longest value name, or a greater size, as the number of TCHAR elements.

lpcbMaxValueLen: A pointer to a DWORD that receives the size in bytes of the longest data component, or a greater size, in the key's values.

lpcbSecurityDescriptor: A pointer to a DWORD that receives the size in bytes of the key's SECURITY_DESCRIPTOR.

lpftLastWriteTime: A pointer to a FILETIME structure that receives the last write time.

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.
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 (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 returns information for the specified registry key.

The server MUST return the class that is associated with the key in the lpClassOut parameter, as specified in section 3.1.1.6.

The server MUST return a pointer to the variable that contains the number of subkeys for the specified key in the lpcSubKeys parameter. If there are no subkeys under the key indicated by hKey, the server MUST set this value to 0.

The server MUST return a pointer to the variable that contains the number of values associated with the key in the lpcValues parameter. If there are no values under the key indicated by hKey, the server MUST set this value to 0.

The server MUST return a pointer to the variable that contains the size (as the number of TCHAR elements) of the key's longest value name, or a greater size, in the lpcbMaxValueNameLen parameter. This size MUST NOT include the terminating null character. If there are no values under the key indicated by hKey, the server MUST set this value to 0.

The server MUST return a pointer to the variable that contains the size in bytes of the longest data component in the key's values or a greater size in the lpcbMaxValueLen parameter. If there are no subkeys under the key indicated by hKey, the server MUST set this value to 0.

The server MUST return a pointer to the variable that contains the size in bytes of the key's SECURITY_DESCRIPTOR in the lpcbSecurityDescriptor parameter.

The server MUST return a pointer to the FILETIME structure that specifies the last modification time of the key in the lpftLastWriteTime 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]) to indicate an error.

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

If any one of the parameters lpcSubKeys, lpcbMaxSubKeyLen, lpcValues, lpcbMaxValueNameLen, lpcbMaxValueLen, or lpftLastWriteTime is NULL the server MUST return ERROR_INVALID_PARAMETER.

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