IRegistryKey：：QueryKey 方法 (portcls.h)

發行項
02/26/2024

方法 QueryKey 會擷取登錄機碼的相關信息，包括機碼名稱、機碼類別，以及子機碼數目及其大小。

語法

NTSTATUS QueryKey(
  [in]  KEY_INFORMATION_CLASS KeyInformationClass,
  [out] PVOID                 KeyInformation,
  [in]  ULONG                 Length,
  [out] PULONG                ResultLength
);

參數

[in] KeyInformationClass

指定要在緩衝區中傳回的信息類型。將此參數設定為下列其中一個KEY_INFORMATION_CLASS列舉值：

KeyBasicInformation
KeyFullInformation
KeyNodeInformation

[out] KeyInformation

呼叫端配置的緩衝區指標，方法會將要求的數據寫入其中。緩衝區會根據 KeyInformationClass 的值，保留類型為 KEY_BASIC_INFORMATION、KEY_FULL_INFORMATION 或 KEY_NODE_INFORMATION 的結構。結構後面接著 Unicode 字元的字串，其大小取決於所要求密鑰的相關信息類型，以及索引鍵名稱或類別字串的長度。

[in] Length

KeyInformation 緩衝區的位元組大小，呼叫端必須根據指定的KeyInformationClass來設定。若要接收所有要求的數據，緩衝區的大小必須至少與要求的數據大小相同。

[out] ResultLength

結果數據的長度輸出指標。此參數指向呼叫端配置的 ULONG 變數，方法會寫入計數，以指定實際寫入 KeyInformation 緩衝區的位元元組數目。不過，如果指定的緩衝區長度太小而無法包含資訊，則方法會改為輸出所需的緩衝區大小，並傳回STATUS_BUFFER_OVERFLOW或STATUS_BUFFER_TOO_SMALL。如需詳細資訊，請參閱接下來的＜備註＞一節。

傳回值

QueryKey 如果呼叫成功將要求的信息複製到 KeyInformation 緩衝區，則會傳回STATUS_SUCCESS。如果指定的緩衝區大小太小而無法接收所有要求的資訊，則方法會傳回STATUS_BUFFER_OVERFLOW。如果指定的緩衝區大小太小而無法接收任何要求的資訊，此方法會傳回STATUS_BUFFER_TOO_SMALL。否則，此方法會傳回適當的錯誤狀態代碼。下表顯示一些可能的錯誤碼。

傳回碼	Description
STATUS_INVALID_PARAMETER	表示傳遞至方法的其中一個參數無效。

備註

如果 KeyInformation 緩衝區太小而無法保存要求的資訊，此方法會將所需的大小寫入 *ResultLength ，並傳回STATUS_BUFFER_OVERFLOW或STATUS_BUFFER_TOO_SMALL的狀態代碼。如果方法只成功將部分要求的資訊寫入緩衝區，則此方法會傳回STATUS_BUFFER_OVERFLOW。如果方法無法將任何資訊寫入緩衝區，則會傳回STATUS_BUFFER_TOO_SMALL。寫入至 *ResultLength 的值表示保存所有要求資訊所需的最小緩衝區大小。