通过

WdfIoQueueAssignForwardProgressPolicy 函数 (wdfio.h)

  • 项目

[仅适用于 KMDF]

WdfIoQueueAssignForwardProgressPolicy 方法使框架能够保证指定 I/O 队列的前进进度。

语法

NTSTATUS WdfIoQueueAssignForwardProgressPolicy(
  [in] WDFQUEUE                              Queue,
  [in] PWDF_IO_QUEUE_FORWARD_PROGRESS_POLICY ForwardProgressPolicy
);

参数

[in] Queue

框架队列对象的句柄。

[in] ForwardProgressPolicy

指向驱动程序分配 的WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY 结构的指针。

返回值

如果操作成功，WdfIoQueueAssignForwardProgressPolicy 将返回STATUS_SUCCESS。 否则，此方法可能会返回以下值之一：

返回代码 说明
STATUS_INVALID_PARAMETER
 输入参数无效。
STATUS_INFO_LENGTH_MISMATCH
 WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY 结构的大小不正确。
STATUS_INSUFFICIENT_RESOURCES
 可用内存量太低。
 

此方法还可能返回其他 NTSTATUS 值。 此外，如果驱动程序的 EvtIoAllocateResourcesForReservedRequest 回调函数返回错误状态值， 则 WdfIoQueueAssignForwardProgressPolicy 将返回该值。

如果驱动程序提供无效的对象句柄，则会发生 bug 检查。

注解

WdfIoQueueAssignForwardProgressPolicy 方法创建框架为低内存情况保留的请求对象，并注册框架调用以处理低内存情况的回调函数。

在 KMDF 版本 1.9 中， Queue 参数表示的 I/O 队列必须是设备的默认 I/O 队列，或者驱动程序已为其调用 WdfDeviceConfigureRequestDispatching 的队列。 驱动程序在调用 WdfDeviceConfigureRequestDispatching 后，可以随时调用 WdfIoQueueAssignForwardProgressPolicy。

在 KMDF 版本 1.11 及更高版本中， Queue 参数表示的 I/O 队列可以是直接从框架接收请求的任何队列。 例如，驱动程序可以指定一个队列，它将 动态转发 IRP。

在 WdfIoQueueAssignForwardProgressPolicy 返回之前，框架执行以下操作：

驱动程序调用 WdfIoQueueAssignForwardProgressPolicy 来创建保留请求对象后，框架会在尝试创建新请求对象失败时使用这些保留对象。 (通常，此类故障是由内存不足的情况引起的。)

仅当框架删除其所属的框架队列对象时，框架才会删除其保留的请求对象。 如果驱动程序调用 WdfDeviceInitSetRequestAttributes 并为其请求对象指定 EvtCleanupCallback 或 EvtDestroyCallback 回调函数，则框架在删除对象时为其保留的请求对象调用这些回调函数。

有关 WdfIoQueueAssignForwardProgressPolicy 方法以及如何使用框架的保证向前进度功能的详细信息，请参阅 保证 I/O 操作的向前进度。

示例

此代码示例将之前创建的 I/O 队列配置为接收写入请求，然后为队列启用有保证的向前进度。

#define MAX_RESERVED_REQUESTS 10

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY queueForwardProgressPolicy;
WDFQUEUE writeQueue;
NTSTATUS status = STATUS_SUCCESS;
...
status = WdfDeviceConfigureRequestDispatching(
             device,
             writeQueue,
             WdfRequestTypeWrite
             );
if(!NT_SUCCESS(status)) {
    return status;
}
WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY_DEFAULT_INIT(
    &queueForwardProgressPolicy,
    MAX_RESERVED_REQUESTS
    );
status = WdfIoQueueAssignForwardProgressPolicy(
             writeQueue,
             &queueForwardProgressPolicy
             );
if(!NT_SUCCESS(status)) {
    return status;
}

要求

要求 值
目标平台 通用
最低 KMDF 版本 1.9
标头 wdfio.h (包括 Wdf.h)
Library Wdf01000.sys (请参阅框架库版本控制.)
IRQL PASSIVE_LEVEL
DDI 符合性规则 DriverCreate (kmdf)

另请参阅

EvtIoAllocateResourcesForReservedRequest

WDF_IO_QUEUE_FORWARD_PROGRESS_POLICY

WdfDeviceConfigureRequestDispatching