IWDFIoRequest：：UnmarkCancelable 方法 (wudfddi.h)

项目
08/08/2023

[警告： UMDF 2 是最新版本的 UMDF，并取代 UMDF 1。所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。不会向 UMDF 1 添加任何新功能，并且较新版本的 Windows 10 上对 UMDF 1 的支持有限。通用 Windows 驱动程序必须使用 UMDF 2。有关详细信息，请参阅使用 UMDF 入门。]

UnmarkCancelable 方法禁用取消 I/O 请求。

语法

HRESULT UnmarkCancelable();

返回值

UnmarkCancelable 返回以下值之一：

返回代码	说明
S_OK	UnmarkCancelable 禁用了以前通过调用 IWDFIoRequest：：MarkCancelable 方法注册的 IRequestCallbackCancel：：OnCancel 方法。
HRESULT_FROM_WIN32 (ERROR_OPERATION_ABORTED)	请求当前正在取消。

注解

如果驱动程序以前调用 IWDFIoRequest：：MarkCancelable 来启用请求取消，驱动程序可以调用 IWDFIoRequest：：UnmarkCancelable 来禁用取消 I/O 请求。

如果驱动程序以前调用 MarkCancelable，则驱动程序必须在调用其 IRequestCallbackCancel：：OnCancel 回调方法之外调用 IWDFIoRequest：：Complete 之前调用 UnmarkCancelable。

但是，在 OnCancel 调用 Complete 后，驱动程序不得调用 UnmarkCancelable。

如果 UnmarkCancelable 返回HRESULT_FROM_WIN32 (ERROR_OPERATION_ABORTED) ，然后 OnCancel 完成请求，则驱动程序随后不得使用请求对象。

如果 UnmarkCancelable 返回HRESULT_FROM_WIN32 (ERROR_OPERATION_ABORTED) ，则驱动程序在框架调用 OnCancel 之前不得完成请求。否则，框架可能会使用无效请求调用驱动程序的 OnCancel 。

示例

下面的代码示例演示了驱动程序如何在调用其 IRequestCallbackCancel：：OnCancel 方法之外调用 IWDFIoRequest：：UnmarkCancelable 之前调用 IWDFIoRequest：：Complete。

该示例还演示如何使用 OnCancel 加速请求的完成。在这种情况下， OnCancel 回调并不总是完成/取消指定的请求。

//
// The driver calls CompletePendingRequest when it is ready to complete the request with error/success.
// You must previously initialize m_CompleteCancelledRequest to zero.
//
VOID
CompletePendingRequest( 
    HRESULT hr,
    DWORD   information
    )
{
    LONG shouldComplete = 1;

    if (m_PendingRequest) {
        HRESULT hrUnmark = m_PendingRequest->UnmarkCancelable();
        if (HRESULT_FROM_WIN32(ERROR_OPERATION_ABORTED) == hrUnmark) { 
            //
            // We are racing with OnCancel.  We cannot complete m_PendingRequest until after
            // both IWDFIoRequest::Complete and OnCancel have finished with it. To
            // guarantee this, the last to run (either OnCancel or CompletePendingRequest) will
            // be the one to complete the request. 
            //
            shouldComplete = InterlockedExchange(&m_CompleteCancelledRequest, 1);
        }

        // 
        // If we were first to set m_CompleteCancelledRequest to 1, then drop out here
        // and rely on OnCancel to complete the request.
        // 

        if (1 == shouldComplete) { 
            IWDFIoRequest *FxRequest = (IWDFIoRequest*)InterlockedExchangePointer((PVOID *)&m_PendingRequest, NULL);
            InterlockedExchange(&m_CompleteCancelledRequest, 0);
            FxRequest->SetInformation(information);
            FxRequest->Complete(hr);
        }
   }
}

//
// The framework calls OnCancel when an application cancels a pending I/O request. 
//
VOID
STDMETHODCALLTYPE
OnCancel(
    _In_ IWDFIoRequest *pWdfRequest
    )
{
    if (m_PendingRequest != pWdfRequest) {
        TraceEvents(TRACE_LEVEL_ERROR, 
                    YOURDEVICE_TRACE_DEVICE, 
                    "%!FUNC! Cancelled request does not match pending request.");
    }

    // 
    // Add your code to speed up the completion of the request.  Maybe you need to reset the hardware or 
    // do some other domain-specific task.
    //

    //
    // Since we only complete the request if we were the last to run (see comment in
    // CompletePendingRequest), if we are *not* the last to run we rely on CompletePendingRequest 
    // to complete this request.
    //

    LONG shouldComplete = InterlockedExchange(&m_CompleteCancelledRequest, 1);
    if (1 == shouldComplete) { 
        //
        // Enter this block only if we are the last to run.
        // Otherwise, rely on CompletePendingRequest to complete this request.
        //
        (void*) InterlockedExchangePointer((PVOID *)&m_PendingRequest, NULL);
        InterlockedExchange(&m_CompleteCancelledRequest, 0);
        pWdfRequest->Complete(HRESULT_FROM_WIN32(ERROR_CANCELLED));
     } 
 
}

在下一个代码示例中，驱动程序将 I/O 请求存储在驱动程序实现的名为 MyQueue 的队列对象中。驱动程序的 MyQueue 接口实现一些基本方法来操作队列，例如 IsEmpty、 RemoveHead、 Cleanup、 GetFirstNodePosition、 GetAt 和 RemoveAt。

驱动程序还定义了 一个 CommandInformation 结构，用于保存 来自 MyQueue 的单个 I/O 请求。

MyQueue：:D eQueue 方法从队列中删除 I/O 请求，调用 UnmarkCancelable 以禁用取消请求，然后返回处理请求。


void MyQueue::DeQueue(__out CommandInformation* CommandInfo)
{
    CComCritSecLock<CComAutoCriticalSection> scopeLock(m_CriticalSection);

    if (NULL != CommandInfo)
    {
        for (;;) 
        {
            if (TRUE == IsEmpty()) 
            {
                ZeroMemory(CommandInfo, sizeof(CommandInformation));
                break;
            }
            //
            // If queue is not empty, retrieve the first element from the list.
            //
            *CommandInfo = RemoveHead(); 
            if (HRESULT_FROM_WIN32(ERROR_OPERATION_ABORTED) != (CommandInfo->Request)->UnmarkCancelable())
            {
                //
                // UnmarkCancelable was successful.
                // Ownership of this request has been transferred back to this driver.
                //
                break;
            }
            else
            {
                //
                // If UMDF returns HRESULT_FROM_WIN32(ERROR_OPERATION_ABORTED) for UnmarkCancelable,
                // that means UMDF is planning on cancelling the request. However, since this call
                // popped the request off our internal queue, let’s cleanup the generic command object
                // and let OnCancel complete the request.               
                //                
                CommandInfo->Cleanup();
            }
        }    
    }
}

//
// The framework calls OnCancel when an application cancels a dispatched I/O request.
//
void MyQueue::OnCancel(__in IWDFIoRequest* Request)
{
    {
        CComCritSecLock<CComAutoCriticalSection> scopeLock(m_CriticalSection);

        POSITION pos = GetFirstNodePosition();

        while (NULL != pos)
        {
            //
            // Find the request and remove it from our driver-implemented queue.
            //
            CommandInformation commandInfo = GetAt(pos);
            if (Request == commandInfo.Request)
            {
                RemoveAt(pos);
                commandInfo.Cleanup();
                break;
            }

            GetNext(pos);
        }
    }

    //
    // Cancel/Complete the request.
    //
    // The request might not be in the queue when the framework calls OnCancel. 
    // This occurs if DeQueue receives HRESULT_FROM_WIN32(ERROR_OPERATION_ABORTED)
    // when it calls UnmarkCancelable for the request. In this case, as soon as
    // DeQueue releases the scopeLock, the framework calls OnCancel to cancel the request.
    //
    Request->Complete(HRESULT_FROM_WIN32(ERROR_CANCELLED));
}

另请参阅 WdfRequestUnmarkCancelable 上的代码示例。虽然为 KMDF 驱动程序编写，但此示例演示了如何使用框架的自动同步来管理取消回调与另一个调用 Unmark 例程的线程之间的同步。

要求

要求	值
结束支持	在 UMDF 2.0 及更高版本中不可用。
目标平台	桌面
最低 UMDF 版本	1.5
标头	wudfddi.h (包括 Wudfddi.h)
DLL	WUDFx.dll

另请参阅

IRequestCallbackCancel：：OnCancel

IWDFIoRequest

IWDFIoRequest：：Complete

IWDFIoRequest：：MarkCancelable

IWDFIoRequest：：UnmarkCancelable 方法 (wudfddi.h)

语法

返回值

注解

示例

要求

另请参阅

反馈

反馈

其他资源