SET_OPTIONS回调函数 (ndis.h)

  • 项目

NDIS 调用驱动程序的 XxxSetOptions 函数，以允许驱动程序注册可选服务。 此函数定义为 微型端口驱动程序的 MiniportSetOptions 、协议驱动程序的 ProtocolSetOptions 或筛选器驱动程序的 FilterSetOptions 。

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

语法

SET_OPTIONS SetOptions;

NDIS_STATUS SetOptions(
  [in] NDIS_HANDLE NdisDriverHandle,
  [in] NDIS_HANDLE DriverContext
)
{...}

参数

[in] NdisDriverHandle

标识驱动程序的句柄。 当从驱动程序注册函数返回时，NDIS 会将此句柄返回到驱动程序， (用于微型端口驱动程序的 NdisMRegisterMiniportDriver 、用于协议驱动程序的 NdisRegisterProtocolDriver 和用于筛选器驱动程序的 NdisFRegisterFilterDriver) 。

[in] DriverContext

驱动程序传递给 NdisRegisterXxxDriver 的句柄，用于标识驱动程序上下文区域，其中 Xxx 是微型端口、协议或筛选器) (驱动程序的类型。

返回值

XxxSetOptions 返回以下状态值之一：

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

注解

XxxSetOptions 是一个可选函数。 NDIS 在驱动程序调用 的上下文中调用 XxxSetOptions NdisRegisterXxxDriver 函数，其中 Xxx 是微型端口、协议或筛选器) (驱动程序的类型。

XxxSetOptions 注册可选服务并可以分配其他驱动程序资源。 若要注册可选的 MiniportXxx、 ProtocolXxx 或 FilterXxx 函数，驱动程序会调用 NdisSetOptionalHandlers 函数。 驱动程序从 NdisSetOptionalHandlers 的 NdisHandle 参数传递 NdisDriverHandle 参数的句柄，并在 OptionalHandlers 参数中传递特征结构。

微型端口驱动程序可以应用于以下特征结构中定义的可选服务：

NDIS_MINIPORT_CO_CHARACTERISTICS
NDIS_MINIPORT_PNP_CHARACTERISTICS
NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS
NDIS_PROVIDER_CHIMNEY_OFFLOAD_GENERIC_CHARACTERISTICS (请参阅 NDIS 6.0 TCP 烟囱卸载文档)
NDIS_PROVIDER_CHIMNEY_OFFLOAD_TCP_CHARACTERISTICS (请参阅 NDIS 6.0 TCP 烟囱卸载文档)

协议驱动程序可以应用于在以下特征结构中定义的可选服务：

NDIS_PROTOCOL_CO_CHARACTERISTICS
NDIS_CO_CLIENT_OPTIONAL_HANDLERS
NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS

当前 Windows 版本中没有可选的筛选器驱动程序服务。

NDIS 可以在 XxxSetOptions 返回后随时调用驱动程序的其他 MiniportXxx、ProtocolXxx 或 FilterXxx 函数。 驱动程序应准备好在其初始化函数中回调： (MiniportInitializeEx 用于微型端口驱动程序， ProtocolBindAdapterEx 用于协议驱动程序， FilterAttach 用于筛选器驱动程序) 。

对于微型端口驱动程序，在 NDIS 调用 MiniportInitializeEx 之前，微型端口适配器处于“已停止”状态。 对于协议驱动程序，在 NDIS 调用 ProtocolBindAdapterEx 之前，协议绑定处于“未绑定”状态。 对于筛选器驱动程序，筛选器模块在 NDIS 调用 FilterAttach 之前处于“分离”状态。

如果尝试分配资源或服务失败， XxxSetOptions 应在返回状态为NDIS_STATUS_SUCCESS以外的控件之前撤消所有成功的分配。

微型端口和筛选器驱动程序的 XxxDriverUnload 应撤消在 XxxSetOptions 中执行的所有操作

NDIS 在 IRQL = PASSIVE_LEVEL 调用 XxxSetOptions 。

示例

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

在 Ndis.h 头文件中，SET_OPTIONS回调函数进一步定义如下：

typedef SET_OPTIONS (*SET_OPTIONS_HANDLER);
typedef SET_OPTIONS (MINIPORT_SET_OPTIONS);
typedef SET_OPTIONS (PROTOCOL_SET_OPTIONS);
typedef SET_OPTIONS (FILTER_SET_OPTIONS);
这使所有 NDIS 驱动程序都可以使用相同的语法实现其 XxxSetOptions 回调函数。 微型端口驱动程序使用 MINIPORT_SET_OPTIONS 类型，协议驱动程序使用 PROTOCOL_SET_OPTIONS 类型，筛选器驱动程序使用 FILTER_SET_OPTIONS 类型。

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

MINIPORT_SET_OPTIONS MySetOptions;

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

_Use_decl_annotations_
NDIS_STATUS
 MySetOptions(
    NDIS_HANDLE  NdisDriverHandle,
    NDIS_HANDLE  DriverContext
    )
  {...}

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

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

要求

要求 值
最低受支持的客户端 在 NDIS 6.0 及更高版本中受支持。
目标平台 Windows
标头 ndis.h (包括 Ndis.h)
IRQL PASSIVE_LEVEL

另请参阅

NDIS_CO_CALL_MANAGER_OPTIONAL_HANDLERS NDIS_CO_CLIENT_OPTIONAL_HANDLERS NDIS_PROTOCOL_CO_CHARACTERISTICS

NdisOpenAdapterEx

NdisRegisterProtocolDriver

NdisSetOptionalHandlers

ProtocolBindAdapterEx