MINIPORT_SHUTDOWN回呼函式 (ndis.h)

發行項
02/27/2024

當系統關閉時，NDIS 會呼叫迷你埠驅動程式的 MiniportShutdownEx 函式。此函式會將迷你埠放入 [關機] 狀態，其中沒有其他回呼可以 (包括 MiniportHaltEx) 。如需迷你埠驅動程序狀態的詳細資訊，請參閱 Miniport配接器狀態和作業。

注意您必須使用 MINIPORT_SHUTDOWN 類型來宣告函式。如需詳細資訊，請參閱下列範例一節。

語法

MINIPORT_SHUTDOWN MiniportShutdown;

void MiniportShutdown(
  [in] NDIS_HANDLE MiniportAdapterContext,
  [in] NDIS_SHUTDOWN_ACTION ShutdownAction
)
{...}

參數

[in] MiniportAdapterContext

迷你埠驅動程式在其 MiniportInitializeEx 函式中配置的內容區域句柄。驅動程式會使用此內容區域來維護迷你埠配接器的狀態資訊。

[in] ShutdownAction

NDIS 呼叫關機函式的原因。下列是有效值：

NdisShutdownPowerOff

指出 NDIS 稱為 MiniportShutdownEx ，因為系統正在關閉。

NdisShutdownBugCheck

表示 NDIS 因為發生系統錯誤，所以稱為 MiniportShutdownEx 。

傳回值

無

備註

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

MiniportShutdownEx 會將迷你埠適配卡還原至已知的初始狀態， (NDIS 呼叫 miniport 驅動程式的 MiniportInitializeEx 函式之前，迷你埠適配卡) 。這可確保迷你埠適配卡處於已知狀態，並準備好在發生系統關機后重新啟動計算機時重新初始化，包括無法復原的系統錯誤。

MiniportShutdownEx 可以藉由呼叫 NdisMGetBusData 或 NdisMSetBusData 函式來停用 DMA 引擎、停用中斷，或將硬體重設為已知狀態，以將硬體重設為已知狀態，以便安全地重新啟動硬體。

如果 NDIS 因為使用者起始的關機而呼叫 MiniportShutdownEx，MiniportShutdownEx 會在 IRQL = PASSIVE_LEVEL執行，而迷你埠驅動程式可以呼叫其他 NdisXxx 函式。

如果 NDIS 因為無法復原的錯誤而呼叫 MiniportShutdownEx，ShutdownAction 參數會設定為 NdisShutdownBugCheck，而 MiniportShutdownEx 正在高 IRQL 執行。在此情況下，迷你埠驅動程式不得呼叫任何 NdisXxx 函式，但可以在任何 IRQL 呼叫的函式除外。從 NDIS 6.30 迷你埠開始，除非迷你埠在其配接器註冊屬性中提供NDIS_MINIPORT_ATTRIBUTES_REGISTER_BUGCHECK_CALLBACK旗標，否則 NDIS 不會在 BugCheck 期間呼叫 MiniportShutdownEx。

如果 ShutdownAction 的值是 NdisShutdownPowerOff，迷你埠驅動程式可能會選擇性地釋放其資源。不過，這既不需要也不鼓勵，因為系統關機會不需要。

如果 ShutdownAction 的值是 NdisShutdownBugCheck，迷你埠驅動程式不得釋放其資源。

重要如果 MiniportHaltEx 造成系統錯誤，迷你埠驅動程式會看到具有 ShutdownActionNdisShutdownBugCheck 的MiniportShutdownEx 巢狀呼叫。在此情況下， MiniportShutdownEx 應該立即傳回，而不需要執行任何工作。

例子

若要定義 MiniportShutdownEx 函式，您必須先提供函式宣告，以識別您要定義的函式類型。 Windows 提供一組驅動程式的函式類型。使用函式類型宣告函式有助於驅動程式的程式代碼分析、靜態驅動程序驗證器 (SDV) ，以及其他驗證工具會尋找錯誤，而且這是撰寫 Windows 操作系統驅動程式的需求。

例如，若要定義名為「 MyShutdownEx」的 MiniportShutdownEx 函式，請使用 MINIPORT_SHUTDOWN 類型，如下列程式代碼範例所示：

MINIPORT_SHUTDOWN MyShutdownEx;

然後，實作您的函式，如下所示：

_Use_decl_annotations_
VOID
 MyShutdownEx(
    NDIS_HANDLE  MiniportAdapterContext,
    NDIS_SHUTDOWN_ACTION  ShutdownAction
    )
  {...}

MINIPORT_SHUTDOWN函式類型定義於 Ndis.h 頭檔中。若要在執行程式代碼分析工具時更精確地識別錯誤，請務必將 Use_decl_annotations 註釋新增至函式定義。 Use_decl_annotations註釋可確保使用頭檔中套用至MINIPORT_SHUTDOWN函式類型的批註。如需函式宣告需求的詳細資訊，請參閱使用 NDIS 驅動程式的函式角色類型來宣告函式。

如需 Use_decl_annotations的詳細資訊，請參閱標註函式行為。