PROTOCOL_BIND_ADAPTER_EX回调函数 (ndis.h)

项目
08/07/2023

NDIS 调用协议驱动程序的 ProtocolBindAdapterEx 函数，以请求驱动程序绑定到微型端口适配器。

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

语法

PROTOCOL_BIND_ADAPTER_EX ProtocolBindAdapterEx;

NDIS_STATUS ProtocolBindAdapterEx(
  [in] NDIS_HANDLE ProtocolDriverContext,
  [in] NDIS_HANDLE BindContext,
  [in] PNDIS_BIND_PARAMETERS BindParameters
)
{...}

参数

[in] ProtocolDriverContext

驱动程序分配的上下文区域的句柄，驱动程序在其中维护状态和配置信息。协议驱动程序将此上下文区域传递给 NdisRegisterProtocolDriver 函数。

[in] BindContext

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

[in] BindParameters

指向 NDIS 创建的 NDIS_BIND_PARAMETERS 结构的指针。

返回值

ProtocolBindAdapterEx 返回以下状态值之一：

返回代码	说明
NDIS_STATUS_SUCCESS	ProtocolBindAdapterEx 成功完成了对基础微型端口适配器的绑定。
NDIS_STATUS_PENDING	ProtocolBindAdapterEx 未完成绑定操作，该操作将以异步方式完成。协议驱动程序必须调用操作完成后，NdisCompleteBindAdapterEx 函数。
NDIS_STATUS_RESOURCES	ProtocolBindAdapterEx 无法分配驱动程序执行网络 I/O 操作所需的资源。
NDIS_STATUS_XXX或NTSTATUS_XXX	协议驱动程序尝试设置绑定失败。通常，此类错误状态是从 NdisXxx 函数或内核模式支持例程传播的。

注解

ProtocolBindAdapterEx 是必需函数。每当协议驱动程序可以绑定到的基础微型端口适配器可用时，NDIS 就会调用 ProtocolBindAdapterEx 来执行绑定操作。

ProtocolBindAdapterEx 分配足够的内存来维护绑定上下文信息，并调用 NdisOpenAdapterEx 函数将自身绑定到基础微型端口适配器。 ProtocolBindAdapterEx 传递指向 NdisOpenAdapterEx 的 ProtocolBindingContext 参数上的绑定上下文信息的指针。 ProtocolBindAdapterEx 将 AdapterName 成员的值从其 BindParameters 参数作为 NdisOpenAdapterEx 的 OpenParameters 参数的 AdapterName 成员传递。

在驱动程序调用 NdisOpenAdapterEx 之前，驱动程序可以将 BindParameters 处的指针传递到 NdisOpenConfigurationEx 函数，以读取与微型端口适配器关联的配置参数。

成功打开微型端口适配器后，驱动程序可以将句柄从 NdisOpenAdapterEx 的 NdisHandle 参数传递到 NdisOpenConfigurationEx，以获取存储协议绑定配置参数的注册表位置的句柄。

ProtocolBindAdapterEx 向 NdisOpenAdapterEx 传递指向一个中类型值数组的指针，该数组列出了协议驱动程序可以支持的媒体类型。此列表是 NDIS_MEDIUM 类型的子集。 NDIS 指示 OpenParameters 结构的 SelectedMediumIndex 参数中的选定介质类型。

如果 NdisOpenAdapterEx 返回错误状态， ProtocolBindAdapterEx 将返回该错误状态，释放协议驱动程序分配的每个绑定资源，并立即返回控件。

如果 NdisOpenAdapterEx 返回NDIS_STATUS_SUCCESS， 则 ProtocolBindAdapterEx 可以分配协议驱动程序在绑定上执行网络 I/O 所需的剩余资源。驱动程序还可以配置驱动程序用于跟踪网络 I/O 操作的任何特定于绑定的上下文信息。

如果 NdisOpenAdapterEx 返回NDIS_STATUS_PENDING，则 NDIS 将调用协议驱动程序的打开操作完成后的 ProtocolOpenAdapterCompleteEx 函数。 ProtocolOpenAdapterCompleteEx 可以完成绑定操作。 ProtocolBindAdapterEx 可以将 BindContext 句柄 存储在绑定上下文区域中。 NDIS 将 ProtocolBindingContext 作为输入参数传递给驱动程序的 ProtocolOpenAdapterCompleteEx 函数。

如果 NdisOpenAdapterEx 返回NDIS_STATUS_PENDING，则 NDIS 在 OpenParameters 参数处设置结构的 SelectedMediumIndex 成员，并在 NdisOpenAdapterEx 返回后设置 NdisBindingHandle 参数的值。 NDIS 在调用 ProtocolOpenAdapterCompleteEx 之前设置这些值。因此，协议驱动程序必须将打开的参数结构以及协议绑定句柄存储在 ProtocolBindingContext (或任何有效位置的上下文区域中，直到 NDIS 调用 ProtocolOpenAdapterCompleteEx) 。

在打开操作完成之前，协议驱动程序无法对绑定发出 OID 请求。由于绑定在打开操作完成后处于暂停状态，因此在 NDIS 重启绑定之前，协议驱动程序无法发出发送请求。

打开操作完成后， ProtocolBindAdapterEx 可以返回NDIS_STATUS_SUCCESS以完成绑定操作。 ProtocolBindAdapterEx 可以返回NDIS_STATUS_PENDING，以将绑定操作的完成延迟到以后的时间。如果 ProtocolBindAdapterEx 返回NDIS_STATUS_PENDING，驱动程序必须调用绑定操作完成后的 NdisCompleteBindAdapterEx 函数。

协议驱动程序应使用 NDIS_BIND_PARAMETERS 结构来确定基础微型端口适配器的功能。打开操作完成后，协议驱动程序可以调用 NdisOidRequest 函数来查询基础微型端口驱动程序 (或 NDIS) 其他微型端口适配器功能，具体取决于基础媒体。有关 OID 请求的详细信息，请参阅协议驱动程序 OID 请求。

NDIS 可以调用协议驱动程序的驱动程序为绑定设置数据包筛选器后的 ProtocolReceiveNetBufferLists 函数 OID_GEN_CURRENT_PACKET_FILTER 老。如果基础微型端口适配器不对传入数据包使用数据包筛选器，则在打开操作完成后，将启用接收指示。打开操作完成后，协议驱动程序可以在 ProtocolStatusEx 函数上接收状态指示。

每个协议驱动程序都应分配足够的 NET_BUFFER 和 NET_BUFFER_LIST 结构池。驱动程序从这些池中为后续发送操作分配网络数据描述符。

如果 ProtocolBindAdapterEx 无法分配执行后续网络 I/O 操作所需的资源，则应释放已分配的所有资源，并返回适当的错误值。

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

如果协议驱动程序成功打开微型端口适配器，但绑定操作失败 (例如，由于 OID 请求) 失败，则驱动程序必须从 ProtocolBindAdapterEx 或 ProtocolUnbindAdapterEx 的上下文中关闭微型端口适配器。例如，驱动程序从 ProtocolBindAdapterEx 调用 NdisCloseAdapterEx，并等待关闭操作完成，然后驱动程序从 ProtocolBindAdapterEx 返回。或者，如果驱动程序从 ProtocolBindAdapterEx 返回NDIS_STATUS_PENDING，驱动程序可以调用 NdisUnbindAdapter 函数，并在 ProtocolUnbindAdapterEx 函数中调用 NdisCloseAdapterEx。

NDIS 在 IRQL = PASSIVE_LEVEL 调用 ProtocolBindAdapterEx 。

示例

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

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

PROTOCOL_BIND_ADAPTER_EX MyBindAdapterEx;

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

_Use_decl_annotations_
NDIS_STATUS
 MyBindAdapterEx(
    NDIS_HANDLE  ProtocolDriverContext,
    NDIS_HANDLE  BindContext,
    PNDIS_BIND_PARAMETERS  BindParameters
    )
  {...}

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

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