SET_OPTIONS回调函数 (ndis.h)
NDIS 调用驱动程序的 XxxSetOptions 函数，以允许驱动程序注册可选服务。 此函数定义为 微型端口驱动程序的 MiniportSetOptions 、协议驱动程序的 ProtocolSetOptions 或筛选器驱动程序的 FilterSetOptions 。
语法
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 返回以下状态值之一：
| 返回代码 | 说明 |
|---|---|
|
XxxSetOptions 已成功注册驱动程序的可选服务和资源。 |
|
XxxSetOptions 无法分配驱动程序所需的资源。 |
|
驱动程序注册选项的尝试失败。 通常，此类错误状态是从 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);例如，若要定义名为“ 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 |