PROTOCOL_UNBIND_ADAPTER_EX回调函数 (ndis.h)

项目
08/07/2023

NDIS 调用协议驱动程序的 ProtocolUnbindAdapterEx 函数，以请求驱动程序从基础微型端口适配器取消绑定。

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

语法

PROTOCOL_UNBIND_ADAPTER_EX ProtocolUnbindAdapterEx;

NDIS_STATUS ProtocolUnbindAdapterEx(
  [in] NDIS_HANDLE UnbindContext,
  [in] NDIS_HANDLE ProtocolBindingContext
)
{...}

参数

[in] UnbindContext

标识此取消绑定操作的 NDIS 上下文区域的句柄。

[in] ProtocolBindingContext

协议驱动程序分配的上下文区域的句柄。协议驱动程序在此上下文区域中维护每个绑定的上下文信息。驱动程序调用 NdisOpenAdapterEx 函数时，驱动程序向 NDIS 提供此句柄。

返回值

ProtocolUnbindAdapterEx 返回以下状态值之一：

返回代码	说明
NDIS_STATUS_SUCCESS	ProtocolUnbindAdapterEx 已成功从基础微型端口适配器取消绑定。
NDIS_STATUS_PENDING	ProtocolUnbindAdapterEx 未完成取消绑定操作，操作将以异步方式完成。协议驱动程序必须调用取消绑定操作完成后的 NdisCompleteUnbindAdapterEx 函数。

注解

ProtocolUnbindAdapterEx 是必需函数。作为 ProtocolBindAdapterEx 函数的倒数，NDIS 调用 ProtocolUnbindAdapterEx 以释放驱动程序为特定于绑定的网络 I/O 操作分配的资源。协议驱动程序无法使取消绑定的操作失败。

在调用 ProtocolUnbindAdapterEx 之前，NDIS 会暂停协议绑定。为了暂停绑定，NDIS 调用 ProtocolNetPnPEvent 函数并指定 NetEventPause 事件。

ProtocolUnbindAdapterEx 必须调用 NdisCloseAdapterEx 函数以关闭与基础微型端口适配器的绑定。如果 NdisCloseAdapterEx 返回NDIS_STATUS_SUCCESS，则关闭操作已完成。如果 NdisCloseAdapterEx 返回NDIS_STATUS_PENDING，则 NDIS 将调用协议驱动程序的关闭操作完成后的 ProtocolCloseAdapterCompleteEx 函数。

在调用 NdisCloseAdapterEx 之前，协议驱动程序应清除绑定的多播地址列表和数据包筛选器。协议驱动程序将绑定多播地址列表设置为 NULL，将数据包筛选器设置为零。有关详细信息，请参阅 OID_802_3_MULTICAST_LIST 和 OID_GEN_CURRENT_PACKET_FILTER。

如果已指定唤醒模式，则协议驱动程序应使用 OID_PNP_REMOVE_WAKE_UP_PATTERN OID 将其删除，并使用 OID_GEN_RECEIVE_SCALE_PARAMETERS OID 清除接收端缩放参数。 NDIS 6.20 及更高版本的协议驱动程序应使用 OID_PM_REMOVE_WOL_PATTERN OID 删除 LAN 唤醒模式，并删除 OID_PM_REMOVE_PROTOCOL_OFFLOAD OID 的低功耗协议卸载。

ProtocolUnbindAdapterEx 不得释放 ProtocolBindingContext 上的内存，直到关闭操作完成。 NDIS 将 ProtocolBindingContext 中的句柄传递给 ProtocolCloseAdapterCompleteEx。

如果协议驱动程序已完成取消绑定操作， ProtocolUnbindAdapterEx 可以返回NDIS_STATUS_SUCCESS。如果 NdisCloseAdapterEx 返回NDIS_STATUS_PENDING， 则 ProtocolUnbindAdapterEx 必须等待 NDIS 调用 ProtocolCloseAdapterCompleteEx ，然后才能返回NDIS_STATUS_SUCCESS。

ProtocolUnbindAdapterEx 可以返回NDIS_STATUS_PENDING，以将取消绑定操作的完成延迟到以后的时间。如果 ProtocolUnbindAdapterEx 返回NDIS_STATUS_PENDING，驱动程序必须最终调用 NdisCompleteUnbindAdapterEx 函数，用于完成取消绑定操作。如果 NdisCloseAdapterEx 函数返回NDIS_STATUS_PENDING，驱动程序可以在 ProtocolCloseAdapterCompleteEx 中完成取消绑定操作。 ProtocolUnbindAdapterEx 在调用 NdisCloseAdapterEx 之前，可以将句柄存储在 ProtocolBindingContext 的上下文区域中的 UnbindContext。如果 ProtocolUnbindAdapterEx 存储了句柄， 则 ProtocolCloseAdapterCompleteEx 可以将句柄传递给 NdisCompleteUnbindAdapterEx 以完成取消绑定操作。

ProtocolUnbindAdapterEx 调用 NdisCloseAdapterEx 后，从 NdisBindingHandle 参数的 NdisOpenAdapterEx 函数获取的句柄将变为无效。 ProtocolUnbindAdapterEx 不能对此句柄对 NdisXxx 函数进行任何后续调用。驱动程序可以从基础微型端口适配器获取接收和状态指示，直到关闭操作完成。

NDIS 在 IRQL = PASSIVE_LEVEL调用 ProtocolUnbindAdapterEx 。

更新电源管理和 RSS 设置

NDIS 6.0 和 6.1 协议驱动程序应执行以下操作（如果适用）：

使用从微型端口适配器中删除 LAN (WOL) 模式上的电源管理唤醒 OID_PNP_REMOVE_WAKE_UP_PATTERN 老。
使用清除接收方缩放参数 OID_GEN_RECEIVE_SCALE_PARAMETERS 老。

NDIS 6.20 及更高版本的协议驱动程序应执行以下操作：

使用 OID_PM_REMOVE_WOL_PATTERN OID 从微型端口适配器中删除电源管理 WOL 模式。
使用从微型端口适配器中删除电源管理协议卸载 OID_PM_REMOVE_PROTOCOL_OFFLOAD 老。

示例

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

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

PROTOCOL_UNBIND_ADAPTER_EX MyUnbindAdapterEx;

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

_Use_decl_annotations_
NDIS_STATUS
 MyUnbindAdapterEx(
    NDIS_HANDLE  UnbindContext,
    NDIS_HANDLE  ProtocolBindingContext
    )
  {...}

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

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