MINIPORT_HALT回调函数 (ndis.h)

项目
02/26/2024

NDIS 调用微型端口驱动程序的 MiniportHaltEx 函数，以在删除微型端口适配器时释放资源，并停止硬件。此函数将微型端口置于“已停止”状态， (包括 MiniportShutdownEx) ，则无法发生任何其他回调。有关微型端口驱动程序状态的详细信息，请参阅微型端口适配器状态和操作。

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

语法

MINIPORT_HALT MiniportHalt;

void MiniportHalt(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] NDIS_HALT_ACTION HaltAction
)
{...}

参数

[in] MiniportAdapterContext

微型端口驱动程序在其 MiniportInitializeEx 函数中分配的上下文区域的句柄。微型端口驱动程序使用此上下文区域来维护微型端口适配器的状态信息。

[in] HaltAction

停止微型端口适配器的原因。可以为下列值之一：

NdisHaltDeviceDisabled

NDIS 正在停止微型端口适配器以响应即插即用 (PnP) 删除消息。

NdisHaltDeviceInstanceDeInitialized

NDIS 正在停止微型端口适配器，以响应调用的中间驱动程序 NdisIMDeInitializeDeviceInstance 函数。

NdisHaltDevicePoweredDown

NDIS 正在停止微型端口适配器，因为系统将进入睡眠状态。

NdisHaltDeviceSurpriseRemoved

微型端口适配器意外删除，硬件不存在。

NdisHaltDeviceFailed

由于硬件故障，将删除微型端口适配器。称为 NdisMRemoveMiniport 函数的微型端口驱动程序或总线驱动程序在恢复时未启动 NIC。

NdisHaltDeviceInitializationFailed

MiniportInitializeEx 函数成功完成后，由于未知原因，NDIS 无法初始化微型端口适配器。

NdisHaltDeviceStopped

NDIS 正在停止微型端口适配器以响应 PnP 停止设备消息。

返回值

无

备注

驱动程序在调用时指定 MiniportHaltEx 入口点 NdisMRegisterMiniportDriver 函数。

驱动程序的 MiniportInitializeEx 函数成功返回后，NDIS 可以随时调用 MiniportHaltEx。如果驱动程序控制物理 NIC，MiniportHaltEx 应停止 NIC。如果 NDIS 中间驱动程序调用 NdisIMDeInitializeDeviceInstance 函数，NDIS 为驱动程序的虚拟设备调用 MiniportHaltEx 函数。

MiniportHaltEx 必须为设备释放 MiniportInitializeEx 中分配的所有资源。 MiniportHaltEx 还会释放驱动程序在该设备的后续操作中分配的任何其他资源。驱动程序必须调用最初分配资源的 NdisXxx 函数的倒数。作为一般规则，MiniportHaltEx 函数应按从 MiniportInitializeEx 调用驱动程序的顺序调用倒数 NdisXxx 函数。

如果 NIC 生成中断，则微型端口驱动程序的 MiniportHaltEx 函数可由驱动程序的 MiniportInterrupt 函数抢占，直到 MiniportHaltEx 调用 NdisMDeregisterInterruptEx 函数返回。此类驱动程序的 MiniportHaltEx 函数应禁用中断，并调用 NdisMDeregisterInterruptEx 尽快。请注意，驱动程序可能会一直收到中断，直到 NdisMDeregisterInterruptEx 返回。在驱动程序完成所有计划的 DPC 之前，NdisMDeregisterInterruptEx 不会返回， (请参阅 MiniportInterruptDPC 函数以获取) 的详细信息。

如果驱动程序具有与可能位于系统计时器队列中的计时器对象关联的 NetTimerCallback 函数， MiniportHaltEx 应调用 NdisCancelTimerObject 函数。如果 NdisCancelTimerObject 失败，则计时器可能已触发。在这种情况下，驱动程序应等待计时器函数完成，然后驱动程序才从 MiniportHaltEx 返回。

如果有未完成的 OID 请求或发送请求，NDIS 不会调用 MiniportHaltEx 。在 NDIS 调用 MiniportHaltEx 后，NDIS 不会为受影响的设备提交进一步的请求。

如果驱动程序必须等待任何操作完成， MiniportHaltEx 可以使用 NdisWaitEvent 函数或 NdisMSleep 函数。

NDIS 在 IRQL = PASSIVE_LEVEL 调用 MiniportHaltEx 。

示例

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

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

MINIPORT_HALT MyHaltEx;

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

_Use_decl_annotations_
VOID
 MyHaltEx(
    NDIS_HANDLE  MiniportAdapterContext,
    NDIS_HALT_ACTION  HaltAction
    )
  {...}

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

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

要求

要求	值
最低受支持的客户端	在 NDIS 6.0 及更高版本中受支持。
目标平台	Windows
标头	ndis.h (包括 Ndis.h)
IRQL	PASSIVE_LEVEL
DDI 符合性规则	WlanAssociation、WlanConnectionRoaming、WlanDisassociation、WlanTimedAssociation、WlanTimedConnectionRoaming、WlanTimedConnectRequest、WlanTimedLinkQuality、WlanTimedScanScan