IRegistryKey：：QueryValueKey 方法 (portcls.h)

發行項
02/29/2024

方法 QueryValueKey 會擷取登錄機碼值專案的相關信息，包括其名稱、類型、數據大小和值。

語法

NTSTATUS QueryValueKey(
  [in]  PUNICODE_STRING             ValueName,
  [in]  KEY_VALUE_INFORMATION_CLASS KeyValueInformationClass,
  [out] PVOID                       KeyValueInformation,
  [in]  ULONG                       Length,
  [out] PULONG                      ResultLength
);

參數

[in] ValueName

值專案製造商提供名稱的指標。名稱字串是由類型為 UNICODE_STRING 的結構所指定。

[in] KeyValueInformationClass

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

KeyValueBasicInformation
KeyValueFullInformation
KeyValuePartialInformation

[out] KeyValueInformation

呼叫端配置的緩衝區指標，該方法會將要求的數據寫入其中。根據 KeyValueInformationClass 的值，緩衝區包含類型為 KEY_VALUE_BASIC_INFORMATION、KEY_VALUE_FULL_INFORMATION 或 KEY_VALUE_PARTIAL_INFORMATION 的結構。結構後面接著其他數據，其大小取決於索引鍵值的數據類型。

[in] Length

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

[out] ResultLength

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

傳回值

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

傳回碼	Description
STATUS_INVALID_PARAMETER	表示傳遞至方法的其中一個參數無效。
STATUS_OBJECT_NAME_NOT_FOUND	表示找不到具有指定名稱的值專案。

備註

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