MINIPORT_PAUSE回调函数 (ndis.h)

项目
08/07/2023

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中的 Status 成员设置为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的信息，请参阅批注函数行为。