PROTOCOL_CL_INCOMING_CLOSE_CALL回调函数 (ndis.h)

项目
02/26/2024

ProtocolClIncomingCloseCall 函数由所有面向连接的 NDIS 客户端使用。所有此类客户端都必须具有完全正常运行 的 ProtocolClIncomingCloseCall 函数。

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

语法

PROTOCOL_CL_INCOMING_CLOSE_CALL ProtocolClIncomingCloseCall;

void ProtocolClIncomingCloseCall(
  [in] NDIS_STATUS CloseStatus,
  [in] NDIS_HANDLE ProtocolVcContext,
  [in] PVOID CloseData,
  [in] UINT Size
)
{...}

参数

[in] CloseStatus

指定指示连接断开原因的状态，该状态通常NDIS_STATUS_SUCCESS指示呼叫的远程方请求关闭连接。任何其他值表示网络上的问题导致调用管理器终止连接。

[in] ProtocolVcContext

为要关闭连接的 VC 指定客户端每个 VC 上下文区域的句柄。无论 CloseStatus 的值如何，客户端都不能在此上下文区域中的 NdisVcHandle 指定的 VC 上发送和接收数据。

[in] CloseData

指向包含特定于协议的关闭消息的缓冲区的指针，该消息可能是由调用管理器通过网络接收的远程客户端提供的，或者此参数可以为 NULL。

NDIS_STATUS_SUCCESS CloseStatus 时，如果基础网络介质在关闭连接时不支持数据传输，则此参数为 NULL 。但是，任何特定的呼叫管理器都可能定义一个结构，以将其他诊断信息传递给其客户端，因为网络上的问题导致呼叫拆解。

[in] Size

指定 CloseData 处缓冲区的大小（以字节为单位），如果 CloseData 为 NULL，则为零。

返回值

无

备注

调用 ProtocolClIncomingCloseCall 表示发生了以下情况之一：

调用管理器已通过网络收到一个请求，要求关闭已建立的连接，该连接由 NdisVcHandle 标识，客户端存储在其每个 VC 上下文区域中 的 ProtocolVcContext 。
呼叫管理器已检测到网络问题将阻止在已建立的连接上进一步传输数据。

在任一情况下， ProtocolClIncomingCloseCall 都应执行任何协议确定的操作，例如通知客户端自己的客户端 () 连接中断。例如，如果要关闭的调用是由客户端创建的多点 VC， 则 ProtocolClIncomingCloseCall 必须调用 NdisClDropParty 一次或多次，直到只有一方保留在其多点 VC 上。

无论给定的 VC 是单点连接还是多点连接， ProtocolClIncomingCloseCall 都必须调用 NdisClCloseCall 来确认客户端既不会尝试发送也不期望接收此特定 VC 上的数据。如果调用管理器创建了此 VC， 则 ProtocolClIncomingCloseCall 应在调用 NdisClCloseCall 后返回控制权。调用管理器负责销毁或重用它创建的任何 VC。

如果客户端最初为传出调用创建了此 VC， 则 ProtocolClIncomingCloseCall 可以在根据需要调用 NdisClDropParty （如果有）和 NdisClClall 之后执行以下操作之一：

如果 CloseStatus 是NDIS_STATUS_SUCCESS，请使用 NdisCoDeleteVc 删除 VC，然后释放客户端的每个 VC 上下文区域，或准备在后续调用 NdisCoCreateVc 中重复使用它。
如果 CloseStatus 是NDIS_STATUS_SUCCESS，请保留客户端创建的 VC，并准备其每个 VC 上下文区域，以便在后续调用 NdisClMakeCall 时重复使用。
否则，使用 NdisCoDeleteVc 删除 VC，并释放其每 VC 上下文区域（如果调用管理器指示网络已失效）。

示例

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

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

PROTOCOL_CL_INCOMING_CLOSE_CALL MyClIncomingCloseCall;

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

_Use_decl_annotations_
VOID
 MyClIncomingCloseCall(
    NDIS_STATUS  CloseStatus,
    NDIS_HANDLE  ProtocolVcContext,
    PVOID  CloseData,
    UINT  Size
    )
  {...}

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

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

要求

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