EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE 콜백 함수(wdfchildlist.h)

아티클
02/29/2024

[KMDF에만 적용]

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

구문

EVT_WDF_CHILD_LIST_ADDRESS_DESCRIPTION_DUPLICATE EvtWdfChildListAddressDescriptionDuplicate;

NTSTATUS EvtWdfChildListAddressDescriptionDuplicate(
  [in]  WDFCHILDLIST ChildList,
  [in]  PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER SourceAddressDescription,
  [out] PWDF_CHILD_ADDRESS_DESCRIPTION_HEADER DestinationAddressDescription
)
{...}

매개 변수

[in] ChildList

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

[in] SourceAddressDescription

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

[out] DestinationAddressDescription

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

반환 값

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

설명

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

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

EvtChildListAddressDescriptionDuplicate 콜백 함수는 주소 설명의 중복 복사본을 만들어야 합니다. 드라이버는 자식 디바이스에 주소 설명이 필요하고 프레임워크가 RtlCopyMemory 를 호출하여 주소 설명을 복제할 수 없는 경우 이 콜백 함수를 제공해야 합니다. 설명에 추가 메모리에 대한 포인터가 포함된 경우 프레임워크에서 RtlCopyMemory 를 호출할 수 없습니다.

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

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

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

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

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

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

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

드라이버가 EvtChildListAddressDescriptionDuplicate 콜백 함수를 제공하는 경우 EvtChildListAddressDescriptionCopy 및 EvtChildListAddressDescriptionCleanup 콜백 함수가 필요할 수도 있습니다.

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