FILTER_SYNCHRONOUS_OID_REQUEST函数 (ndis.h)

NDIS 调用筛选器驱动程序的 FilterSynchronousOidRequest 函数,在向基础微型端口驱动程序提供请求之前预览同步 OID 请求。

NDIS 6.81 及更高版本中支持此函数。

语法

NDIS_STATUS FILTER_SYNCHRONOUS_OID_REQUEST(
            NDIS_HANDLE      FilterModuleContext,
  [in, out] NDIS_OID_REQUEST *OidRequest,
  [out]     PVOID            *CallContext
);

参数

FilterModuleContext

此请求的目标筛选器模块的上下文区域的句柄。 筛选器驱动程序在 FilterAttach 函数中创建并初始化此上下文区域。

[in, out] OidRequest

指向指定所请求操作 的NDIS_OID_REQUEST 结构的指针。

[out] CallContext

筛选器驱动程序在其 FilterSynchronousOidRequestFilterSynchronousOidRequestComplete 处理程序之间共享状态的 PVOID 大小存储槽。 NDIS 保证这最初指向零值。 有关详细信息,请参阅备注部分。

返回值

此函数返回以下适当的NDIS_STATUS代码之一:

返回代码 说明
NDIS_STATUS_SUCCESS 允许 OID 请求继续传播到微型端口驱动程序。 筛选器驱动程序必须返回任何无法识别的 OID 类型的此状态代码。
NDIS_STATUS_ALREADY_COMPLETE 停止传播 OID 请求,而是将其返回到状态为NDIS_STATUS_SUCCESS的调用方。
  • NDIS_STATUS_BUFFER_TOO_SHORT
  • NDIS_STATUS_INVALID_LENGTH
  • NDIS_STATUS_INVALID_DATA
FilterDirectOidRequest 相同。
NDIS_STATUS_RESOURCES FilterDirectOidRequest 相同,但请注意,同步 OID 请求必须快速完成,因此筛选器驱动程序通常应避免分配资源。
NDIS_STATUS_NOT_SUPPORTED 筛选器驱动程序不能仅仅因为无法识别 OID 而返回此代码。 筛选器驱动程序只能在筛选器识别操作但出于某种原因而无法执行时返回此筛选器。

注解

FilterSynchronousOidRequest 是一个可选函数。 如果筛选器驱动程序不需要观察或修改发送到微型端口驱动程序的同步 OID 请求,则当筛选器驱动程序调用 NdisFRegisterFilterDriver 时,筛选器驱动程序应将此函数的入口点设置为 NULL

NDIS 调用筛选器驱动程序的 FilterSynchronousOidRequest 函数来处理过度分配驱动程序发起的同步 OID 请求。 筛选器驱动程序可以读取或修改 NDIS_OID_REQUEST 结构中的某些字段,如下所示:

字段 筛选器访问
标头 只读
RequestType 读取/写入
PortNumber 读取/写入
超时 不访问
RequestId 不访问
RequestHandle 读取/写入
DATA 读取/写入
NdisReserved 不访问
MiniportReserved 不访问
SourceReserved 不访问
SupportedRevision 读取/写入
Reserved1、Reserved2 不访问
SwitchId 读取/写入
VPortId 读取/写入
Flags 读取/写入

除了修改 NDIS_OID_REQUEST 结构外,筛选器驱动程序还可以使用 FilterSynchronousOidRequest 中的返回代码控制请求:

  • NDIS_STATUS_SUCCESS:OID 继续传播到微型端口驱动程序。
  • NDIS_STATUS_ALREADY_COMPLETE:OID 会立即完成回到过度的驱动程序,而无需先传播到微型端口驱动程序。 使用 NDIS_STATUS_SUCCESS向过度分配的驱动程序完成 OID 请求。
  • 任何其他状态代码:OID 会立即完成回到过度的驱动程序,而无需首先传播到微型端口驱动程序。 OID 请求已完成到过度分配的驱动程序,其中包含筛选器驱动程序返回的状态代码。

如果筛选器驱动程序还注册 FilterSynchronousOidRequestComplete 处理程序,NDIS 可确保在 FilterSynchronousOidRequestComplete 处理程序返回NDIS_STATUS_SUCCESS时才调用 FilterSynchronousOidRequestComplete 处理程序。

FilterSynchronousOidRequest 处理程序可以将任何 PVOID 大小的值写入 *CallContext,当 OID 请求完成时,相同的值将返回到筛选器驱动程序的 FilterSynchronousOidRequestComplete 处理程序。 筛选器驱动程序可以使用此功能在两个处理程序之间传递状态。 由于 FilterSynchronousOidRequestComplete 处理程序仅在 FilterSynchronousOidRequest 处理程序返回NDIS_STATUS_SUCCESS时才调用,因此在返回任何其他代码时,没有理由将值写入 *CallContext 。 同样,如果筛选器驱动程序未提供 FilterSynchronousOidRequestComplete 处理程序,则没有理由将值写入 *CallContext

筛选器驱动程序不得从 FilterSynchronousOidRequest 处理程序返回NDIS_STATUS_PENDING。 无法对同步 OID 请求进行笔划或取消。

筛选器驱动程序应从 FilterSynchronousOidRequest 处理程序快速返回,而无需阻止、等待或睡觉。 同步 OID 请求仅用于低延迟操作,筛选器驱动程序应努力在几毫秒内继续或完成这些请求。 NDIS 不会相互序列化同步 OID 请求、针对其他 OID 请求或 FilterPause。 筛选器驱动程序负责实现任何所需的同步。

NDIS 针对 FilterDetach 序列化同步 OID 请求:NDIS 保证在调用 FilterDetach 后不会激活同步 OID 请求。

筛选器驱动程序不得在同步 OID 请求上调用 NdisAllocateCloneOidRequestNdisCancelOidRequest 。 筛选器驱动程序不得在通过 FilterSynchronousOidRequest 处理程序收到的 OID 请求上调用 NdisFSynchronousOidRequest

如果筛选器驱动程序在其 FilterSynchronousOidRequest 处理程序中引发 IRQL,则必须在从 FilterSynchronousOidRequest 处理程序返回之前将 IRQL 还原到其初始级别。

要求

   
最低受支持的客户端 Windows 10 版本 1709
目标平台 Windows
标头 ndis.h (包括 Ndis.h)
IRQL <= DISPATCH_LEVEL

另请参阅

FilterSynchronousOidRequestComplete

NdisFSynchronousOidRequest

NDIS 6.80 中的同步 OID 请求接口