PO_FX_COMPONENT_IDLE_STATE_CALLBACK回呼函式 (wdm.h)

發行項
02/27/2024

ComponentIdleStateCallback 回呼例程會通知驅動程式對指定元件的 Fx 電源狀態進行擱置變更。

語法

PO_FX_COMPONENT_IDLE_STATE_CALLBACK PoFxComponentIdleStateCallback;

void PoFxComponentIdleStateCallback(
  [in] PVOID Context,
  [in] ULONG Component,
  [in] ULONG State
)
{...}

參數

[in] Context

裝置內容的指標。設備驅動器會使用此內容來儲存裝置目前電源狀態的相關信息。設備驅動器會在PO_FX_DEVICE結構的 DeviceContext 成員中指定此指標，驅動程式用來向電源管理架構註冊裝置， (PoFx) 。此內容對 PoFx 而言不透明。

[in] Component

指定元件編號。此參數是裝置驅動程式用來向PoFx註冊裝置之PO_FX_DEVICE結構中 Components 陣列的索引。如果 Components 陣列包含 N 個元素，元件索引的範圍從 0 到 N-1。

[in] State

指定元件將變更的新 Fx 電源狀態。如果此參數為零，則新狀態為 F0;如果此參數為一，則新狀態為 F1;依此類故。

傳回值

無

備註

當 PoFx 呼叫驅動程式的 ComponentIdleStateCallback 例程時，驅動程式可能需要準備擱置的 Fx 狀態變更。完成任何必要的準備工作之後，驅動程式必須呼叫 PoFxCompleteIdleState 例程，通知PoFx驅動程式已完成對 ComponentIdleStateCallback 回 呼的回應。 PoFxCompleteIdleState 呼叫可以在 ComponentIdleStateCallback 例程傳回之前或之後發生。

如果元件要從 F0 切換到低電源 Fx 狀態，裝置將會失去元件的硬體狀態，驅動程式必須在轉換至新的 Fx 狀態之前儲存該元件的硬體狀態。如果元件是從低電源 Fx 狀態切換到 F0，而且先前已儲存硬體狀態，驅動程式應該在電源還原至元件之後還原硬體狀態。

對於某些裝置，元件電源狀態可能會在裝置硬體中控制。針對這些裝置，驅動程式通常會負責變更元件的電源狀態。對於其他裝置，元件的電源狀態可能會由裝置外部的硬體控制，而驅動程式通常必須依賴 PoFx 來設定元件的電源狀態。

如果驅動程式負責設定元件的電源狀態，驅動程式應該變更電源狀態以回應 ComponentIdleStateCallback 回 呼。對於從 F0 轉換為低電源 Fx 狀態的轉換，元件在 進入 ComponentIdleStateCallback 例程時為 F0，而且驅動程式必須在呼叫 PoFxCompleteIdleState 之前將元件切換為新的 Fx 狀態。若要從低電源 Fx 狀態轉換為 F0，元件在 進入 ComponentIdleStateCallback 例程時處於低電源 Fx 狀態，而且驅動程式必須先將元件切換至 F0，再呼叫 PoFxCompleteIdleState。

如果驅動程式不負責設定元件的電源狀態，驅動程式應該假設元件在 進入 ComponentIdleStateCallback 例程時一律處於 F0 狀態。對於從 F0 到低電源 Fx 狀態的暫止轉換，在驅動程式呼叫 PoFxCompleteIdleState 之後，才會發生轉換到新的 Fx 狀態。針對從低電源 Fx 狀態轉換為 F0 的轉換，轉換至 F0 會在呼叫 ComponentIdleStateCallback 例程之前發生。

PoFx 永遠不會呼叫 ComponentIdleStateCallback 例程，直接從一個低電源 Fx 狀態切換到另一個低電量 Fx 狀態。例如，PoFx 可能需要將元件從一個低電源 Fx 狀態切換到另一個，以回應對 PoFxSetComponentLatency、 PoFxSetComponentResidency 或 PoFxSetComponentWake 例程的呼叫。在此情況下，PoFx 會先呼叫 ComponentIdleStateCallback 例程，以從舊的 Fx 狀態切換至 F0，然後第二次呼叫 ComponentIdleStateCallback 例程，以從 F0 切換到新的 Fx 狀態。

範例

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

例如，若要定義名為 MyComponentIdleStateCallback的 ComponentIdleStateCallback 回呼例程，請使用 PO_FX_COMPONENT_IDLE_STATE_CALLBACK 類型，如下列程式代碼範例所示：

PO_FX_COMPONENT_IDLE_STATE_CALLBACK MyComponentIdleStateCallback;

然後，實作回呼例程，如下所示：

_Use_decl_annotations_
VOID
  MyComponentIdleStateCallback(
    PVOID Context,
    ULONG Component,
    ULONG State
    )
  {
      // Function body
  }

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

規格需求

需求	值
最低支援的用戶端	Windows 8 和更新版本的 Windows 支援。
目標平台	桌面
標頭	wdm.h (包含 Wudfwdm.h)
IRQL	在 IRQL <= DISPATCH_LEVEL呼叫。