WdfRegistryQueryMultiString 함수(wdfregistry.h)

아티클
02/07/2025

[KMDF 및 UMDF에 적용]

WdfRegistryQueryMultiString 메서드는 현재 지정된 다중 문자열 레지스트리 값에 할당된 문자열을 검색하고, 각 문자열에 대한 프레임워크 문자열 개체를 만들고, 지정된 개체 컬렉션각 문자열 개체를 추가합니다.

통사론

NTSTATUS WdfRegistryQueryMultiString(
  [in]           WDFKEY                 Key,
  [in]           PCUNICODE_STRING       ValueName,
  [in, optional] PWDF_OBJECT_ATTRIBUTES StringsAttributes,
  [in]           WDFCOLLECTION          Collection
);

매개 변수

[in] Key

열린 레지스트리 키를 나타내는 레지스트리 키 개체에 대한 핸들입니다.

[in] ValueName

값 이름을 포함하는 UNICODE_STRING 구조체에 대한 포인터입니다.

[in, optional] StringsAttributes

각 새 문자열 개체에 대한 개체 특성을 포함하는 WDF_OBJECT_ATTRIBUTES 구조체에 대한 포인터입니다. 이 매개 변수는 선택 사항이며 WDF_NO_OBJECT_ATTRIBUTES 수 있습니다.

[in] Collection

드라이버 제공 프레임워크 컬렉션 개체에 대한 핸들입니다.

반환 값

WdfRegistryQueryMultiString 작업이 성공하면 STATUS_SUCCESS 반환합니다. 그렇지 않으면 메서드는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	묘사
STATUS_INVALID_DEVICE_REQUEST	WdfRegistryQueryMultiString IRQL = PASSIVE_LEVEL 호출되지 않았습니다.
STATUS_INVALID_PARAMETER	잘못된 매개 변수를 지정했습니다.
STATUS_INSUFFICIENT_RESOURCES	문자열 개체를 할당할 수 없습니다.
STATUS_ACCESS_DENIED	드라이버가 KEY_QUERY_VALUE, KEY_READ 또는 KEY_ALL_ACCESS 액세스 권한이 있는 레지스트리 키를 열지 않았습니다.
STATUS_OBJECT_TYPE_MISMATCH	지정한 ValueName 매개 변수가 REG_MULTI_SZ 않은 레지스트리 값의 데이터 형식입니다.
STATUS_OBJECT_NAME_NOT_FOUND	레지스트리 값을 사용할 수 없습니다.
STATUS_RESOURCE_DATA_NOT_FOUND	레지스트리 값은 지정된 키 아래에 있지만 비어 있습니다.

WdfRegistryQueryMultiString 메서드가 반환할 수 있는 다른 반환 값 목록은 Framework 개체 만들기 오류참조하세요.

이 메서드는 다른NTSTATUS 값을 반환할 수도 있습니다.

드라이버에서 잘못된 개체 핸들을 제공하면 버그 검사가 수행됩니다.

발언

드라이버가 WdfRegistryQueryMultiString호출하기 전에 WdfCollectionCreate 호출하여 컬렉션 개체를 만들어야 합니다.

호출자가 StringsAttributes 매개 변수를 제공하지 않으면 프레임워크에서 만든 모든 WDFSTRING 개체는 기본적으로 WDFDRIVER에 부모로 설정됩니다.

WdfRegistryQueryMultiString 반환한 후 드라이버는 WdfCollectionGetCount 호출하여 검색된 문자열 수를 가져오고 WdfCollectionGetItem 컬렉션에서 문자열 개체를 가져올 수 있습니다.

드라이버가 WdfRegistryQueryMultiString 메서드를 호출하기 전에 컬렉션에 개체가 포함된 경우 메서드는 해당 개체를 제거하거나 인덱스 값을 변경하지 않습니다. 새 개체는 컬렉션의 끝에 추가됩니다.

문자열 개체에서 문자열을 가져오려면 드라이버는 WdfStringGetUnicodeString호출할 수 있습니다.

레지스트리 키 개체에 대한 자세한 내용은 Framework-Based 드라이버레지스트리 사용을 참조하세요.

예제

다음 코드 예제에서는 컬렉션 개체를 만들고, 컬렉션 개체가 컬렉션에 대해 만든 모든 문자열 개체의 부모가 되도록 WDF_OBJECT_ATTRIBUTES 구조를 초기화하고, 다중 문자열 레지스트리 값에서 문자열을 검색합니다. 마지막으로, 이 예제에서는 프레임워크가 컬렉션에 추가한 문자열 개체의 수를 가져옵니다.

WDF_OBJECT_ATTRIBUTES stringAttributes;
WDFCOLLECTION col;
NTSTATUS status;
ULONG count;
DECLARE_CONST_UNICODE_STRING(valueMultiSz, VALUE_MULTI_SZ);

status = WdfCollectionCreate(
                             NULL,
                             &col
                             );
ASSERT(NT_SUCCESS(status));

WDF_OBJECT_ATTRIBUTES_INIT(&stringAttributes);
stringAttributes.ParentObject = col;

status = WdfRegistryQueryMultiString(
                                     Key,
                                     &valueMultiSzEmpty,
                                     &stringAttributes,
                                     col
                                     );

count = WdfCollectionGetCount(col);

요구 사항

요구	값
대상 플랫폼	보편적
최소 KMDF 버전	1.0
최소 UMDF 버전	2.0
헤더	wdfregistry.h(Wdf.h 포함)
라이브러리	Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF)
IRQL	PASSIVE_LEVEL
DDI 규정 준수 규칙	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)