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 注册可选服务,并可以分配其他驱动程序资源。 若要注册可选的 MiniportXxxProtocolXxxFilterXxx 函数,驱动程序会调用 NdisSetOptionalHandlers 函数。 驱动程序从 NdisSetOptionalHandlersNdisHandle 参数传递 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 返回后随时调用驱动程序的其他 MiniportXxxProtocolXxxFilterXxx 函数。 驱动程序应准备好在其初始化函数中回调: (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