FILTER_SET_MODULE_OPTIONS回调函数 (ndis.h)

项目
03/05/2024

FilterSetModuleOptions 函数更改与指定筛选器模块关联的可选服务集。

注意必须使用 FILTER_SET_MODULE_OPTIONS 类型声明函数。有关详细信息，请参阅以下示例部分。

语法

FILTER_SET_MODULE_OPTIONS FilterSetModuleOptions;

NDIS_STATUS FilterSetModuleOptions(
  [in] NDIS_HANDLE FilterModuleContext
)
{...}

参数

[in] FilterModuleContext

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

返回值

FilterSetModuleOptions 返回以下状态值之一：

返回代码	说明
NDIS_STATUS_SUCCESS	FilterSetModuleOptions 已成功注册筛选器模块的可选服务和资源。
NDIS_STATUS_RESOURCES	FilterSetModuleOptions 无法分配筛选器模块所需的资源。
NDIS_STATUS_ XXX 或 NTSTATUS_ XXX	筛选器驱动程序注册选项的尝试失败。通常，此类错误状态是从 NdisXxx 函数或内核模式支持例程传播的。

注解

如果定义了 FilterSetModuleOptions ，则 NDIS 会先调用 FilterSetModuleOptions ，然后再调用 FilterRestart 函数来启动筛选器模块。

筛选器驱动程序指定它传递给的 NDIS_FILTER_DRIVER_CHARACTERISTICS 结构中可更改的筛选器模块选项的默认值驱动程序初始化期间的 NdisFRegisterFilterDriver 函数。

若要在运行时更改特定筛选器模块的选项，筛选器驱动程序还必须在中为 FilterSetModuleOptions 指定入口点 NDIS_FILTER_DRIVER_CHARACTERISTICS 结构。

若要指定应更改的选项， FilterSetModuleOptions 定义特征结构并调用 NdisSetOptionalHandlers 函数。筛选器驱动程序不得从其他线程调用 NdisSetOptionalHandlers 。

可从 FilterSetModuleOptions 指定的可能特征结构包括：

NDIS_FILTER_PARTIAL_CHARACTERISTICS NDIS_CLIENT_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS NDIS_CLIENT_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS

有关最后四个结构的信息，请参阅 NDIS 6.0 TCP 烟囱卸载文档。

对于每个筛选器模块，每个特征结构中指定的选项可能不同。

当 NDIS 调用 FilterDetach 函数时，筛选器驱动程序应撤消 FilterSetModuleOptions 中执行的所有操作。

NDIS 在 IRQL = PASSIVE_LEVEL调用 FilterSetModuleOptions 。

示例

若要定义 FilterSetModuleOptions 函数，必须首先提供一个函数声明来标识要定义的函数类型。 Windows 为驱动程序提供了一组函数类型。使用函数类型声明函数可帮助驱动程序的代码分析、静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，并且这是为 Windows 操作系统编写驱动程序的要求。

例如，若要定义名为“ MySetModuleOptions ”的 FilterSetModuleOptions 函数，请使用 FILTER_SET_MODULE_OPTIONS 类型，如以下代码示例所示：

FILTER_SET_MODULE_OPTIONS MySetModuleOptions;

然后，按如下所示实现函数：

_Use_decl_annotations_
NDIS_STATUS
 MySetModuleOptions(
    NDIS_HANDLE  FilterModuleContext
    )
  {...}

FILTER_SET_MODULE_OPTIONS函数类型在 Ndis.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 Use_decl_annotations 注释添加到函数定义。 Use_decl_annotations批注可确保使用应用于头文件中FILTER_SET_MODULE_OPTIONS函数类型的注释。有关函数声明要求的详细信息，请参阅使用 NDIS 驱动程序的函数角色类型声明函数。

有关 Use_decl_annotations的信息，请参阅批注函数行为。