REQUEST_POWER_COMPLETE コールバック関数 (wdm.h)

[アーティクル]
02/29/2024

PowerCompletion コールバックルーチンは、power 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

電源 IRP のマイナー関数コードを指定します。詳細については、「解説」セクションのサポートされている IRP_MN_XXX コードの一覧を参照してください。

[in] PowerState

PoRequestPowerIrp ルーチンに渡されたデバイスの電源状態またはシステム電源状態を指定します。

[in, optional] Context

PoRequestPowerIrp に渡されたコンテキストへのポインター。

[in] IoStatus

完成した IRP の IO_STATUS_BLOCK 構造体へのポインター。

戻り値

なし

解説

電源 IRP を送信するドライバーは、他のすべてのドライバーが IRP を完了した後、追加のタスクを実行する必要があります。その場合、送信ドライバーは、IRP を割り当てる PoRequestPowerIrp ルーチンの呼び出し中に PowerCompletion コールバックルーチンを登録する必要があります。

ドライバーの PowerCompletion コールバックルーチンは、IRP_MN_SET_POWER、IRP_MN_QUERY_POWER、およびIRP_MN_WAIT_WAKEのマイナー IRP コードを持つIRP_MJ_POWER IRP にのみ使用されます。詳細については、「デバイスの電源状態のIRP_MN_QUERY_POWERまたはIRP_MN_SET_POWERの送信」および「待機/スリープ解除コールバックルーチン」を参照してください。

I/O マネージャーは、I/O マネージャーがスタックの下に IRP を渡すと、他のドライバーによって設定されたすべての IoCompletion ルーチンを呼び出した後にのみ、送信ドライバーの PowerCompletion ルーチンを呼び出します。 PowerCompletion ルーチンは、他のすべてのドライバーが IRP を完了した後、IRP の送信者が必要とする追加のタスクを実行します。 PowerCompletion ルーチンは IRP を解放しないでください。これは、電源マネージャーが行います。

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_については、「関数の動作に注釈を付ける」を参照してください。

要件

要件	値
対象プラットフォーム	デスクトップ
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
IRQL	IRQL <= DISPATCH_LEVELで呼び出されます (「解説」セクションを参照)。