MINIPORT_PAUSE回调函数（ndis.h）

项目
02/07/2025

NDIS 调用微型端口驱动程序的 MiniportPause 函数，以通过指定的微型端口适配器停止网络数据流。

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

语法

MINIPORT_PAUSE MiniportPause;

NDIS_STATUS MiniportPause(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] PNDIS_MINIPORT_PAUSE_PARAMETERS PauseParameters
)
{...}

参数

[in] MiniportAdapterContext

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

[in] PauseParameters

指向 NDIS_MINIPORT_PAUSE_PARAMETERS 结构，用于定义微型端口适配器的暂停参数。

返回值

MiniportPause 返回以下状态值之一：

返回代码	描述
NDIS_STATUS_SUCCESS	MiniportPause 通过微型端口适配器成功停止了网络数据流。
NDIS_STATUS_PENDING	MiniportPause 未完成暂停作，作将以异步方式完成。微型端口驱动程序必须在作完成后调用 NdisMPauseComplete 函数。

言论

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

NDIS 暂停微型端口适配器以停止可能会干扰 PnP作的数据流，例如添加或删除筛选器驱动程序、绑定或取消绑定协议驱动程序。

NDIS 调用微型端口驱动程序的 MiniportPause 函数来启动 MiniportAdapterContext中指定的微型端口适配器的暂停请求。微型端口适配器在暂停作完成之前保持暂停状态。

对于处于暂停状态的微型端口适配器，微型端口驱动程序：

等待对 NdisMIndicateReceiveNetBufferLists 函数返回。
等待 NDIS 返回所有 NET_BUFFER_LIST 结构的所有权，从未完成的接收指示返回到微型端口驱动程序的 MiniportReturnNetBufferLists 函数。
完成所有未完成的发送请求并调用为所有未完成的发送请求 NdisMSendNetBufferListsComplete 函数。
拒绝对其发出的所有新发送请求通过调用 NdisMSendNetBufferListsComplete立即 MiniportSendNetBufferLists 函数。它应将每个NET_BUFFER_LIST中的完整状态设置为NDIS_STATUS_PAUSED。
可以向提供状态指示 NdisMIndicateStatusEx 函数。
应在 MiniportOidRequest 函数中处理 OID 请求。
如果停止微型端口适配器阻止驱动程序处理请求或提供状态指示，则不应完全停止微型端口适配器。
不应释放初始化期间分配的驱动程序的资源。

NDIS 不会为微型端口适配器启动其他 PnP作，例如暂停、初始化、电源更改、暂停或重启请求，而微型端口适配器处于暂停状态。 NDIS 可以在微型端口适配器处于暂停状态后启动这些 PnP作。

微型端口驱动程序完成所有未完成的发送请求，NDIS 返回所有收到的网络数据结构（来自未接收指示），驱动程序必须完成暂停作。如果驱动程序从 MiniportPause返回NDIS_STATUS_SUCCESS，则暂停作已完成。如果驱动程序返回NDIS_STATUS_PENDING，微型端口适配器可以保持暂停状态，并在驱动程序调用 NdisMPauseComplete 函数后完成暂停作。暂停作完成后，微型端口适配器处于暂停状态。

对于处于暂停状态的微型端口适配器，微型端口驱动程序：

必须通过调用 NdisMSendNetBufferListsComplete立即拒绝对 MiniportSendNetBufferLists 发出的所有发送请求。它应将每个NET_BUFFER_LIST中的“状态”成员设置为NDIS_STATUS_PAUSED。
可以处理接收中断（请参阅 MiniportInterrupt 函数）和中断 DPC（请参阅 MiniportInterruptDPC 函数），但不应指示收到的网络数据。
可以使用 NdisMIndicateStatusEx 函数提供状态指示。
应在 MiniportOidRequest 函数中处理 OID 请求。
应处理请求以更改设备电源状态 MiniportDevicePnPEventNotify 函数。
可以处理对 NetTimerCallback 函数的调用。
可以处理在 MiniportResetEx 函数中重置硬件的请求。

微型端口驱动程序无法通过暂停请求。因此，如果微型端口驱动程序需要任何资源来处理暂停请求，则应在初始化期间预先分配资源。

NDIS 调用 MiniportRestart 函数，为暂停的微型端口适配器启动重启请求。

NDIS 在 IRQL = PASSIVE_LEVEL 调用 miniportPause。

示例

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

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

MINIPORT_PAUSE MyPause;

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

_Use_decl_annotations_
NDIS_STATUS
 MyPause(
    NDIS_HANDLE  MiniportAdapterContext,
    PNDIS_MINIPORT_PAUSE_PARAMETERS  MiniportPauseParameters
    )
  {...}

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

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