REQUEST_POWER_COMPLETE回呼函式 (wdm.h)

發行項
02/27/2024

PowerCompletion 回呼例程會完成電源 IRP 的處理。

語法

REQUEST_POWER_COMPLETE RequestPowerComplete;

void RequestPowerComplete(
  [in]           PDEVICE_OBJECT DeviceObject,
  [in]           UCHAR MinorFunction,
  [in]           POWER_STATE PowerState,
  [in, optional] PVOID Context,
  [in]           PIO_STATUS_BLOCK IoStatus
)
{...}

參數

[in] DeviceObject

已完成電源 IRP 的目標指標DEVICE_OBJECT 。

[in] MinorFunction

指定 Power IRP 中的次要函式程式代碼。如需詳細資訊，請參閱一節中支援的 IRP_MN_XXX 代碼清單。

[in] PowerState

指定傳遞給 PoRequestPowerIrp 例程的裝置電源狀態或系統電源狀態。

[in, optional] Context

傳遞至 PoRequestPowerIrp 之內容的指標。

[in] IoStatus

已完成 IRP 之 IO_STATUS_BLOCK 結構的指標。

傳回值

無

備註

傳送電源 IRP 的驅動程式可能需要在所有其他驅動程式完成 IRP 之後執行其他工作。如果是，傳送驅動程式應該在呼叫配置 IRP 的 PoRequestPowerIrp 例程期間註冊 PowerCompletion 回呼例程。

驅動程式的PowerCompletion回呼例程僅適用於具有次要 IRP 代碼IRP_MN_SET_POWER、IRP_MN_QUERY_POWER和IRP_MN_WAIT_WAKE的 IRP_MJ_POWER IRP。如需詳細資訊，請參閱傳送裝置電源狀態的IRP_MN_QUERY_POWER或IRP_MN_SET_POWER 和等候/喚醒回呼例程。

I/O 管理員只會在 I/O 管理員呼叫其他驅動程式所設定的所有 IoCompletion 例程之後，才會呼叫傳送驅動程式的 PowerCompletion 例程。 PowerCompletion 例程會在所有其他驅動程式完成 IRP 之後，執行 IRP 傳送者所需的任何其他工作。 PowerCompletion 例程不應該釋放 IRP，Power Manager 會執行此動作。

PowerCompletion 例程是在 IRQL = PASSIVE_LEVEL或 IRQL = DISPATCH_LEVEL呼叫。

範例

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

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

REQUEST_POWER_COMPLETE MyPowerCompletion;

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

_Use_decl_annotations_
VOID
  MyPowerCompletion(
    PDEVICE_OBJECT DeviceObject,
    UCHAR MinorFunction,
    POWER_STATE PowerState,
    PVOID Context,
    PIO_STATUS_BLOCK IoStatus
    )
  {
      // Function body
  }

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