NdisMSetAttributesEx 函数 (ndis.h)

  • 项目

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

NdisMSetAttributesEx 在初始化期间通知 NDIS 库调用方 NIC 或虚拟 NIC 的重要功能。

语法

void NdisMSetAttributesEx(
  [in]           NDIS_HANDLE         MiniportAdapterHandle,
  [in]           NDIS_HANDLE         MiniportAdapterContext,
  [in, optional] UINT                CheckForHangTimeInSeconds,
  [in]           ULONG               AttributeFlags,
  [in, optional] NDIS_INTERFACE_TYPE AdapterType
);

参数

[in] MiniportAdapterHandle

指定 MiniportInitialize 的句柄输入。

[in] MiniportAdapterContext

指定 由 MiniportInitialize 分配的驻留上下文区域的句柄。

[in, optional] CheckForHangTimeInSeconds

指定 NDIS 应调用 MiniportCheckForHang 函数的间隔（以秒为单位）。 如果驱动程序未响应 OID 请求，也没有在连续两次调用 MiniportCheckForHang 中发送请求，NDIS 可以调用驱动程序的 MiniportReset 函数。

NDIS 在调用 MiniportCheckForHang 时使用的实际间隔始终为 2 秒的倍数。 例如，如果指定 5 秒，则实际间隔大约为 4 秒。

为此参数指定零表示 NDIS 应按 NDIS 默认的 2 秒间隔调用 MiniportCheckForHang 。

如果调用方在 AttributeFlags 中设置NDIS_ATTRIBUTE_DESERIALIZE，则 NDIS 不会为微型端口驱动程序排队等待发送。 相反，每当资源不足，无法立即传输传入的发送时，此类反序列化的驱动程序必须在内部管理自己的后续发送请求的队列。

[in] AttributeFlags

指定可以使用以下标志的一个或多个 (ORed) 设置的位掩码：

  • NDIS_ATTRIBUTE_BUS_MASTER
    设置调用方 NIC 是否为总线主 DMA 设备。

  • NDIS_ATTRIBUTE_DESERIALIZE
    如果调用方是反序列化的微型端口驱动程序，则设置 。

  • NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT
    设置是否 NDIS 不应尝试超时它持有的排队到调用方的挂起发送数据包。 中间驱动程序应设置此标志，但 NIC 驱动程序不应设置。

  • NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT
    设置是否 NDIS 不应尝试超时挂起的查询，并设置它保留的排队请求给调用方。 中间驱动程序应设置此标志，但 NIC 驱动程序不应设置。

  • NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER
    设置调用方是否为中间驱动程序。

  • NDIS_ATTRIBUTE_IGNORE_TOKEN_RING_ERRORS
    如果指示令牌通道错误，则设置 NDIS 不应调用令牌环 NIC 驱动程序的 MiniportReset 函数。

  • NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND
    如果 NDIS 在系统转换为低功率 (睡眠) 状态之前不应调用驱动程序的 MiniportHalt 函数，则设置 。 依赖于硬件维护状态的驱动程序不应设置此标志。

    注意设置此标志将禁用网络接口卡 (NIC) 的“属性”对话框中的“允许计算机关闭此设备以节省电源检查”框。 即使 NIC 能够进行电源管理，也会禁用电源管理。

  • NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK
    设置驱动程序是否可以在不通知用户的情况下删除其 NIC。 此类驱动程序导出 MiniportPnPEventNotify 函数。 Windows XP 和更高版本的操作系统中提供了对NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK的系统支持。

  • NDIS_ATTRIBUTE_NOT_CO_NDIS
    由可同时支持面向连接的设备和无连接的设备的驱动程序设置，以指示该设备是无连接设备。 Windows XP 和更高版本的操作系统中提供了对 NDIS_ATTRIBUTE_NOT_CO_NDIS 的系统支持。

  • NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS
    由驱动程序设置，该驱动程序使用 NdisBufferVirtualAddressSafe、 NdisGetFirstBufferFromPacketSafe 和 NdisQueryBufferSafe 专门访问发送数据包缓冲区的系统虚拟地址。 NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS也由专门使用物理地址访问此类缓冲区的驱动程序设置。 设置NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS可以提高性能，因为操作系统不必将发送数据包缓冲区映射到系统虚拟地址。 Windows XP 及更高版本中提供对NDIS_ATTRIBUTE_USES_SAFE_BUFFER_APIS的系统支持。

  • NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO
    由不提供 TAPI 服务的 CoNDIS 微型端口驱动程序设置。 设置NDIS_ATTRIBUTE_DO_NOT_BIND_TO_ALL_CO可防止 NDIS 将微型端口驱动程序绑定到 NDIS TAPI 代理驱动程序 (NDPROXY) 。 默认情况下，NDIS 将 NDPROXY 绑定到所有 CoNDIS 微型端口驱动程序。

[in, optional] AdapterType

指定调用方 NIC 的 I/O 总线接口类型，通常为连接 NIC 的 I/O 总线类型，如下所示：

  • NdisInterfaceInternal
    指定特定于主机的内部接口。

  • NdisInterfaceIsa
    指定 ISA 接口。

  • NdisInterfaceEisa
    指定扩展的 ISA (EISA) 接口。

  • NdisInterfaceMca
    这指的是不再受支持的 MCA 总线。

  • NdisInterfaceTurboChannel
    指定 Turbo 通道接口。

  • NdisInterfacePci
    指定 PCI) 接口 (外围组件互连。

  • NdisInterfacePcMcia
    指定个人计算机内存卡国际协会 (电脑卡) 接口。

此参数与中间驱动程序无关，中间驱动程序应将此参数的零传递给 NdisMSetAttributesEx。

返回值

无

备注

MiniportInitialize 函数必须先调用 NdisMSetAttributesEx (或 NdisMSetAttributes) ，然后才能调用任何其他 NdisMRegisterXxx 或 NdisXxx 函数，该函数依赖于提供给 NdisMSetAttributesEx 的信息。 例如，如果 MiniportInitialize 尚未使用 NDIS_ATTRIBUTE_BUS_MASTER 设置 AttributeFlags 调用 NdisMSetAttributesEx，则 NIC 驱动程序对 NdisMAllocateMapRegisters 的调用将失败。

中间驱动程序必须调用 NdisMSetAttributesEx，而不是 NdisMSetAttributes，并且它们必须在 AttributeFlags 中设置NDIS_ATTRIBUTE_INTERMEDIATE_DRIVER。 设置此标志会导致 NDIS 将中间驱动程序视为全双工微型端口驱动程序，从而防止中间驱动程序中出现罕见但间歇性的死锁。 因此，每个中间驱动程序都必须能够处理并发发送和指示。

反序列化驱动程序还必须调用 NdisMSetAttributesEx，并且必须在 AttributeFlags 中设置NDIS_ATTRIBUTE_DESERIALIZE。 NDIS 不维护反序列化驱动程序的发送数据包队列，NDIS 也不会序列化对此类驱动程序的 MiniportXxx 函数的调用。 反序列化的驱动程序自行负责以下事项：

  • 接受所有传入发送请求
  • 如有必要，在内部将传入发送数据包排队，例如，如果反序列化的 NIC 驱动程序当前没有足够的资源来立即传输传入的发送数据包
  • 根据需要，在驱动程序的例程之间同步对其内部队列的访问 ()
  • 通过随后调用 NdisMSendComplete 以异步方式完成所有请求的发送，并将每个协议提供的数据包描述符传递到其 微型端口 (Co) 发送 (数据包) 函数

NDIS 假定所有面向连接的微型端口都是反序列化的驱动程序，而不考虑它们传递给 NdisMSetAttributesEx 的 AttributeFlags。 也就是说，调用 NdisMRegisterMiniport 且0x05为 MajorNdisVersion 的任何驱动程序都必须是反序列化的微型端口驱动程序。

序列化的 NIC 驱动程序可以从 MiniportInitialize 调用其中任一函数，但 NdisMSetAttributes 不允许其调用方调整调用 NIC 驱动程序的 MiniportCheckForHang 和/或 MiniportReset 函数 () 的时间间隔。

CheckForHangTimeInSeconds 的值确定 NDIS 库在发送（如果有）时的超时间隔，以及它持有排队到调用方的请求。 默认情况下，NDIS 超时排队发送 (，仅针对序列化驱动程序) 和请求以两倍的检查为挂起间隔，在此间隔后调用 MiniportReset 函数，除非驱动程序使用 NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT 设置 AttributeFlags，并在调用 NdisMSetAttributesEx 时NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT。 中间驱动程序应在调用 NdisMSetAttributesEx 时设置这些标志，因为此类驱动程序无法确定或控制基础 NIC 驱动程序何时处理发送和请求。

NIC 驱动程序不应设置NDIS_ATTRIBUTE_IGNORE_PACKET_TIMEOUT和NDIS_ATTRIBUTE_IGNORE_REQUEST_TIMEOUT标志，尽管 NDIS 将遵循序列化的 NIC 驱动程序的此类规范。 但是，NIC 驱动程序可以通过指定显式 CheckForHangTimeInSeconds 来调整调用其 MiniportReset 函数的超时间隔。 例如，通过调制解调器模拟以太网的 NIC 驱动程序可能无法在 NDIS 库的默认超时间隔内完成每个数据包。 每当数据包在此类 NIC 上出现超时时，NDIS 都会假定 NIC 不再正常运行，并调用驱动程序的 MiniportReset 函数。 对于此类 NIC 的驱动程序，使用 CheckForHangTimeInSeconds 设置为大于 2 的值调用 NdisMSetAttributesEx 既可防止不必要的重置，又会延长调用其 MiniportCheckForHang 函数（如果有）以测试 NIC 运行状态的间隔。

中间驱动程序必须设置NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND标志。 设置此标志可防止 NDIS 在系统转换为低功耗 (休眠) 状态之前停止驱动程序。

管理非 PnP 感知 NIC 的旧微型端口驱动程序可以设置NDIS_ATTRIBUTE_NO_HALT_ON_SUSPEND标志，以防止 NDIS 在系统转换为低功耗状态之前停止驱动程序。 如果微型端口驱动程序设置此标志，则 NDIS 使用 OID_PNP_CAPABILITIES 查询微型端口驱动程序，即使微型端口驱动程序的 NIC 的总线驱动程序可能已指示 NIC 不识别 PM。 微型端口驱动程序必须使用 NDIS_STATUS_SUCCESS 成功OID_PNP_CAPABILITIES请求。 在此 OID 返回的NDIS_PM_WAKE_UP_CAPABILITIES结构中，微型端口驱动程序还必须为每个唤醒功能指定设备电源状态 NdisDeviceStateUnspecified 。 当系统转换为低功耗状态时，NDIS 不会调用此类微型端口驱动程序的 MiniportHalt 函数。 在系统转换为低功耗状态之前，微型端口驱动程序必须保存它维护的任何硬件上下文。 在收到 D3 状态 的OID_PNP_SET_POWER 请求时，微型端口驱动程序必须将其 NIC 设置为适用于低功耗状态的相应状态。 收到对 D0 状态的OID_PNP_SET_POWER请求时，微型端口驱动程序必须将其 NIC 设置为工作状态的相应状态。

支持意外删除设备 (删除的微型端口驱动程序必须设置NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK，而无需通过用户界面) 通知删除。 这样做会导致 NDIS 在删除微型端口的设备时调用驱动程序的 MiniportPnPEventNotify 函数，并将 PnPEvent 设置为 NdisDevicePnPEventSurpriseRemoved 而不通知。 此外，设置NDIS_ATTRIBUTE_SURPRISE_REMOVE_OK会取消显示警告对话框，要求用户在删除设备之前停止设备。

如果微型端口驱动程序支持无连接设备和面向连接的设备，则必须设置NDIS_ATTRIBUTE_NOT_CO_NDIS（如果其设备是无连接设备）。 否则，NDIS 会错误地假定其设备面向连接，因为驱动程序向 NdisMRegisterMiniport 注册面向连接的微型端口驱动程序函数。

通常，NIC 驱动程序必须先调用 NdisMSetAttributesEx ，然后才能调用任何声明其 NIC 注册表中硬件资源的 NdisXxx 函数，因为 NDIS 在进行此类调用之前必须具有 AttributeFlags 值，并且驱动程序通常需要 MiniportAdapterContext 中的内存来存储这些调用的信息。 此限制意味着 NIC 驱动程序的 MiniportInitialize 函数在调用 NdisMSetAttributesEx 之前无法调用以下 NdisXxx：

但是，在调用 NdisMSetAttributesEx 之前，任何驱动程序的 MiniportInitialize 函数都可以调用 Ndis.。用于 检索注册表中安装的配置信息的配置函数。 只要驱动程序接口类型的已安装注册表项与特定于总线类型的 NdisReadXxxMiniportInitialize 调用匹配，MiniportInitialize 还可以调用特定于总线类型的 NdisReadXxxMiniportInitialize 函数，例如 NdisReadPciSlotInformation。

提供给 NdisMSetAttributesEx 的 MiniportAdapterContext 句柄成为在调用 NdisMRegisterMiniport 或 NdisIMRegisterLayeredMiniport 时注册的所有 MiniportXxx 函数以及 MiniportInitialize的输入参数。 通常，此句柄是指向由 MiniportInitialize 分配的驻留内存的指针，驱动程序在其中维护特定于 NIC 的运行时状态。

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

要求

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

另请参阅