EVT_WDF_OBJECT_CONTEXT_CLEANUP 콜백 함수(wdfobject.h)

  • 아티클

[KMDF 및 UMDF에 적용]

드라이버의 EvtCleanupCallback 이벤트 콜백 함수는 개체를 삭제할 수 있도록 개체에서 드라이버의 참조를 제거합니다.

구문

EVT_WDF_OBJECT_CONTEXT_CLEANUP EvtWdfObjectContextCleanup;

void EvtWdfObjectContextCleanup(
  [in] WDFOBJECT Object
)
{...}

매개 변수

[in] Object

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

반환 값

없음

설명

드라이버는 WDF_OBJECT_ATTRIBUTES 구조에서 EvtCleanupCallback 콜백 함수를 지정할 수 있습니다. 이 구조체는 WdfDeviceCreate와 같은 프레임워크 개체를 만드는 모든 프레임워크 메서드에 대한 입력으로 사용됩니다.

프레임워크 또는 드라이버가 개체를 삭제하려고 할 때 프레임워크는 콜백 함수를 호출합니다.

드라이버가 개체의 참조 수를 늘리기 위해 WdfObjectReference를 호출한 경우 드라이버는 WdfObjectDereference를 호출하는 EvtCleanupCallback 콜백 함수를 제공해야 합니다. 이 호출을 통해 개체의 참조 수가 0으로 감소하고, 결과적으로 프레임워크는 드라이버의 EvtDestroyCallback 콜백 함수를 호출한 다음 개체를 삭제할 수 있습니다.

드라이버가 개체에 대해 EvtCleanupCallback 콜백 함수와 EvtDestroyCallback 콜백 함수를 모두 제공하는 경우 프레임워크는 먼저 EvtCleanupCallback 콜백 함수를 호출합니다.

프레임워크가 개체의 EvtCleanupCallback 콜백 함수를 호출한 후 드라이버는 EvtDestroyCallback 콜백 함수에서만 개체에 액세스할 수 있습니다. 그러나 드라이버는 EvtDestroyCallback에서 개체에 대한 메서드를 호출하려고 시도해서는 안 됩니다.

드라이버가 개체를 만들 때 개체별 메모리 버퍼를 할당하고 버퍼 포인터를 개체의 컨텍스트 공간에 저장하는 경우가 있습니다. 드라이버의 EvtCleanupCallback 또는 EvtDestroyCallback 콜백 함수는 이러한 메모리 버퍼의 할당을 취소할 수 있습니다.

일반적으로 드라이버가 개체에 대해 WdfObjectReference 를 호출하지 않는 경우 개체의 EvtCleanupCallback 콜백 함수는 개체 컨텍스트 할당의 할당을 취소할 수 있습니다. 이 경우 드라이버에는 개체에 대한 EvtDestroyCallback 콜백 함수가 필요하지 않습니다.

개체가 삭제되면 프레임워크는 개체의 자식도 삭제합니다. 한 가지 예외를 제외하고 프레임워크는 부모 개체의 루틴을 호출하기 전에 자식 개체의 EvtCleanupCallback 루틴을 호출하므로 드라이버는 자식의 EvtCleanupCallback 루틴을 실행할 때 부모 개체가 계속 존재하게 됩니다.

이 보장된 순서 지정에 대한 예외는 드라이버가 DISPATCH_LEVEL 완료되는 I/O 요청에 적용됩니다. 이러한 I/O 요청 개체에 PASSIVE_LEVEL EvtCleanupCallback 루틴을 호출해야 하는 하나 이상의 자식이 있는 경우 부모 요청은 하나 이상의 자식 앞에 삭제될 수 있습니다. 개체가 완료되기를 기다려야 하거나 페이징된 메모리에 액세스하는 경우 개체를 PASSIVE_LEVEL 정리해야 합니다.

드라이버가 DISPATCH_LEVEL 실행되는 동안 이러한 개체(또는 이러한 개체의 부모)를 삭제하려고 하면 프레임워크는 나중에 PASSIVE_LEVEL 처리를 위해 EvtCleanupCallback 을 작업 항목에 큐에 넣은 다음 자식에 대한 콜백이 실행되었는지 여부를 결정하지 않고 부모 개체에 대한 정리 콜백을 호출합니다.

이 동작으로 인해 발생할 수 있는 문제를 방지하기 위해 드라이버는 PASSIVE_LEVEL 정리가 필요한 개체에 대해 요청 개체를 부모로 설정해서는 안 됩니다. 기본적으로 대부분의 개체에 대한 부모는 WDFDEVICE이므로 드라이버는 기본값만 허용해야 합니다. 일반적으로 WDFDEVICE 개체가 개체를 만드는 메서드에 직접 또는 구조체의 일부로 매개 변수로 전달되는 경우 WDFDEVICE는 기본 부모입니다. 기본 부모에 대한 전체 목록은 프레임워크 개체 요약을 참조하세요.

위의 예외가 적용되지 않으면 프레임워크는 부모 개체의 EvtCleanupCallback 콜백 함수를 호출하기 전에 자식 개체의 EvtCleanupCallback 콜백 함수를 호출합니다. 다음으로, 자식의 참조 수가 0이면 프레임워크는 자식 개체의 EvtDestroyCallback 콜백 함수를 호출합니다. 마지막으로, 부모의 참조 수가 0이면 프레임워크는 부모 개체의 EvtDestroyCallback 콜백 함수를 호출합니다.

프레임워크 개체 삭제에 대한 자세한 내용은 Framework 개체 수명 주기를 참조하세요.

일반적으로 프레임워크는 IRQL <= DISPATCH_LEVEL EvtCleanupCallback 콜백 함수를 호출합니다. 그러나 프레임워크는 다음과 같은 상황에서 IRQL = PASSIVE_LEVEL 콜백 함수를 호출합니다.

  • 개체의 핸들 형식은 WDFDEVICE, WDFDRIVER, WDFDPC, WDFINTERRUPT, WDFIOTARGET, WDFQUEUE, WDFSTRING, WDFTIMER 또는 WDFWORKITEM입니다.
  • 개체의 핸들 형식은 WDFMEMORY 또는 WDFLOOKASIDE이고, 드라이버는 PoolType 매개 변수에 대해 PagedPool을 WdfMemoryCreate 또는 WdfLookasideListCreate로 지정했습니다.
작업 항목 개체가 명시적으로 삭제되거나 작업 항목의 부모 개체가 삭제되어 작업 항목의 EvtCleanupCallback 콜백 함수를 호출하기 전에 프레임워크는 작업 항목의 EvtWorkItem 콜백 함수의 모든 인스턴스가 반환될 때까지 기다립니다. 자세한 내용은 WdfWorkItemEnqueue를 참조하세요.

마찬가지로 타이머 개체가 명시적으로 삭제되거나 타이머의 부모 개체가 삭제되어 타이머의 EvtCleanupCallback 콜백 함수를 호출하기 전에 프레임워크는 타이머의 EvtTimerFunc 이벤트 콜백 함수의 모든 인스턴스가 반환될 때까지 기다립니다.

프레임워크 버전 1.9부터 wdfroletypes.h 헤더 파일에는 EvtCleanupCallback 콜백 함수에 대한 몇 가지 대체 개체 형식별 함수 형식이 포함되어 있습니다. 이러한 대체 형식은 확인 도구를 사용하여 드라이버가 콜백 함수를 제대로 사용하고 있는지 여부를 확인하는 데 도움이 될 수 있습니다. 다음 표를 사용하여 사용할 함수 유형을 결정합니다.

개체 유형 함수 유형
디바이스 개체 EVT_WDF_DEVICE_CONTEXT_CLEANUP
I/O 큐 개체 EVT_WDF_IO_QUEUE_CONTEXT_CLEANUP_CALLBACK
File 개체 EVT_WDF_FILE_CONTEXT_CLEANUP_CALLBACK
기타 모든 개체 EVT_WDF_OBJECT_CONTEXT_CLEANUP

요구 사항

요구 사항 값
대상 플랫폼 유니버설
최소 KMDF 버전 1.0
최소 UMDF 버전 2.0
머리글 wdfobject.h(Wdf.h 포함)
IRQL 설명 섹션을 참조하십시오.

추가 정보

EvtDestroyCallback

WDF_OBJECT_ATTRIBUTES

WdfObjectDereference

WdfObjectReference

WdfWorkItemFlush