MINIPORT_HALT回调函数（ndis.h）

2025-02-07

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 函数。

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

MiniportHaltEx 必须释放在设备 MiniportInitializeEx 中分配的所有资源。 MiniportHaltEx 还会释放驱动程序在该设备的后续作中分配的任何其他资源。驱动程序必须调用 NdisXxx 函数的对等函数，该函数最初分配了资源。一般情况下，MiniportHaltEx 函数应调用倒数 NdisXxx 函数，以便反向调用从 MiniportInitializeEx发出的驱动程序。

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

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

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

如果驱动程序必须等待任何作完成，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 及更高版本中受支持。
目标平台	窗户
标头	ndis.h （包括 Ndis.h）
IRQL	PASSIVE_LEVEL
DDI 符合性规则	WlanAssociation、WlanConnectionRoaming、WlanDisassociation、WlanTimedAssociation、WlanTimedConnectionRoaming、WlanTimedConnectRequest、WlanTimedLinkQuality、WlanTimedScan