WdfRequestMarkCancelable 함수(wdfrequest.h)

아티클
02/07/2025

[KMDF 및 UMDF에 적용]

WdfRequestMarkCancelable 메서드를 사용하면 지정된 I/O 요청을 취소할 수 있습니다.

통사론

void WdfRequestMarkCancelable(
  [in] WDFREQUEST             Request,
  [in] PFN_WDF_REQUEST_CANCEL EvtRequestCancel
);

매개 변수

[in] Request

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

[in] EvtRequestCancel

드라이버 정의 EvtRequestCancel에 대한 포인터는 I/O 요청을 취소하는 경우 프레임워크가 호출하는 콜백 함수를.

반환 값

없음

발언

드라이버에서 잘못된 개체 핸들을 제공하면 버그 검사가 수행됩니다.

드라이버가 프레임워크에서 I/O 요청 받은 후 드라이버는 WdfRequestMarkCancelable 호출하거나 KMDF 버전 1.9부터 WdfRequestMarkCancelableEx 호출하여 요청을 취소할 수 있도록 할 수 있습니다.

WdfRequestMarkCancelable호출할 때 드라이버는 EvtRequestCancel 콜백 함수를 지정해야 합니다. I/O 관리자 또는 다른 드라이버가 I/O 요청을 취소하려고 하는 경우 프레임워크는 콜백 함수를 호출합니다.

WdfRequestMarkCancelable과 WdfRequestMarkCancelableEx 중에서 선택

드라이버가 프레임워크의 자동 동기화사용하는 경우 드라이버는 WdfRequestMarkCancelable 또는 WdfRequestMarkCancelableEx호출할 수 있습니다.

드라이버가 자동 동기화를 사용하지 않는 경우 다음과 같은 이유로 WdfRequestMarkCancelable 대신 WdfRequestMarkCancelableEx 호출해야 합니다.

지정된 요청이 이미 취소된 경우 WdfRequestMarkCancelable 반환하기 전에 드라이버의 EvtRequestCancel 콜백 함수를 호출합니다. 드라이버가 WdfRequestMarkCancelable 호출하기 전에 스핀 잠금을 획득하고 EvtRequestCancel내에서 동일한 스핀 잠금을 획득하려고 하면 동일한 스레드가 동일한 스핀 잠금을 두 번 획득하여 교착 상태가 발생합니다.
그러나 WdfRequestMarkCancelableEx EvtRequestCancel 호출하지 않으므로 이 시나리오는 발생하지 않습니다. 요청이 이미 취소된 경우 WdfRequestMarkCancelableExSTATUS_CANCELLED반환합니다. 드라이버가 WdfRequestMarkCancelableEx 호출하기 전에 스핀 잠금(IRQL을 DISPATCH_LEVEL 설정)을 획득하고 WdfRequestMarkCancelableEx 반환한 후 스핀 잠금(IRQL을 PASSIVE_LEVEL 설정)을 해제하는 경우 EvtRequestCancel 콜백 함수는 스핀 잠금이 해제되기 전에 호출되지 않습니다. 따라서 EvtRequestCancel 콜백 함수가 동일한 스핀 잠금을 사용하는 경우에도 교착 상태가 발생하지 않습니다.

취소를 사용하도록 설정한 후 요청 처리

드라이버가 WdfRequestMarkCancelable 호출하여 취소를 사용하도록 설정한 후에는 드라이버가 WdfRequestUnmarkCancelable호출하지 않는 한 드라이버 요청 개체를 소유하는 동안 요청을 취소할 수 있습니다.

드라이버가 WdfRequestMarkCancelable호출하고 드라이버의 EvtRequestCancel 콜백 함수가 실행되지 않은 경우 WdfRequestCompleteEvtRequestCancel 콜백 함수 외부에서 WdfRequestComplete 호출하기 전에 드라이버는 WdfRequestUnmarkCancelable 호출해야 합니다.

드라이버가 WdfRequestForwardToIoQueue 호출하여 요청을 다른 큐로 전달하는 경우 다음 규칙이 적용됩니다.

드라이버가 다른 큐에 전달하는 경우 I/O 요청을 취소할 수 없습니다.
일반적으로 드라이버는 WdfRequestForwardToIoQueue호출하기 전에 요청을 취소할 수 있도록 WdfRequestMarkCancelable 호출해서는 안 됩니다. 드라이버가 요청을 취소할 수 있도록 하는 경우 WdfRequestForwardToIoQueue호출하기 전에 취소를 사용하지 않도록 설정하려면 WdfRequestUnmarkCancelable 호출해야 합니다.
요청이 두 번째 큐에 있는 동안 프레임워크는 요청을 소유하고 드라이버에 알리지 않고 취소할 수 있습니다.
드라이버에 취소 알림이 필요한 경우(WdfRequestForwardToIoQueue호출하기 전에 할당된 리소스의 할당을 취소할 수 있도록) 드라이버는 EvtIoCanceledOnQueue 콜백 함수를 등록해야 하며 요청 관련 컨텍스트 메모리를 사용하여 요청의 리소스에 대한 정보를 저장해야 합니다.
프레임워크가 두 번째 큐에서 요청을 큐에서 제거하고 드라이버에 전달한 후 드라이버는 WdfRequestMarkCancelable 호출하여 취소를 사용하도록 설정할 수 있습니다.

WdfRequestMarkCancelable 대한 자세한 내용은 I/O 요청 취소참조하세요.

예제

다음 코드 예제에서는 두 콜백 함수의 일부를 보여 줍니다.

요청별 작업(예: I/O 대상에 보낼 하위 쿼리 만들기)을 수행하는 EvtIoRead 콜백 함수를 사용하면 수신된 I/O 요청을 취소할 수 있습니다.
I/O 요청을 취소하는 EvtRequestCancel 콜백 함수입니다.

드라이버는 프레임워크의 자동 동기화사용해야 합니다.

VOID
MyEvtIoRead(
    IN WDFQUEUE  Queue,
    IN WDFREQUEST  Request,
    IN size_t  Length
    )
{
...
    // Perform request-specific work here
    // (such as creating subrequests 
    // to send to an I/O target). 
...
    WdfRequestMarkCancelable(
                             Request,
                             MyEvtRequestCancel
                             );
    }
...
}
VOID
MyEvtRequestCancel(
    IN WDFREQUEST  Request
    )
{
    // Remove request-specific work here, because
    // we don't want the work to be done if the
    // request was canceled.

    WdfRequestComplete(
                       Request,
                       STATUS_CANCELLED
                       );
}

요구 사항

요구	값
대상 플랫폼	보편적
최소 KMDF 버전	1.0
최소 UMDF 버전	2.0
헤더	wdfrequest.h(Wdf.h 포함)
라이브러리	Wdf01000.sys(KMDF); WUDFx02000.dll(UMDF)
IRQL	<=DISPATCH_LEVEL
DDI 규정 준수 규칙	DeferredRequestCompleted(kmdf), DriverCreate(kmdf), EvtIoStopCancel(kmdf), InvalidReqAccess() kmdf), InvalidReqAccessLocal(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), MarkCancOnCancReqLocal(kmdf), ReqIsCancOnCancReq(kmdf), ReqMarkCancelable Send(kmdf), ReqNotCanceledLocal(kmdf), RequestCompleted(kmdf), RequestCompletedLocal(kmdf)