EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE 콜백 함수(wdfchildlist.h)

아티클
02/29/2024

[KMDF에만 적용]

드라이버의 EvtChildListIdentificationDescriptionCompare 이벤트 콜백 함수는 한 자식 식별 설명을 다른 자식 식별 설명과 비교합니다.

구문

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_COMPARE EvtWdfChildListIdentificationDescriptionCompare;

BOOLEAN EvtWdfChildListIdentificationDescriptionCompare(
  [in] WDFCHILDLIST ChildList,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER FirstIdentificationDescription,
  [in] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SecondIdentificationDescription
)
{...}

매개 변수

[in] ChildList

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

[in] FirstIdentificationDescription

하나의 자식 식별 설명을 식별하는 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER 구조체에 대한 포인터입니다.

[in] SecondIdentificationDescription

다른 자식 식별 설명을 식별하는 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER 구조체에 대한 포인터입니다.

반환 값

EvtChildListIdentificationDescriptionCompare 콜백 함수는 두 자식 ID 설명이 일치하는 경우 TRUE를 반환해야 합니다. 그렇지 않으면 이 함수는 FALSE를 반환해야 합니다.

설명

버스 드라이버가 동적 열거형을 사용하는 경우 WdfFdoInitSetDefaultChildListConfig 또는 WdfChildListCreate를 호출하여 EvtChildListIdentificationDescriptionCompare 콜백 함수를 등록할 수 있습니다. 드라이버는 WdfChildListRetrieveNextDevice를 호출할 때 두 번째 특수 사례인 EvtChildListIdentificationDescriptionCompare 콜백 함수를 등록할 수도 있습니다.

프레임워크는 두 설명이 동일한 디바이스를 식별하는지 확인해야 하는 경우 두 식별 설명을 비교합니다.

EvtChildListIdentificationDescriptionCompare 콜백 함수는 두 식별 설명의 내용을 비교하고 일치하는 경우 TRUE를 반환해야 합니다. 프레임워크에서 RtlCompareMemory 를 호출하여 식별 설명을 비교할 수 없는 경우 드라이버는 이 콜백 함수를 제공해야 합니다. 설명에 추가 메모리에 대한 포인터가 포함된 경우 프레임워크에서 RtlCompareMemory 를 호출할 수 없습니다.

드라이버가 EvtChildListIdentificationDescriptionCompare 콜백 함수를 제공하지 않는 경우 프레임워크는 RtlCompareMemory를 호출하여 식별 설명을 비교합니다.

다음 단계에서는 가능한 시나리오에 대해 설명합니다.

드라이버는 WdfChildListRetrieveAddressDescription 을 호출하여 자식 목록에 저장된 프레임워크의 ID 설명 복사본과 연결된 주소 설명을 가져옵니다.
프레임워크는 자식 목록을 트래버스합니다. 자식의 식별 설명이 WdfChildListRetrieveAddressDescription이라고 할 때 드라이버가 지정한 설명과 일치하는지 확인하기 위해 프레임워크는 EvtChildListIdentificationDescriptionCompare 콜백 함수(있는 경우) 또는 RtlCompareMemory를 호출합니다.
두 식별 설명이 일치하고 비교에서 TRUE를 반환하는 경우 프레임워크는 목록 트래버스를 중지합니다.
프레임워크는 드라이버가 WdfChildListRetrieveAddressDescription을 호출할 때 제공한 메모리에 주소 설명을 복사합니다.

각 설명이 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER 구조체의 IdentificationDescriptionSize 멤버에 의해 지정된 미리 결정된 크기의 단일 구조로 구성된 경우 프레임워크는 RtlCompareMemory를 사용하여 식별 설명을 비교할 수 있습니다. 그러나 경우에 따라 설명에 동적으로 할당된 메모리에 저장된 추가 정보도 포함되어야 합니다. 이 경우 일반적으로 멤버가 동적으로 할당된 메모리를 가리키도록 설명 구조를 정의하고 드라이버는 EvtChildListIdentificationDescriptionCompare 콜백 함수를 제공해야 합니다.

이 콜백 함수는 두 식별 설명이 동일한 디바이스를 나타내는지 여부를 결정합니다. 콜백 함수는 해당 결정을 내리기 위해 모든 구조체 멤버를 비교할 필요가 없습니다. 예를 들어 ID 설명에 일련 번호와 하드웨어 식별자 집합이 다음과 같이 포함되어 있다고 가정합니다.

typedef struct _PDO_IDENTIFICATION_DESCRIPTION {
  WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER Header;
  ULONG DeviceSerialNumber;
  ULONG CchHardwareIds;
  PWCHAR HardwareIds;
} PDO_IDENTIFICATION_DESCRIPTION, *PPDO_IDENTIFICATION_DESCRIPTION;

이 경우 EvtChildListIdentificationDescriptionCompare 콜백 함수는 DeviceSerialNumber 멤버만 비교하여 두 설명이 동일한 디바이스를 나타내는지 확인해야 합니다.

드라이버가 WdfChildListRetrieveNextDevice 를 호출하여 디바이스 목록을 트래버스하는 경우 다음 설명을 검색할 때 프레임워크에서 사용하는 추가 EvtChildListIdentificationDescriptionCompare 콜백 함수를 제공할 수 있습니다. 프레임워크는 드라이버 제공 WDF_RETRIEVE_CHILD_FLAGS 형식 플래그와 일치하는 자식 디바이스를 찾습니다. 드라이버가 특별한 EvtChildListIdentificationDescriptionCompare 콜백 함수를 제공하는 경우 프레임워크는 콜백 함수를 사용하여 검색을 구체화합니다. 드라이버가 특별한 EvtChildListIdentificationDescriptionCompare 콜백 함수를 제공하지 않는 경우 프레임워크는 RtlCompareMemory를 호출하지 않습니다. 이 함수는 지정된 플래그와 일치하는 각 자식 디바이스를 반환합니다.

드라이버의 EvtChildListIdentificationDescriptionCompare 콜백 함수가 호출할 수 있는 유일한 프레임워크 자식 목록 개체 메서드는 WdfChildListGetDevice입니다.

프레임워크는 EvtChildListIdentificationDescriptionCompareEvtChildListIdentificationDescriptionCompare 콜백 함수를 호출하기 전에 내부 자식 목록 개체 잠금을 획득합니다. 콜백 함수는 프레임워크 메모리 개체 메서드 호출 및 개체 컨텍스트 공간 액세스와 같은 비교 작업과 관련된 작업만 수행해야 합니다. 다른 드라이버에 액세스하는 메서드를 호출해서는 안 됩니다.

동적 열거형에 대한 자세한 내용은 버스에서 디바이스 열거를 참조하세요.