PROTOCOL_CO_CREATE_VC回调函数（ndis.h）

项目
02/07/2025

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 库使用保留。但是，调用管理器和客户端必须保存此句柄，以传入对 NdisCo/Cl/Cm/MCmXxx 涉及此 VC 的函数的后续调用。

[out] ProtocolVcContext

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

返回值

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

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

言论

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

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

面向连接的协议驱动程序必须将 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 中采取任何作，该作实际上会建立调用，因为 VC 在建立呼叫之前可能会销毁，因为连接导向型 NDIS 的另一个组件存在错误条件。

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

示例

若要定义 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的信息，请参阅批注函数行为。

要求

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