PROTOCOL_CO_CREATE_VC回调函数 (ndis.h)

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 将操作的状态作为下列值之一返回 (s) :

返回代码 说明
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 执行后续操作所需的任何动态资源和结构分配。 此类资源包括但不限于内存缓冲区、数据结构、事件和其他类似的资源。 呼叫管理器和客户端还应初始化建立呼叫时所需的任何相关的每 VC 结构。

面向连接的协议驱动程序必须将 VC(在 NdisVcHandle 中指定的 VC 句柄)存储在其每个 VC 状态区域中,以便在将来在此虚拟连接的操作中使用。 NdisVcHandleNdisCoXxx、NdisCm Xxx 和/或 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 函数返回控制权后,客户端的 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的信息,请参阅 批注函数行为

要求

   
最低受支持的客户端 支持 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

请参阅

NdisClMakeCall

NdisClOpenAddressFamilyEx

NdisCmDispatchIncomingCall

ProtocolClIncomingCall

ProtocolCmMakeCall

ProtocolCmOpenAf

ProtocolCoAfRegisterNotify