PROTOCOL_CL_MAKE_CALL_COMPLETE回调函数 (ndis.h)

项目
08/07/2023

ProtocolClMakeCallComplete 函数由进行传出调用的面向连接的 NDIS 客户端使用。此类客户端必须具有 ProtocolClMakeCallComplete 函数才能完成它们使用 NdisClMakeCall 启动的异步操作。否则，此类协议驱动程序的已注册 ProtocolClMakeCallComplete 函数只需返回控件。

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

语法

PROTOCOL_CL_MAKE_CALL_COMPLETE ProtocolClMakeCallComplete;

void ProtocolClMakeCallComplete(
  [in]           NDIS_STATUS Status,
  [in]           NDIS_HANDLE ProtocolVcContext,
  [in, optional] NDIS_HANDLE NdisPartyHandle,
  [in]           PCO_CALL_PARAMETERS CallParameters
)
{...}

参数

[in] Status

指定客户端对 NdisClMakeCall 的原始调用的最终状态，可以是以下其中一种：

NDIS_STATUS_SUCCESS

客户端尝试设置虚拟连接已成功。因此，客户端可以使用 NdisCoCreateVc 返回的 NdisVcHandle 继续对活动 VC 进行传输，客户端已将其存储在其每个 VC 上下文区域中的 ProtocolVcContext 。

NDIS_STATUS_RESOURCES

NDIS、调用管理器或基础驱动程序无法分配足够的资源来设置连接。

NDIS_STATUS_XXX

调用管理器或基础微型端口驱动程序未能建立活动连接，并且 NDIS 将此驱动程序确定的故障状态传播到客户端。

[in] ProtocolVcContext

指定客户端每 VC 上下文区域的句柄，客户端在调用 NdisCoCreateVc 以为其传出调用设置 VC 时最初提供给 NDIS。

[in, optional] NdisPartyHandle

如果 Status 为NDIS_STATUS_SUCCESS并且客户端通过将显式 ProtocolPartyContext 句柄传递给 NdisClMakeCall 创建了多点 VC，则这是有效的 NdisPartyHandle 。否则，此参数为 NULL。

ProtocolClMakeCallComplete 必须保存任何有效的输入 NdisPartyHandle，通常位于客户端的每方上下文区域中。如果 (或) 客户端对引用此参与方的 NdisClDropParty 或 NdisClClCloseCall 进行后续调用，则客户端必须使用此句柄。

[in] CallParameters

指向缓冲CO_CALL_PARAMETERS结构的指针。在将此指针传递到 NdisClMakeCall 之前，客户端分配了此缓冲区，并使用客户端确定的数据初始化了此结构。在处理客户端请求时，调用管理器可以修改此数据，以反映其与网络或信号对等方协商的结果。

返回值

无

备注

调用 ProtocolClMakeCallComplete 表示调用管理器已完成处理客户端与 NdisClMakeCall 建立虚拟连接的请求。

如果客户端尝试建立传出调用未成功， (输入状态为NDIS_STATUS_SUCCESS) ， 则 ProtocolClMakeCallComplete 应执行以下操作：

释放或准备重复使用 ProtocolPartyContext 区域（如果有）以及客户端分配的 CallParameters 上的缓冲区。
通过调用 NdisCoDeleteVc 来删除客户端创建的 VC，并释放或准备重复使用客户端分配的 ProtocolVcContext 区域。

否则， ProtocolClMakeCallComplete 应执行以下操作：

在 CallParameters 中检查结构的 Flags 成员，以查看是否设置了 CALL_PARAMETERS_CHANGED，这指示调用管理器修改了客户端提供的调用参数。
如果是这样，请检查 CallParameters 中的数据，以确定这些数据对于此连接是否可接受。
例如，客户端可能会保留活动 VC 的缓冲调用参数，如果这是多点 VC，则保存 NdisPartyHandle ;如果客户端发现给定的调用参数令人满意，则通常会使客户端准备好在活动 VC 上进行后续传输和其他操作。
否则，信号协议将确定客户端是否可以尝试与调用管理器重新协商可接受的调用参数。
例如，特定调用管理器可能允许其客户端在这些情况下调用 NdisClModifyCallQoS 一次或多次。
如果 CM 修改的调用参数不可接受并且无法进一步重新协商， 则 ProtocolClMakeCallComplete 必须使用 NdisClClCloseCall 取消调用。
在这种情况下， ProtocolClMakeCallComplete不应尝试在从 NdisClClCloseCall 返回时释放任何客户端分配的资源，而只能返回控制权。相反，客户端应释放 (分配的资源，或准备在其 ProtocolClCloseCallComplete 函数中重复使用) 资源。

示例

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

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

PROTOCOL_CL_MAKE_CALL_COMPLETE MyClMakeCallComplete;

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

_Use_decl_annotations_
VOID
 MyClMakeCallComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolVcContext,
    NDIS_HANDLE  NdisPartyHandle,
    PCO_CALL_PARAMETERS  CallParameters
    )
  {...}

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

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

要求

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