IWDFIoRequest：：UnmarkCancelable 方法 (wudfddi.h)
[警告： UMDF 2 是最新版本的 UMDF，并取代 UMDF 1。 所有新的 UMDF 驱动程序都应使用 UMDF 2 编写。 不会向 UMDF 1 添加任何新功能，并且较新版本的 Windows 10 上对 UMDF 1 的支持有限。 通用 Windows 驱动程序必须使用 UMDF 2。 有关详细信息，请参阅使用 UMDF 入门。]
UnmarkCancelable 方法禁用取消 I/O 请求。
语法
HRESULT UnmarkCancelable();
返回值
UnmarkCancelable 返回以下值之一：
| 返回代码 | 说明 |
|---|---|
|
UnmarkCancelable 禁用了以前通过调用 IWDFIoRequest：：MarkCancelable 方法注册的 IRequestCallbackCancel：：OnCancel 方法。 |
|
请求当前正在取消。 |
注解
如果驱动程序以前调用 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 |