MINIPORT_PAUSE回呼函式 (ndis.h)

發行項
05/23/2024

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 會傳回下列其中一個狀態值：

傳回碼	Description
NDIS_STATUS_SUCCESS	MiniportPause 已成功透過迷你埠配接器停止網路數據的流程。
NDIS_STATUS_PENDING	MiniportPause 未完成暫停作業，且作業將會以異步方式完成。迷你埠驅動程序必須在作業完成時呼叫 NdisMPauseComplete 函式。

備註

驅動程式會在呼叫時指定 MiniportPause 進入點 NdisMRegisterMiniportDriver 函式。

NDIS 會暫停迷你埠配接器，以停止可能會干擾 PnP 作業的數據流，例如新增或移除篩選驅動程式，或系結或解除系結通訊協定驅動程式。

NDIS 會呼叫迷你埠驅動程式的 MiniportPause 函式，以起始 MiniportAdapterContext 中指定的迷你埠配接器的暫停要求。迷你埠配接器會 維持在暫停 狀態，直到暫停作業完成為止。

針對 處於暫停 狀態的迷你埠適配卡，迷你埠驅動程式：

等候對的所有呼叫要傳回的 NdisMIndicateReceiveNetBufferLists 函式。
等候 NDIS 將所有 NET_BUFFER_LIST 結構的擁有權從未處理的接收指示傳回到迷你埠驅動程式的 MiniportReturnNetBufferLists 函式。
完成所有未完成的傳送要求，並呼叫所有未處理傳送要求的 NdisMSendNetBufferListsComplete 函式。
拒絕對它提出的所有新傳送要求 MiniportSendNetBufferLists 函式會立即呼叫 NdisMSendNetBufferListsComplete。它應該在每個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的詳細資訊，請參閱標註函式行為。