PROTOCOL_CL_ADD_PARTY_COMPLETE回调函数 (ndis.h)

项目
03/05/2024

ProtocolClAddPartyComplete 函数对于设置多点连接的面向连接的 NDIS 客户端是必需的。此类客户端必须具有 ProtocolClAddPartyComplete 函数才能完成它们使用 NdisClAddParty 启动的异步操作。否则，此类协议驱动程序的已注册 ProtocolClAddPartyComplete 函数只需返回控制权。

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

语法

PROTOCOL_CL_ADD_PARTY_COMPLETE ProtocolClAddPartyComplete;

void ProtocolClAddPartyComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolPartyContext,
  [in] NDIS_HANDLE NdisPartyHandle,
  [in] PCO_CALL_PARAMETERS CallParameters
)
{...}

参数

[in] Status

指定客户端发起的添加方操作的最终状态，可以是下列操作之一：

NDIS_STATUS_SUCCESS

给定的一方已添加到客户端的活动多点 VC 上。

NDIS_STATUS_RESOURCES

NDIS 无法分配足够的资源来跟踪新参与方。

NDIS_STATUS_FAILURE

客户端将无效的 NdisVcHandle 传递给 NdisClAddParty。

NDIS_STATUS_XXX

调用管理器的 ProtocolCmAddParty 函数返回 CM 确定的值，以指示它为何无法将参与方添加到 VC。

[in] ProtocolPartyContext

指定最初传递给 NdisClAddParty 的客户端提供的句柄。

[in] NdisPartyHandle

如果 Status 为NDIS_STATUS_SUCCESS，则此 NDIS 提供的句柄表示调用管理器和客户端之间关于此方的关联。否则，尝试添加参与方失败，客户端应将此参数视为无效句柄。

[in] CallParameters

指向 CO_CALL_PARAMETERS 类型的结构的指针，最初由客户端为其调用 NdisClAddParty 而设置，但随后可能由调用管理器修改。

返回值

无

备注

调用 ProtocolClAddPartyComplete 指示客户端调用 NdisClAddParty 时启动的异步操作完成。如果输入状态设置为除 NDIS_STATUS_SUCCESS 以外的任何内容， 则 ProtocolClAddPartyComplete 可以在 ProtocolPartyContext 和 CallParameters 上释放或重复使用客户端分配的缓冲区。

如果尝试添加参与方成功， 则 ProtocolClAddPartyComplete 应保存输入 NdisPartyHandle ，以便在客户端的 ProtocolPartyContext 区域中针对该参与方对 NDIS 库函数的后续调用。例如，客户端必须在后续调用 NdisClDropParty 时传递此句柄，除非它所代表的远程方先关闭其连接。

CallParameters 中的结构最初是由客户端分配和初始化的，客户端将此指针传递给
NdisClAddParty。但是，调用管理器可能修改了客户端提供的值，以反映 CM 在处理客户端的添加方请求时与网络或信号对等方协商的结果。若要确定调用管理器是否进行了任何修改，ProtocolClAddPartyComplete 可以检查此结构的 Flags 成员，以确定是否设置了CALL_PARAMETERS_CHANGED。如果是这样， ProtocolClAddPartyComplete 必须更新客户端在 ProtocolPartyContext 中为此调用维护的每方状态，除非它发现 CM 的修改不可接受。特定信号协议确定客户端在这种情况下可以执行的操作。通常，如果客户端发现 CM 修改的调用参数不可接受，则调用 NdisClDropParty 。

根据调用管理器的信号协议， CallParameters 中的流量参数对于任何特定多点连接的所有方而言可能相同。也就是说，当此类调用管理器的客户端在客户端最初使用 NdisClMakeCall 设置的多点连接上添加参与方时，它只能提供每一方的目标地址，并在每次调用 NdisClAddParty 时保留最初为多点 VC 设置的流量参数。

示例

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

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

PROTOCOL_CL_ADD_PARTY_COMPLETE MyClAddPartyComplete;

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

_Use_decl_annotations_
VOID
 MyClAddPartyComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolPartyContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

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

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

要求

要求	值
最低受支持的客户端	NDIS 6.0 和 NDIS 5.1 驱动程序支持 (请参阅 Windows Vista 中的 ProtocolClAddPartyComplete (NDIS 5.1) ) 。 NDIS 5.1 驱动程序支持 (请参阅 Windows XP 中的 ProtocolClAddPartyComplete (NDIS 5.1) ) 。
目标平台	Windows
标头	ndis.h (包括 Ndis.h)
IRQL	<= DISPATCH_LEVEL