3.1.4.2.39 ApiQueryInfoKey (Opnum 38)

(Protocol Version 3) The ApiQueryInfoKey method returns information about the designated cluster key. This includes the number of values in the key, the number of immediate subkeys in the key, the length of the longest key and value names, the length of the largest data value, and the length of the key's security descriptor.

The server SHOULD accept an ApiQueryInfoKey request if its protocol server state is read-only, and the server MUST accept the request for processing if it is in the read/write state, as specified in section 3.1.1.

The server SHOULD accept an ApiQueryInfoKey request if the client's access level is at least "Read" (section 3.1.4).

 error_status_t ApiQueryInfoKey(
   [in] HKEY_RPC hKey,
   [out] LPDWORD lpcSubKeys,
   [out] LPDWORD lpcbMaxSubKeyLen,
   [out] LPDWORD lpcValues,
   [out] LPDWORD lpcbMaxValueNameLen,
   [out] LPDWORD lpcbMaxValueLen,
   [out] LPDWORD lpcbSecurityDescriptor,
   [out] PFILETIME lpftLastWriteTime,
   [out] error_status_t *rpc_status
 );

hKey: The HKEY_RPC context handle for a key that was previously obtained by a call to ApiGetRootKey, ApiCreateKey, or ApiOpenKey.

lpcSubKeys: On successful completion of the method, the server MUST set the variable pointed to by lpcSubKeys to the number of keys that are contained in the designated key.

lpcbMaxSubKeyLen: On successful completion of the method, the server MUST set the variable pointed to by lpcbMaxSubKeyLen to the length, in characters of the subkey with the longest name.

lpcValues: On successful completion of the method, the server MUST set the variable pointed to by lpcValues to the number of values that are associated with the key.

lpcbMaxValueNameLen: On successful completion of the method, the server MUST set the variable pointed to by lpcbMaxValueNameLen to the length, in characters, of the value with the longest name.

lpcbMaxValueLen: On successful completion of the method, the server MUST set the variable pointed to by lpcbMaxValueLen to the length, in bytes, of the key's value that contains the largest amount of data.

lpcbSecurityDescriptor: On successful completion of the method, the server MUST set the variable pointed to by lpcbSecurityDescriptor to the length, in bytes, of the key's security descriptor.

lpftLastWriteTime: On successful completion of the method, the server MUST set lpftLastWriteTime to the time of the most recent modification to the key or any of its values. The lpftLastWriteTime parameter is a FILETIME data structure as specified in [MS-DTYP].

rpc_status: A 32-bit integer used to indicate success or failure. The RPC runtime MUST indicate, by writing to this parameter, whether the runtime succeeded in executing this method on the server. A value of 0x00000000 indicates that the method call was successfully transported to the server, executed with no faults with control returned to the client without encountering any communication faults. This value is separate from the value returned by the method and does not represent the success of the method. The client MUST treat all nonzero values the same, except as specified in section 3.2.4.6.

Return Values: The method MUST return the following error codes for the specified conditions.

Return value/code	Description
0x00000000 ERROR_SUCCESS	Success.
0x00000006 ERROR_INVALID_HANDLE	The hKey parameter does not represent a valid HKEY_RPC context handle.

For any other condition, the server MUST set Status to a value that is not one of the values listed in the preceding table. The client MUST treat all values not listed in the preceding table the same, except as specified in section 3.2.4.6.