EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE 콜백 함수(wdfio.h)

  • 아티클

[KMDF 및 UMDF에 적용]

드라이버의 EvtIoCanceledOnQueue 이벤트 콜백 함수는 프레임워크가 I/O 큐에서 제거되었음을 드라이버에 알리는 I/O 요청을 완료해야 합니다.

구문

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE EvtWdfIoQueueIoCanceledOnQueue;

void EvtWdfIoQueueIoCanceledOnQueue(
  [in] WDFQUEUE Queue,
  [in] WDFREQUEST Request
)
{...}

매개 변수

[in] Queue

I/O 큐 개체에 대한 핸들입니다.

[in] Request

요청 개체에 대한 핸들입니다.

반환 값

없음

설명

드라이버는 WdfIoQueueCreate 메서드를 호출할 때 EvtIoCanceledOnQueue 콜백 함수를 등록합니다. WdfIoQueueCreate 호출에 대한 자세한 내용은 I/O 큐 만들기를 참조하세요.

드라이버가 I/O 큐에 대해 EvtIoCanceledOnQueue 콜백 함수를 등록하는 경우 프레임워크는 다음과 같은 상황에서 콜백 함수를 호출합니다.

프레임워크가 EvtIoCanceledOnQueue 콜백 함수를 호출한 후 드라이버는 요청 개체를 소유하며 EvtIoCanceledOnQueue 이상에서 적절한 상태 코드로 요청을 완료해야 합니다. 프레임워크가 EvtIoCanceledOnQueue를 호출하는 경우 요청은 여전히 I/O 큐와 연결되지만 드라이버는 요청을 다시 큐에 추가할 수 없습니다. 드라이버가 EvtIoCanceledOnQueue에서 요청을 완료하지 않더라도 요청 소유권은 드라이버와 함께 유지됩니다. EvtIoCanceledOnQueue가 반환된 후 드라이버가 요청을 완료하는 경우 드라이버에 이미 요청 소유권이 있으므로 WdfIoQueueFindRequest 및 WdfIoQueueRetrieveFoundRequest를 호출하여 요청 소유권을 다시 가져올 수 없습니다.

일반적으로 EvtIoCanceledOnQueue에서 드라이버는 STATUS_CANCELLED 완료 상태 I/O 요청을 완료합니다.

경우에 따라 드라이버가 정보를 기다리기 위해 I/O 요청을 수동 큐에 다시 큐에 추가했을 수 있습니다. 예를 들어 요청 처리기 중 하나에서 드라이버는 보류 중인 DMA 트랜잭션과 연결된 I/O 요청을 수동 큐에 배치할 수 있습니다. 이 경우 드라이버는 EvtIoCanceledOnQueue 콜백에서 DMA 트랜잭션을 취소하려고 시도합니다. 취소 작업의 결과에 따라 드라이버는 EvtIoCanceledOnQueue 이상에서 적절한 상태 사용하여 요청을 완료합니다.

프레임워크는 프레임워크가 드라이버에 전달한 적이 없는 I/O 요청에 대해 드라이버의 EvtIoCanceledOnQueue 콜백 함수를 호출하지 않습니다.

프레임워크는 드라이버가 I/O 큐에 대해 설정한 디스패치 메서드에 관계없이 I/O 요청이 취소되었음을 확인하는 즉시 EvtIoCanceledOnQueue 콜백 함수를 호출합니다. 따라서 프레임워크는 다음을 위해 EvtIoCanceledOnQueue 콜백 함수를 호출할 수 있습니다.

EvtIoCanceledOnQueue 콜백 함수에 대한 자세한 내용은 I/O 요청 취소를 참조하세요.

디바이스 또는 드라이버의 WDF_OBJECT_ATTRIBUTES 구조체의 ExecutionLevel 멤버가 WdfExecutionLevelPassive로 설정되지 않는 한 IRQL <= DISPATCH_LEVELEvtIoCanceledOnQueue 콜백 함수를 호출할 수 있습니다.

IRQL이 PASSIVE_LEVEL 경우 프레임워크는 중요한 지역 내에서 콜백 함수를 호출합니다.

예제

EvtIoCanceledOnQueue 콜백 함수를 정의하려면 먼저 정의 중인 콜백 함수의 형식을 식별하는 함수 선언을 제공해야 합니다. Windows는 드라이버에 대한 콜백 함수 형식 집합을 제공합니다. 콜백 함수 형식을 사용하여 함수를 선언하면 드라이버에 대한 코드 분석, SDV( 정적 드라이버 검증 도구 ) 및 기타 확인 도구에서 오류를 찾을 수 있으며 Windows 운영 체제용 드라이버를 작성하기 위한 요구 사항입니다.

EvtIoCanceledOnQueue 콜백 함수를 정의하려면 먼저 SDV 및 기타 확인 도구에 필요한 함수 선언을 제공해야 합니다. 다음 예제는 PCMCIA 스마트 카드 드라이버 샘플에서 가져옵니다.

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE PscrEvtIoCanceledOnQueue;

PCMCIA 스마트 카드 드라이버 샘플에서 드라이버는 수동 큐를 사용하여 보류 중인 스마트 카드 알림 요청을 저장합니다. 드라이버는 드라이버가 알림 필드를 지우고 요청을 완료하는 EvtIoCanceledOnQueue 콜백 함수를 제공합니다.

_Use_decl_annotations_
VOID
PscrEvtIoCanceledOnQueue(
    WDFQUEUE  Queue,
    WDFREQUEST  Request
    )

{
    PDEVICE_EXTENSION DeviceExtension;
    PSMARTCARD_EXTENSION smartcardExtension;

    DeviceExtension = GetDeviceExtension(WdfIoQueueGetDevice(Queue));
    smartcardExtension = (PSMARTCARD_EXTENSION) &DeviceExtension->SmartcardExtension;

    //KdPrint(("Cancelled on queue 0x%x\n", WdfRequestWdmGetIrp(Request)));

    InterlockedExchangePointer(
                             &(smartcardExtension->OsData->NotificationIrp),
                             NULL
                             );

    WdfRequestComplete(Request, STATUS_CANCELLED);
}

EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE 함수 형식은 Wdfio.h 헤더 파일에 정의되어 있습니다. 코드 분석 도구를 실행할 때 오류를 보다 정확하게 식별하려면 함수 정의에 Use_decl_annotations 주석을 추가해야 합니다. Use_decl_annotations 주석은 헤더 파일의 EVT_WDF_IO_QUEUE_IO_CANCELED_ON_QUEUE 함수 형식에 적용되는 주석이 사용되도록 합니다. 함수 선언에 대한 요구 사항에 대한 자세한 내용은 KMDF 드라이버에 함수 역할 형식을 사용하여 함수 선언을 참조하세요. Use_decl_annotations 대한 자세한 내용은 함수 동작 주석 지정을 참조하세요.

요구 사항

요구 사항 값
대상 플랫폼 유니버설
최소 KMDF 버전 1.0
최소 UMDF 버전 2.0
머리글 wdfio.h(Wdf.h 포함)
IRQL <= DISPATCH_LEVEL(주의 섹션 참조)

추가 정보

WdfIoQueueCreate

WdfRequestForwardToIoQueue