MINIPORT_HALT回呼函式 (ndis.h)

發行項
02/29/2024

NDIS 會呼叫迷你埠驅動程式的 MiniportHaltEx 函式，以在移除迷你埠配接器時釋放資源，並停止硬體。此函式會將迷你埠放入「已停止」狀態，其中沒有其他回呼發生 (包括 MiniportShutdownEx) 。如需迷你埠驅動程序狀態的詳細資訊，請參閱 Miniport配接器狀態和作業。

注意您必須使用 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 和更新版本支援。
目標平台	Windows
標頭	ndis.h (包括 Ndis.h)
IRQL	PASSIVE_LEVEL
DDI 合規性規則	WlanAssociation、WlanConnectionRoaming、WlanDisassociation、WlanTimedAssociation、WlanTimedConnectionRoaming、WlanTimedConnectRequest、WlanTimedLinkQuality、WlanTimedScan