WdfChildListRetrieveNextDevice 함수(wdfchildlist.h)

아티클
08/08/2023

[KMDF에만 적용]

WdfChildListRetrieveNextDevice 메서드는 지정된 자식 목록을 트래버스하고 지정된 조건과 일치하는 다음 자식 디바이스를 검색합니다.

구문

NTSTATUS WdfChildListRetrieveNextDevice(
  [in]      WDFCHILDLIST             ChildList,
  [in]      PWDF_CHILD_LIST_ITERATOR Iterator,
  [out]     WDFDEVICE                *Device,
  [in, out] PWDF_CHILD_RETRIEVE_INFO Info
);

매개 변수

[in] ChildList

프레임워크 자식 목록 개체에 대한 핸들입니다.

[in] Iterator

드라이버가 이전에 WdfChildListBeginIteration에 제공한 것과 동일한 호출자 할당 WDF_CHILD_LIST_ITERATOR 구조체에 대한 포인터입니다.

[out] Device

프레임워크 디바이스 개체에 대한 핸들을 수신하는 위치에 대한 포인터입니다. Iterator 매개 변수가 WdfRetrievePendingChildren 플래그를 지정하는 경우 수신된 값은 NULL입니다.

[in, out] Info

호출자가 할당한 WDF_CHILD_RETRIEVE_INFO 구조체에 대한 포인터입니다. 이 포인터는 선택 사항이며 NULL일 수 있습니다.

반환 값

WdfChildListRetrieveNextDevice는 작업이 성공하면 STATUS_SUCCESS 또는 NT_SUCCESS(상태)가 TRUE와 같은 다른 상태 값을 반환합니다. 그렇지 않으면 이 메서드는 다음 값 중 하나를 반환할 수 있습니다.

반환 코드	설명
STATUS_INVALID_PARAMETER	입력 매개 변수가 잘못되었습니다.
STATUS_INFO_LENGTH_MISMATCH	Iterator가 지정한 WDF_CHILD_LIST_ITERATOR 구조체의 크기가 잘못되었습니다.
STATUS_INVALID_DEVICE_REQUEST	주소 설명이 지정되었지만 자식 목록에 주소 설명이 포함되지 않았습니다.
STATUS_NO_MORE_ENTRIES	프레임워크가 자식 목록의 끝에 도달했습니다.
STATUS_INVALID_DEVICE_STATE	드라이버가 WdfChildListBeginIteration을 호출하지 않았습니다.

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

드라이버가 잘못된 개체 핸들을 제공하는 경우 시스템 버그 검사 발생합니다.

설명

WdfChildListRetrieveNextDevice를 호출하기 전에 드라이버는 WdfChildListBeginIteration을 호출해야 합니다. 드라이버가 자식 목록 트래버스를 완료한 후 WdfChildListEndIteration을 호출해야 합니다. 그런 다음 프레임워크는 플러그 앤 플레이(PnP) 관리자에게 자식 목록에 대한 변경 내용을 알릴 수 있습니다.

드라이버가 WdfChildListRetrieveNextDevice를 호출할 때마다 메서드는 다음 검색 조건과 일치하는 다음 자식을 검색합니다.

자식의 형식은 드라이버의 WDF_CHILD_LIST_ITERATOR 구조에서 WDF_RETRIEVE_CHILD_FLAGS 형식화된 플래그에 해당해야 합니다.
드라이버가 WDF_CHILD_RETRIEVE_INFO 구조에서 EvtChildListIdentificationDescriptionCompare 콜백 함수에 대한 포인터를 제공하는 경우 콜백 함수는 TRUE를 반환해야 합니다.

드라이버가 EvtChildListIdentificationDescriptionCompare 콜백 함수를 제공하는 경우 WDF_CHILD_RETRIEVE_INFO 구조에서 식별 설명 도 제공해야 합니다. 프레임워크는 콜백 함수를 사용하여 전달된 식별 설명자를 자식 목록의 자식 설명과 비교합니다( WDF_RETRIEVE_CHILD_FLAGS 형식의 플래그가 자식이 일치 후보임을 나타내는 경우). 콜백 함수가 TRUE를 반환하면 일치가 성공합니다. 콜백 함수가 FALSE를 반환하는 경우 프레임워크는 다른 후보를 찾습니다.

WdfChildListRetrieveNextDevice는 일치 항목을 찾으면 Info 매개 변수가 지정하는 포인터가 NULL이 아닌 경우 자식의 ID 설명과 주소 설명을 드라이버의 WDF_CHILD_RETRIEVE_INFO 구조에 복사합니다. (이 작업은 드라이버의 입력 식별 설명을 덮어씁니다.) 또한 메서드는 Device 매개 변수가 식별하는 위치에 자식의 디바이스 개체에 대한 핸들을 배치합니다.

자식 목록에 대한 자세한 내용은 동적 열거형을 참조하세요.

예제

다음 코드 예제에서는 부모 디바이스의 모든 자식이 배출되고 있음을 프레임워크에 알릴 수 있습니다. 이 예제에서는 디바이스의 기본 자식 목록을 가져오고 목록을 안내합니다. 각 자식의 식별 설명자를 가져오고 각 식별 설명자를 WdfChildListRequestChildEject에 전달합니다.

WDF_CHILD_LIST_ITERATOR  iterator;
WDFDEVICE  hChild;
NTSTATUS  status = STATUS_INVALID_PARAMETER;
WDFCHILDLIST  list;
WDF_CHILD_RETRIEVE_INFO  childInfo;
PDO_IDENTIFICATION_DESCRIPTION  description;
BOOLEAN  ret;

list = WdfFdoGetDefaultChildList(Device);

WDF_CHILD_LIST_ITERATOR_INIT(
                             &iterator,
                             WdfRetrievePresentChildren
                             );
WdfChildListBeginIteration(
                           list,
                           &iterator
                           );
for (;;) {
    WDF_CHILD_RETRIEVE_INFO_INIT(
                                 &childInfo,
                                 &description.Header
                                 );
    WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER_INIT(
                                                     &description.Header,
                                                     sizeof(description)
                                                     );
    status = WdfChildListRetrieveNextDevice(
                                            list, 
                                            &iterator, 
                                            &hChild, 
                                            &childInfo
                                            );
    if (!NT_SUCCESS(status) || status == STATUS_NO_MORE_ENTRIES) {
       break;
    }
    ASSERT(childInfo.Status == WdfChildListRetrieveDeviceSuccess);

    ret = WdfChildListRequestChildEject(
                                        list,
                                        &description.Header
                                        );
    if(!ret) {
       WDFVERIFY(ret);
    }
}
WdfChildListEndIteration(
                         list,
                         &iterator
                         );
if (status == STATUS_NO_MORE_ENTRIES) {
   status = STATUS_SUCCESS;
}
return status;

요구 사항

요구 사항	값
대상 플랫폼	유니버설
최소 KMDF 버전	1.0
머리글	wdfchildlist.h(Wdf.h 포함)
라이브러리	Wdf01000.sys(프레임워크 라이브러리 버전 관리 참조)
IRQL	<= DISPATCH_LEVEL
DDI 규정 준수 규칙	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)