EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE 콜백 함수(wdfchildlist.h)

아티클
08/08/2023

[KMDF에만 적용]

드라이버의 EvtChildListIdentificationDescriptionDuplicate 이벤트 콜백 함수는 자식 식별 설명을 복제합니다.

구문

EVT_WDF_CHILD_LIST_IDENTIFICATION_DESCRIPTION_DUPLICATE EvtWdfChildListIdentificationDescriptionDuplicate;

NTSTATUS EvtWdfChildListIdentificationDescriptionDuplicate(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER SourceIdentificationDescription,
  [out] PWDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER DestinationIdentificationDescription
)
{...}

매개 변수

[in] ChildList

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

[in] SourceIdentificationDescription

자식 식별 설명의 원본 위치를 식별하는 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER 구조체에 대한 포인터입니다.

[out] DestinationIdentificationDescription

중복 자식 식별 설명의 대상 위치를 식별하는 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER 구조체에 대한 포인터입니다.

반환 값

작업이 성공하면 EvtChildListIdentificationDescriptionDuplicate 콜백 함수는 STATUS_SUCCESS 또는 NT_SUCCESS(상태)가 TRUE와 같은 다른 상태 값을 반환해야 합니다. 그렇지 않으면 이 콜백 함수는 NT_SUCCESS(상태)가 FALSE와 같은 상태 값을 반환해야 합니다.

설명

버스 드라이버가 동적 열거형을 사용하는 경우 WdfFdoInitSetDefaultChildListConfig 또는 WdfChildListCreate를 호출하여 EvtChildListIdentificationDescriptionDuplicate 콜백 함수를 등록할 수 있습니다.

프레임워크는 설명의 내부 복사본을 가질 수 있도록 드라이버 제공 식별 설명을 복제합니다.

EvtChildListIdentificationDescriptionDuplicate 콜백 함수는 ID 설명의 중복 복사본을 만들어야 합니다. 프레임워크가 RtlCopyMemory 를 호출하여 식별 설명을 복제할 수 없는 경우 드라이버는 이 콜백 함수를 제공해야 합니다. 설명에 추가 메모리에 대한 포인터가 포함되어 있으면 프레임워크에서 RtlCopyMemory 를 호출할 수 없습니다.

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

다음 단계에서는 일반적인 시나리오를 설명합니다.

드라이버는 자식 디바이스가 있는지 확인합니다.
드라이버는 WDF_CHILD_IDENTIFICATION_DESCRIPTION_HEADER 구조가 포함된 드라이버 정의 구조를 채우고 디바이스별 크기의 식별 정보를 저장하기 위해 추가 메모리를 동적으로 할당하여 식별 설명을 만듭니다.
드라이버는 WdfChildListAddOrUpdateChildDescriptionAsPresent 를 호출하여 자식 디바이스를 보고하고 식별 설명에 대한 포인터를 제공합니다.
프레임워크는 EvtChildListIdentificationDescriptionDuplicate 콜백 함수(있는 경우) 또는 RtlCopyMemory 를 호출하여 설명의 내부 복사본을 가질 수 있도록 식별 설명을 복제합니다.

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

일반적으로 ExAllocatePool을 호출하여 추가 메모리를 할당합니다.
할당된 메모리의 주소를 드라이버 정의 주소 설명 구조(즉, 콜백 함수의 DestinationIdentificationDescription 구조)에 저장합니다.
콜백 함수의 SourceIdentificationDescription 구조에서 콜백 함수의 DestinationIdentificationDescription 구조체로 다른 구조체 멤버를 복사합니다.

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

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

드라이버가 EvtChildListIdentificationDescriptionDuplicate 콜백 함수를 제공하는 경우 EvtChildListIdentificationDescriptionCopy, EvtChildListIdentificationDescriptionCompare 및 EvtChildListIdentificationDescriptionCleanup 콜백 함수가 필요할 수도 있습니다.

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