PROTOCOL_CL_REGISTER_SAP_COMPLETE回调函数 (ndis.h)

项目
08/07/2023

接受传入调用的面向连接的 NDIS 客户端必须具有 ProtocolClRegisterSapComplete 函数才能完成它使用 NdisClRegisterSap 启动的异步操作。否则，此类协议驱动程序的已注册 ProtocolClRegisterSapComplete 函数只需返回控制权。

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

语法

PROTOCOL_CL_REGISTER_SAP_COMPLETE ProtocolClRegisterSapComplete;

void ProtocolClRegisterSapComplete(
  [in] NDIS_STATUS Status,
  [in] NDIS_HANDLE ProtocolSapContext,
  [in] PCO_SAP Sap,
  [in] NDIS_HANDLE NdisSapHandle
)
{...}

参数

[in] Status

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

NDIS_STATUS_SUCCESS

SAP 已向 NDIS 和调用管理器注册，后者随后将调用每当收到定向到给定 SAP 的传入呼叫套餐时，NdisCmDispatchIncomingCall，从而导致 NDIS 调用客户端的 ProtocolClIncomingCall 函数。

NDIS_STATUS_RESOURCES

NDIS 或调用管理器无法分配和/或初始化必要的资源来注册和维护 SAP。

NDIS_STATUS_INVALID_DATA

客户端在 Sap 上向 NDIS 提供了无效规范，该规范已转发到调用管理器的 ProtocolCmRegisterSap 函数进行验证。

NDIS_STATUS_XXX

调用管理器在尝试注册给定 SAP 时遇到错误，NDIS 将此 CM 确定的失败状态传播到客户端。

[in] ProtocolSapContext

指定客户端每个 SAP 上下文区域的句柄，客户端在调用 NdisClRegisterSap 时最初提供给 NDIS。如果注册成功，NDIS 将保留此上下文句柄，随后在调用客户端的与此 SAP 相关的 ProtocolClIncomingCall 函数时使用该句柄。

[in] Sap

指向客户端分配的缓冲区的指针，该缓冲区包含要打开的 SAP 的规范。客户端最初将此指针传递到 NdisClRegisterSap。

[in] NdisSapHandle

如果 Status 为NDIS_STATUS_SUCCESS，则指定此已注册 SAP 的 NDIS 提供的有效句柄，实际上是客户端与客户端指定 SAP 的特定调用管理器之间与 NDIS 建立的关联。否则，此参数为 NULL。客户端必须保存有效的句柄（最好在其 ProtocolSapContext 区域中），以便最终调用 NdisClDeregisterSap。

返回值

无

备注

NDIS 调用 ProtocolClRegisterSapComplete 以指示客户端对 NdisClRegisterSap 的上一次调用已由 NDIS 处理，如果 NDIS 未使调用失败，则由客户端共享传递给 NdisClRegisterSap 的 NdisAfHandle 的调用管理器处理。

若要通过面向连接的 NIC 接收传入呼叫，客户端的 ProtocolCoAfRegisterNotify 或 ProtocolClOpenAfCompleteEx 函数通常向调用管理器注册一个或多个 SAP。

为了注册每个 SAP，客户端调用 NdisClRegisterSap，传入标识客户端要从中接收传入呼叫通知的调用管理器的 NdisClRegisterSap，如果客户端对 NdisClRegisterSap 的调用成功，NDIS 会将客户端返回 NdisSapHandle 给已注册的 SAP。 ProtocolClRegisterSapComplete 必须保存每个有效的 NdisSapHandle，通常保存在客户端的 per-SAP ProtocolSapContext 区域中，以便稍后可以使用 NdisClDeregisterSap 发布 SAP。

SAP 的格式特定于调用管理器。如果调用管理器无法识别客户端尝试注册的 SAP，或者指定的 SAP 已在使用中，则调用管理器可能会使 SAP 注册失败。 ProtocolClRegisterSapComplete 应在进一步处理之前检查NDIS_STATUS_SUCCESS的输入状态。如果尝试注册 SAP 失败，
ProtocolClRegisterSapComplete 可以在 Sap 上释放 客户端分配的每个 SAP 上下文区域和缓冲区，或者准备在对 NdisClRegisterSap 的另一次调用中重复使用它们。

即使 SAP 注册仍处于挂起状态（即调用其 ProtocolClRegisterSapComplete 函数之前），客户端也可以接收 SAP 上的传入调用。

示例

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

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

PROTOCOL_CL_REGISTER_SAP_COMPLETE MyClRegisterSapComplete;

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

_Use_decl_annotations_
VOID
 MyClRegisterSapComplete(
    NDIS_STATUS  Status,
    NDIS_HANDLE  ProtocolSapContext,
    PCO_SAP  Sap,
    NDIS_HANDLE  NdisSapHandle
    )
  {...}

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

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

要求

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