PROTOCOL_CM_OPEN_AF回调函数 (ndis.h)

  • 项目

ProtocolCmOpenAf 函数是必需的。 此函数为调用管理器分配每个打开的资源，以便与正在打开地址系列的面向连接的 NDIS 客户端进行交互。

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

语法

PROTOCOL_CM_OPEN_AF ProtocolCmOpenAf;

NDIS_STATUS ProtocolCmOpenAf(
  [in]  NDIS_HANDLE CallMgrBindingContext,
  [in]  PCO_ADDRESS_FAMILY AddressFamily,
  [in]  NDIS_HANDLE NdisAfHandle,
  [out] PNDIS_HANDLE CallMgrAfContext
)
{...}

参数

[in] CallMgrBindingContext

对于非集成调用管理器， CallMgrBindingContext 指定调用管理器分配的上下文区域的句柄，调用管理器在其中维护其按绑定状态信息。 调用管理器在调用 NdisOpenAdapterEx 时提供了此句柄。

对于集成调用管理器 (MCM ) ，CallMgrBindingContext 指定微型端口分配的上下文区域的句柄，微型端口在其中维护其每个适配器的状态信息。 微型端口在其 NdisMSetAttributesEx 调用 (中为 5.x 驱动程序提供此句柄) 或其 NdisMSetMiniportAttributes 调用 6.x 驱动程序) (。

[in] AddressFamily

指定客户端打开的地址系列。 此地址系列在调用时由呼叫管理器注册 NdisCmRegisterAddressFamilyEx.

[in] NdisAfHandle

指定由 NDIS 提供的唯一标识此地址系列实例的句柄。 此句柄对调用管理器不透明，并保留供系统使用。

[out] CallMgrAfContext

指定呼叫管理器提供的上下文区域的句柄，呼叫管理器在其中维护有关此打开的地址系列的状态。

返回值

ProtocolCmOpenAf 将 () 的操作状态返回为以下内容之一：

返回代码 说明
NDIS_STATUS_SUCCESS
 指示调用管理器已成功分配并初始化从客户端到此地址系列的请求所需的任何资源。
NDIS_STATUS_PENDING
 指示正在异步处理请求的操作。 呼叫管理器必须调用 当 NdisCmOpenAddressFamilyComplete 已完成其所有 open-AF 操作时，向 NDIS (，并且客户端) 该操作 () 已完成。
NDIS_STATUS_RESOURCES
 指示调用管理器由于缺少可用的系统资源（如内存）而无法完成其 () 所需的操作。
NDIS_STATUS_XXX
 指示调用管理器无法将自身设置为可以接受来自客户端的请求以对此地址系列进行操作的状态。 这可能是从另一个 NDIS 库函数传播的错误状态，或者由驱动程序编写器确定的适合的任何错误状态。

注解

ProtocolCmOpenAf 执行任何必需的动态资源和结构的分配，调用管理器编写者认为有必要代表打开此地址系列的实例的客户端执行操作。 此类资源包括但不限于内存缓冲区、数据结构、事件和其他类似资源。 在将控制权返回到 NDIS 之前，调用管理器还应初始化任何相关的每打开数据。

当呼叫管理器分配其按打开的状态区域时，应在 CallMgrAfContext 句柄 中设置状态区域的地址，然后再将控制权返回到 NDIS。 为此，请取消引用 CallMgrAfContext ，并将指向数据区域的指针存储为句柄的值。 例如：

*CallMgrAfContext = SomeBuffer;

如果 ProtocolCmOpenAf 无法分配它代表打开此地址系列的客户端执行后续请求所需的每打开资源，则它应释放为打开的所有资源，并使用NDIS_STATUS_RESOURCES将控制权返回到 NDIS。

如果 ProtocolCmOpenAf 已完成其所需的操作，并且 CM 已准备好接受来自客户端的请求， 则 ProtocolCmOpenAf 应尽快返回NDIS_STATUS_SUCCESS状态的控制权。

示例

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

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

PROTOCOL_CM_OPEN_AF MyCmOpenAf;

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

_Use_decl_annotations_
NDIS_STATUS
 MyCmOpenAf(
    NDIS_HANDLE  CallMgrBindingContext,
    PCO_ADDRESS_FAMILY  AddressFamily,
    NDIS_HANDLE  NdisAfHandle,
    PNDIS_HANDLE  CallMgrAfContext
    )
  {...}

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

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

要求

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

另请参阅

NdisClOpenAddressFamilyEx

NdisCmOpenAddressFamilyComplete NdisCmRegisterAddressFamilyEx

NdisOpenAdapterEx