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

지정된 KeyValueInformationClass에 따라 호출자가 설정해야 하는 KeyValueInformation 버퍼의 크기(바이트)입니다. 요청된 모든 데이터를 수신하려면 버퍼가 요청된 데이터의 크기만큼 커야 합니다.

[out] ResultLength

결과 데이터의 길이에 대한 출력 포인터입니다. 이 매개 변수는 호출자가 할당한 ULONG 변수를 가리키며, 메서드는 KeyValueInformation 버퍼에 실제로 기록된 바이트 수를 지정하는 개수를 씁니다. 그러나 지정된 버퍼 길이가 너무 작아서 정보를 포함할 수 없는 경우 메서드는 필요한 버퍼 크기를 출력하고 STATUS_BUFFER_OVERFLOW 또는 STATUS_BUFFER_TOO_SMALL 반환합니다. 자세한 내용은 아래 설명 부분을 참조하십시오.

반환 값

QueryValueKey 는 호출이 요청된 정보를 KeyValueInformation 버퍼에 복사하는 데 성공하면 STATUS_SUCCESS 반환합니다. 지정된 버퍼 크기가 너무 작아서 요청된 모든 정보를 수신하지 못하면 메서드는 STATUS_BUFFER_OVERFLOW 반환합니다. 지정된 버퍼 크기가 너무 작아서 요청된 정보를 수신할 수 없는 경우 메서드는 STATUS_BUFFER_TOO_SMALL 반환합니다. 그렇지 않으면 메서드는 적절한 오류 상태 코드를 반환합니다. 다음 표에서는 몇 가지 가능한 오류 코드를 보여 줍니다.

반환 코드	설명
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 에 기록된 값은 요청된 모든 정보를 보유하는 데 필요한 최소 버퍼 크기를 나타냅니다.