NdisOpenAdapter 函数 (ndis.h)

  • 项目

注意 NDIS 5. x 已弃用，由 NDIS 6 取代。 x。 有关新的 NDIS 驱动程序开发，请参阅 从 Windows Vista 开始的网络驱动程序。 有关移植 NDIS 5 的信息。 NDIS 6 的 x 驱动程序。 x，请参阅 将 NDIS 5.x 驱动程序移植到 NDIS 6.0。

NdisOpenAdapter 设置调用协议与特定基础 NIC 驱动程序或 NDIS 中间驱动程序之间的绑定。

语法

void NdisOpenAdapter(
  [out]          PNDIS_STATUS Status,
  [out]          PNDIS_STATUS OpenErrorStatus,
  [out]          PNDIS_HANDLE NdisBindingHandle,
  [out]          PUINT        SelectedMediumIndex,
  [in]           PNDIS_MEDIUM MediumArray,
  [in]           UINT         MediumArraySize,
  [in]           NDIS_HANDLE  NdisProtocolHandle,
  [in]           NDIS_HANDLE  ProtocolBindingContext,
  [in]           PNDIS_STRING AdapterName,
  [in]           UINT         OpenOptions,
  [in, optional] PSTRING      AddressingInformation
);

参数

[out] Status

指向调用方提供的变量的指针，该变量在从此函数返回时可以是以下值之一：

  • STATUS_SUCCESS
    现在已设置请求的绑定，以便调用方可以在对 NdisXxx 的后续调用中使用在 NdisBindingHandle 和 SelectedMediumIndex 处返回的值。

  • NDIS_STATUS_PENDING
    正在异步处理请求的操作，打开完成后，将调用调用方 ProtocolOpenAdapterComplete 函数。

  • NDIS_STATUS_RESOURCES
    请求的操作失败，因为 NDIS 无法分配足够的内存或初始化它用于跟踪打开的绑定的状态。

  • NDIS_STATUS_ADAPTER_NOT_FOUND
    请求的操作失败，因为在系统对象命名空间中找不到 AdapterName 的名称。

  • NDIS_STATUS_UNSUPPORTED_MEDIA
    MediumArray 中的数组未指定 NDIS 或基础驱动程序支持的任何介质。

  • NDIS_STATUS_CLOSING
    正在关闭在 AdapterName 指定的调用方或物理设备或虚拟设备。

  • NDIS_STATUS_OPEN_FAILED
    由于上述任何特定原因，打开尝试均失败。 例如，可能 NDIS 无法初始化所选介质的筛选器包。

[out] OpenErrorStatus

指向调用方提供的变量的指针，如果 NdisOpenAdapter 在 Status 处返回错误，该变量可能包含NDIS_STATUS_XXX 错误，则提供更多信息。 例如，令牌环 NIC 的驱动程序可能会在此变量中返回环错误。

[out] NdisBindingHandle

指向调用方提供的变量的指针，其中 NDIS 返回表示调用方与 AdapterName 中指定的给定物理或虚拟 NIC 之间的成功绑定的句柄。

[out] SelectedMediumIndex

指向调用方提供的变量的指针，其中 NDIS 返回指定基础 NDIS 驱动程序使用的媒体类型的数组元素的索引。

[in] MediumArray

指向NDIS_MEDIUM类型的值数组的指针，这些值指定调用方可以支持的媒体类型。 可能的元素包括以下任何适当的子集：

  • NdisMedium802_3
    指定以太网 (802.3) 网络。

  • NdisMedium802_5
    指定令牌通道 (802.5) 网络。

  • NdisMediumFddi
    指定 FDDI) 网络 (光纤分布式数据接口。

  • NdisMediumWan
    指定广域网。 此类型涵盖各种形式的点到点和 WAN NIC，以及建立绑定后必须在协议驱动程序和基础驱动程序之间协商的变体地址/标头格式。

  • NdisMediumLocalTalk
    指定 LocalTalk 网络。

  • NdisMediumDix
    指定驱动程序使用 DIX 以太网标头格式的以太网网络。

  • NdisMediumArcnetRaw
    指定 ARCNET 网络。

  • NdisMediumArcnet878_2
    指定 ARCNET (878.2) 网络。

  • NdisMediumAtm
    指定 ATM 网络。 面向连接的客户端协议可以将自身绑定到返回此值的基础微型端口驱动程序。 否则，旧协议会自行绑定到系统提供的 LanE 中间驱动程序，后者将其中等类型报告为 NdisMedium802_3 或 NdisMedium802_5，具体取决于网络管理员配置 LanE 驱动程序的方式。

  • NdisMediumWirelessWan
    指定无线网络。 支持无线 LAN (WLAN) 或无线 WAN (WWAN) 数据包的 NDIS 5.X 微型端口驱动程序将其介质声明为 NdisMedium802_3 ，并将以太网模拟到更高级别的 NDIS 驱动程序。

    注意 从 Windows Vista 开始，此媒体类型不可使用。

  • NdisMediumIrda
    指定红外 (IrDA) 网络。

  • NdisMediumCoWan
    指定面向连接的环境中的广域网。

  • NdisMedium1394
    指定 IEEE 1394 (火线) 网络。

[in] MediumArraySize

指定 MediumArray 处的元素数。

[in] NdisProtocolHandle

指定 NdisRegisterProtocol 返回的句柄。

[in] ProtocolBindingContext

指定调用方提供的常驻上下文区域的句柄，在该区域中，协议在建立此绑定后保持有关此绑定的状态。

[in] AdapterName

指向NDIS_STRING类型的指针，该类型包含计数字符串（在系统默认字符集中指定），命名基础 NDIS 驱动程序的 NIC 或虚拟适配器。 此驱动程序导出一组上边缘 ( MiniportXxx) 函数。 对于 Windows 2000 及更高版本的驱动程序，此计数字符串包含 Unicode 字符。 也就是说，对于 Windows 2000 及更高版本，NDIS 将NDIS_STRING类型定义为 UNICODE_STRING 类型。

[in] OpenOptions

指定一个位掩码，其中包含调用方传递给下一低级驱动程序（假定为 NIC 驱动程序）的标志。 目前，此参数保留供系统使用。

[in, optional] AddressingInformation

指向可选的可变长度计数字符串的指针，该字符串包含特定于 NIC 驱动程序可用于对网卡进行编程的基础 NIC 的信息。 此指针可以为 NULL。

如果已提供，则寻址信息必须保持有效，直到打开的操作完成。 支持异步调制解调器的基础 NIC 驱动程序可以使用此信息进行拨号。

返回值

无

备注

协议驱动程序从其 ProtocolBindAdapter 函数调用 NdisOpenAdapter。 NDIS 不再支持从 DriverEntry 函数调用 NdisOpenAdapter，这是旧版 (V3.0) 协议可用的选项。 NDIS 不再支持 V3.0 协议。 NDIS 无法尝试在 ProtocolBindAdapter 的上下文之外调用 NdisOpenAdapter。

AdapterName 中的字符串仅在 NdisOpenAdapter 返回控制权之前保持有效，即使它在 Status 中返回NDIS_STATUS_PENDING也是如此。

应忽略 NdisBindingHandle 和 SelectedMediumIndex 中的变量，直到调用 ProtocolOpenAdapterComplete 函数（如果 NdisOpenAdapter 返回NDIS_STATUS_PENDING）。 由于这些变量在调用 ProtocolOpenAdapterComplete 之前可能一直无效，因此它们不能位于堆栈上。 通常，这些变量驻留在 ProtocolBindingContext 区域中，因为此句柄是 ProtocolOpenAdapterComplete 的输入参数。

协议驱动程序应保留 NdisProtocolHandle 处返回的句柄。 它是驱动程序随后调用的其他 NdisXxx 函数的必需参数。 提供的 ProtocolBindingContext 是调用方 ProtocolXxx 函数的输入参数，因此协议通常会在调用 NdisOpenAdapter 时将 NdisProtocolHandle 指针传递到调用方分配的上下文区域中的某个变量。

调用方在后续调用 NdisRequest 和/或 NdisCoRequest 时使用 SelectedMediumIndex 中返回的值。 它在请求数据包中设置的 OID 取决于返回的 NdisMediumXxx。 例如，如果在 SelectedMediumIndex 处返回 NdisMediumAtm，则协议驱动程序在指定 OID_ATM_ XXX 或 OID_CO_XXX 代码时调用 NdisCoRequest，并在指定 OID_GEN_XXX 代码时调用 NdisRequest。

如果在 SelectedMediumIndex 处返回 NdisMediumWan，则协议驱动程序会调用 NdisRequest，在查询中指定OID_WAN_MEDIUM_SUBTYPE，以确定基础驱动程序使用的 WAN 媒体类型。

如果以前针对无线媒体发出的OID_NETWORK_TYPE的全局查询指示驱动程序和基础 NIC 支持多个 NdisMediumWirelessWan 类型介质，则协议必须在 NDIS 设置绑定后立即选择一个受支持的媒体，然后协议才选择标头格式。

有关协议驱动程序用于与刚绑定的 NDIS 驱动程序协商的常规和中等特定 OID 的详细信息，请参阅 NDIS 对象标识符。

  • 目标平台： 通用
  • 版本：Windows Vista 中的 NDIS 6.0 驱动程序不支持。 请改用 NdisOpenAdapterEx。 支持 Windows Vista 和 Windows XP 中的 NDIS 5.1 驱动程序。

要求

要求 值
Header ndis.h (包括 Ndis.h)
Library Ndis.lib
IRQL PASSIVE_LEVEL

另请参阅