PROTOCOL_CO_CREATE_VC回调函数 (ndis.h)

项目
08/07/2023

ProtocolCoCreateVc 函数是一个必需函数，它分配调用管理器或客户端激活和维护 VC) (虚拟连接所需的资源。

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

语法

PROTOCOL_CO_CREATE_VC ProtocolCoCreateVc;

NDIS_STATUS ProtocolCoCreateVc(
  [in]  NDIS_HANDLE ProtocolAfContext,
  [in]  NDIS_HANDLE NdisVcHandle,
  [out] PNDIS_HANDLE ProtocolVcContext
)
{...}

参数

[in] ProtocolAfContext

指定协议分配的上下文区域的句柄，调用管理器或客户端在其中保持其每打开状态。调用管理器从其 ProtocolCmOpenAf 函数中提供了此句柄。客户端从其 ProtocolCoAfRegisterNotify 函数调用 NdisClOpenAddressFamilyEx 时提供了此句柄。

[in] NdisVcHandle

指定由 NDIS 提供的唯一标识此虚拟连接的句柄。此句柄对协议驱动程序不透明，并保留供 NDIS 库使用。但是，调用管理器和客户端必须保存此句柄，以便后续调用传入涉及此 VC 的 NdisCo/Cl/Cm/MCmXxx 函数。

[out] ProtocolVcContext

指定协议提供的上下文区域的句柄，调用管理器或客户端在其中维护有关此虚拟连接的状态。

返回值

ProtocolCoCreateVc 将 () 的操作状态作为以下值之一返回：

返回代码	说明
NDIS_STATUS_SUCCESS	指示调用管理器或客户端已成功分配和/或初始化建立和维护虚拟连接所需的任何必要资源。
NDIS_STATUS_RESOURCES	指示调用管理器或客户端无法分配和/或初始化其资源以建立和维护虚拟连接。
NDIS_STATUS_XXX	指示调用管理器或客户端无法将自身设置为可以建立虚拟连接的状态。这可能是从另一个 NDIS 库例程传播的错误返回值。注意调用管理器或客户端无法从其 ProtocolCoCreateVc 函数返回NDIS_STATUS_PENDING。返回挂起将使此虚拟连接不可用，NDIS 库将调用客户端或调用管理器将其删除。

注解

每当相应的客户端或调用管理器分别调用 NdisCoCreateVc 时，调用管理器或客户端的 ProtocolCoCreateVc 函数。客户端在调用 NdisClMakeCall 之前，在设置传出呼叫的过程中启动 VC 的创建。调用管理器在通知其客户端 CM 收到来自远程节点的传入呼叫套餐的过程中启动 VC 的创建，该远程节点在 CM 调用之前定向到该客户端已注册到该 CM 的 SAP NdisCmDispatchIncomingCall。

ProtocolCoCreateVc 执行调用管理器或客户端对要激活的 VC 执行后续操作所需的动态资源和结构的任何必要分配。此类资源包括但不限于内存缓冲区、数据结构、事件和其他类似资源。呼叫管理器和客户端还应初始化建立呼叫时所需的任何相关 per-VC 结构。

面向连接的协议驱动程序必须将 NdisVcHandle 中指定的 VC 的句柄存储在其每 VC 状态区域中，以便在此虚拟连接上的未来操作中使用。 NdisVcHandle 是此类面向连接的协议随后调用的 NdisCoXxx、NdisCmXxx 和/或 NdisClXxx 的必需参数。

当调用管理器或客户端为其自己的每个 VC 数据分配内存并初始化其状态时，应在句柄中设置此数据结构的地址，然后再将控制权返回到 NDIS。为此，请取消引用句柄，并将指向协议分配的数据区域的指针存储为句柄的值。例如：

*ProtocolVcContext = SomeBuffer;

如果 ProtocolCoCreateVc 无法分配执行后续网络 I/O 操作所需的资源，则应释放为此 VC 分配的所有资源，并返回状态为“NDIS_STATUS_RESOURCES”的控制。

如果 ProtocolCoCreateVc 已完成其所需的操作，并且已使调用管理器或客户端准备好为此虚拟连接执行调用初始化， 则 ProtocolCoCreateVc 应尽快返回控制权，状态为 NDIS_STATUS_SUCCESS。

对 ProtocolCoCreateVc 的调用本质上是同步的。也就是说， ProtocolCoCreateVc无法返回NDIS_STATUS_PENDING。

调用管理器的 ProtocolCoCreateVc 函数返回控制权后，将调用调用管理器的 ProtocolCmMakeCall 函数以建立与远程节点的连接。调用管理器不应在 ProtocolCmMakeCall 中执行实际建立呼叫的任何操作，因为在建立呼叫之前，由于面向连接的 NDIS 的另一个组件中的错误条件，可能会销毁 VC。

客户端的 ProtocolCoCreateVc 函数返回控制权后，当远程发起的在客户端先前注册的 SAP 上进行连接的请求通过网络传入时，客户端的 ProtocolClIncomingCall 函数将收到通知。

示例

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

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

PROTOCOL_CO_CREATE_VC MyCoCreateVc;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCoCreateVc(
    NDIS_HANDLE  ProtocolAfContext,
    NDIS_HANDLE  NdisVcHandle,
    PNDIS_HANDLE  ProtocolVcContext
    )
  {...}

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

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

要求

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