FILTER_SYNCHRONOUS_OID_REQUEST 函数 (ndis.h)

项目
08/07/2023

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

筛选器驱动程序的 PVOID 大小的存储槽，用于在其 FilterSynchronousOidRequest 和 FilterSynchronousOidRequestComplete 处理程序之间共享状态。 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 保证仅当 FilterSynchronousOidRequest 处理程序返回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 请求或 FilterPause 序列化同步 OID 请求。筛选器驱动程序负责实现任何所需的同步。

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

筛选器驱动程序不得对同步 OID 请求调用 NdisAllocateCloneOidRequest 或 NdisCancelOidRequest 。筛选器驱动程序不得对通过 FilterSynchronousOidRequest 处理程序接收的 OID 请求调用 NdisFSynchronousOidRequest 。

如果筛选器驱动程序在其 FilterSynchronousOidRequest 处理程序中引发 IRQL，则必须先将 IRQL 还原到其初始级别，然后才能从其 FilterSynchronousOidRequest 处理程序返回。