PROTOCOL_CL_OPEN_AF_COMPLETE_EX回调函数 (ndis.h)

项目
02/29/2024

ProtocolClOpenAfCompleteEx 函数完成在 CoNDIS 客户端调用 NdisClOpenAddressFamilyEx 函数时启动的地址系列 (AF) 的打开。

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

语法

PROTOCOL_CL_OPEN_AF_COMPLETE_EX ProtocolClOpenAfCompleteEx;

void ProtocolClOpenAfCompleteEx(
  [in] NDIS_HANDLE ProtocolAfContext,
  [in] NDIS_HANDLE NdisAfHandle,
  [in] NDIS_STATUS Status
)
{...}

参数

[in] ProtocolAfContext

客户端提供的地址 AF 的上下文区域的句柄。客户端分配了此上下文区域，并在调用时将此句柄传递给 NDIS NdisClOpenAddressFamilyEx 函数。

[in] NdisAfHandle

如果状态为NDIS_STATUS_SUCCESS，则为 AF 提供的 NDIS 句柄。否则，此参数为 NULL。此句柄表示 NDIS 在客户端与绑定到 CoNDIS 微型端口适配器的调用管理器之间建立的关联。如果句柄不为 NULL，则客户端必须保存句柄，以便在后续调用 NdisClXxx 和 NdisCoXxx 函数时使用。

[in] Status

客户端调用 NdisClOpenAddressFamilyEx 的最终状态，可以是以下任一情况：

NDIS_STATUS_SUCCESS

AF 已打开，因此客户端可以在 ProtocolAfContext 上初始化其状态，并在后续调用 NdisClXxx 和 NdisCoXxx 函数（如 NdisCoOidRequest）时使用从 NdisAfHandle 返回的句柄。

NDIS_STATUS_RESOURCES

请求的操作失败，因为 NDIS 或调用管理器无法分配足够的内存或初始化其中一个用于跟踪 客户端打开的 ProtocolAfContext 指定的 AF 的状态。

NDIS_STATUS_FAILURE

NDIS 调用失败，可能是由于以下原因之一：

给定的 AF 与为调用方绑定到的基础微型端口驱动程序注册的任何 AF 都不匹配。
调用方适配器绑定正在关闭。
注册指定 AF 的调用管理器正在关闭其与基础微型端口适配器的绑定。

返回值

无

备注

CoNDIS 客户端需要 ProtocolClOpenAfCompleteEx 函数。 CoNDIS 客户端必须提供 ProtocolClOpenAfCompleteEx 才能完成客户端通过调用启动的异步操作 NdisClOpenAddressFamilyEx 函数。

NDIS 调用 ProtocolClOpenAfCompleteEx 以指示发生了以下部分或全部情况：

如果客户端的所有参数传递给 NdisClOpenAddressFamilyEx 函数的 ProtocolCoAfRegisterNotify 函数有效，NDIS 调用刚刚向 NDIS 注册指定 AF 的调用管理器的 ProtocolCmOpenAf 函数。
调用管理器检查了客户端的 ProtocolCoAfRegisterNotify 函数在 AddressFamily 参数处传递给 NdisClOpenAddressFamilyEx 的规范，并将该规范返回给 NDIS 的此调用管理器是否有效。

如果客户端尝试打开 AF 失败，NDIS 在调用 ProtocolClOpenAfCompleteEx 之前会清理其保存的状态。在这种情况下， ProtocolClOpenAfCompleteEx 可以释放客户端为其调用 NdisClOpenAddressFamilyEx 分配的资源，或准备重复使用这些资源。

否则， ProtocolClOpenAfCompleteEx 应设置客户端对新打开的 AF 执行后续操作所需的任何客户端确定状态。具体而言，客户端必须保存 NdisAfHandle 参数中的句柄，通常位于客户端的 ProtocolAfContext 上下文区域中。

如果客户端接受传入调用，它可能会 (SAP) 状态区域分配每服务接入点，并调用 NdisClRegisterSap 函数。如果客户端发出传出调用，它可能会 (VC) 状态区域分配每个虚拟连接，并使用 NdisCoCreateVc 函数创建一个 VC，以便为来自某个客户端的传入请求做好准备，以向远程节点发出传出调用。

NDIS 在 IRQL = PASSIVE_LEVEL 调用 ProtocolClOpenAfCompleteEx 。

示例

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

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

PROTOCOL_CL_OPEN_AF_COMPLETE_EX MyClOpenAfCompleteEx;

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

_Use_decl_annotations_
VOID
 MyClOpenAfCompleteEx(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  NdisAfHandle,
    NDIS_STATUS  Status
    )
  {...}

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

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