IWDFIoRequest::MarkCancelable method

The MarkCancelable method enables the canceling of the I/O request.

Syntax


void  MarkCancelable(
  [in] IRequestCallbackCancel *pCancelCallback
);

Parameters

pCancelCallback [in]

A pointer to the IRequestCallbackCancel interface whose method the framework calls after the I/O request is canceled.

Return value

None

Remarks

After a driver receives an I/O request as input to an IQueueCallbackRead::OnRead, IQueueCallbackWrite::OnWrite, or IQueueCallbackDeviceIoControl::OnDeviceIoControl event callback function, the driver can call the MarkCancelable method to enable canceling of the request. Later, the driver can call the IWDFIoRequest::UnmarkCancelable method to disable canceling of the request.

Before a driver calls MarkCancelable, the driver must implement the IRequestCallbackCancel::OnCancel method.

The User Mode Driver Framework (UMDF) allows only one IRequestCallbackCancel::OnCancel method per queue. Therefore, when a driver calls MarkCancelable for requests that are associated with a particular queue to enable the framework to cancel those requests, the driver must pass a pointer to the IRequestCallbackCancel interface for the same request-callback object. Later, to cancel each request, the framework passes a pointer to the IWDFIoRequest interface for the request in a call to this request-callback object's IRequestCallbackCancel::OnCancel method.

The driver must call IWDFIoRequest::Complete, either from the IRequestCallbackCancel::OnCancel method or from its regular I/O completion path.

After a driver calls MarkCancelable to enable canceling, the request remains cancelable while the driver has possession of the request object, unless the driver calls UnmarkCancelable to disable canceling.

If the driver calls the IWDFIoRequest::ForwardToIoQueue method to forward the request to a different queue, the following rules apply:

  • Canceling of I/O requests cannot be enabled when the driver forwards the requests to a different queue.

    Typically, the driver should not call MarkCancelable to enable canceling a request before calling IWDFIoRequest::ForwardToIoQueue. Alternatively, the driver can make the request cancelable. However, the driver must then call UnmarkCancelable to disable canceling the request before calling IWDFIoRequest::ForwardToIoQueue.

  • While the request is in a second queue, the framework owns it and can cancel it without notifying the driver.

  • After the framework dequeues the request from the second queue and delivers the request to the driver, the driver can call MarkCancelable to enable canceling.

Examples

The following code example sets up a request so that the framework can cancel it.


    //
    // The QueryInteraface should not fail.
    //
    (VOID)this->QueryInterface(_uuidof(IRequestCallbackCancel),
                               (PVOID *)&cancelCallback);

    pWdfRequest->MarkCancelable(cancelCallback);

Requirements

Target platform

Desktop

End of support

Unavailable in UMDF 2.0 and later.

Minimum UMDF version

1.5

Header

Wudfddi.h (include Wudfddi.h)

DLL

WUDFx.dll

See also

IWDFIoRequest
IQueueCallbackDeviceIoControl::OnDeviceIoControl
IQueueCallbackRead::OnRead
IQueueCallbackWrite::OnWrite
IRequestCallbackCancel
IRequestCallbackCancel::OnCancel
IWDFIoRequest::Complete
IWDFIoRequest::ForwardToIoQueue
IWDFIoRequest::UnmarkCancelable

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft