PoRegisterPowerSettingCallback 関数 (wdm.h)

[アーティクル]
03/08/2023

PoRegisterPowerSettingCallback ルーチンは、電源設定コールバックルーチンを登録して、指定した電源設定の変更に関する通知を受け取ります。

構文

NTSTATUS PoRegisterPowerSettingCallback(
  [in, optional] PDEVICE_OBJECT          DeviceObject,
  [in]           LPCGUID                 SettingGuid,
  [in]           PPOWER_SETTING_CALLBACK Callback,
  [in, optional] PVOID                   Context,
  [out]          PVOID                   *Handle
);

パラメーター

[in, optional] DeviceObject

このルーチンの呼び出し元に関連付けられている DEVICE_OBJECT 構造体へのポインター。このパラメーターは省略可能です。これは、デバッグ目的でのみ内部的に使用されます。このパラメーターを指定しない場合は、 NULL に設定する必要があります。

[in] SettingGuid

この登録の電源設定を表す GUID へのポインター。指定した電源設定が変更されると、電源マネージャーはコールバックルーチンを呼び出して、ドライバーに変更を通知し、設定の新しい値を指定します。詳細については、「解説」を参照してください。

[in] Callback

指定した電源設定が変更されたときに電源マネージャーが呼び出す、呼び出し元によって実装された電源設定コールバックルーチンへのポインター。コールバックルーチンの機能プロトタイプについては、「 Power-Setting Callback」を参照してください。

[in, optional] Context

コールバックルーチンのコンテキストへのポインター。このパラメーターは省略可能です。ドライバーまたはデバイスコンテキストをコールバックルーチンに渡すことができるように提供されます。このパラメーターを使用しない場合は、 NULL に設定する必要があります。

[out] Handle

電源マネージャーがコールバックルーチンを表すために使用するハンドル。ドライバーは、その後、コールバックルーチンの登録を解除するために、PoUnregisterPowerSettingCallback の呼び出しでこのハンドルを指定する必要があります。

戻り値

PoRegisterPowerSettingCallback は、次のいずれかを返します。

リターンコード	説明
STATUS_SUCCESS	ルーチンによってコールバックルーチンが登録されました。
STATUS_INSUFFICIENT_RESOURCES	ルーチンは、コールバックルーチンの登録に必要なシステムリソースを割り当てませんでした。

注釈

ドライバーは PoRegisterPowerSettingCallback を呼び出して、コールバックルーチンを電源マネージャーに登録します。その後、電源マネージャーはこのコールバックルーチンを呼び出して、指定した電源設定に変更が発生した後にドライバーに通知します。さらに、電源マネージャーは、コールバックルーチンをすぐに呼び出し、電源設定の現在の値を渡すことによって、ドライバーの電源設定を初期化します。電源マネージャーは、電源設定が実際に変更されたかどうかに関係なく、ドライバーの電源設定をこのように初期化します。

ドライバーは、ドライバーが監視する必要がある電源設定ごとに PoRegisterPowerSettingCallback を呼び出す必要があります。ドライバーは、初期化中に DriverEntry ルーチンでこのルーチンを呼び出す必要があります。通常、ほとんどのドライバーは 、Context パラメーターでデバイス拡張機能へのポインターを渡します。

電源設定コールバックの登録を解除するには、 PoUnregisterPowerSettingCallback ルーチンを呼び出します。

通常、Kernel-Mode Driver Framework (KMDF) ドライバーは、EvtDeviceSelfManagedIoInit コールバック関数から PoRegisterPowerSettingCallback を呼び出し、EvtDeviceSelfManagedIoCleanup コールバック関数から PoUnregisterPowerSettingCallback を呼び出す必要があります。これらのドライバーは、EvtDriverDeviceAdd コールバック関数から PoRegisterPowerSettingCallback を呼び出さないでください。それ以外の場合は、ドライバースタックが完全に構築される前に、電源設定コールバックルーチンが呼び出される可能性があります。

特定の電源設定に登録されているコールバックルーチンは、設定の値を変更する電源状態の遷移が発生したとき、または電源マネージャーが設定の値を変更したときに呼び出されます。たとえば、 SettingGuid が GUID_LIDSWITCH_STATE_CHANGE GUID 値を指している場合、ラップトップコンピューターのカバーが開いているか閉じられたときにコールバックルーチンが呼び出されます。この例のコールバックルーチンに渡される Value パラメーターは、カバースイッチの状態が閉じている状態から開いている状態に変わった場合は 1、カバースイッチの状態が開いている状態から閉じている状態に変わった場合は 0 である ULONG 値を指します。詳細については、Wdm.h ヘッダーファイルの電源設定 GUID 定義と広範なコメントを参照してください。

コールバックルーチンの最初の呼び出しは、ルーチンが返す PoRegisterPowerSettingCallback 呼び出しの直前に発生する可能性があります。

PoRegisterPowerSettingCallback は IRQL = PASSIVE_LEVELでのみ呼び出すことができます。

Power-Setting コールバック

電源設定コールバックルーチンの関数プロトタイプは次のとおりです。

NTSTATUS
POWER_SETTING_CALLBACK (
  _In_ LPCGUID SettingGuid,
  _In_ PVOID Value,
  _In_ ULONG ValueLength,
  _Inout_opt_ PVOID Context
);

電源設定コールバックパラメーターは次のとおりです。

SettingGuid
変更された電源設定を表す GUID へのポインター。電源設定とそれに対応する GUID は Wdm.h で定義されています。

Value
変更された電源設定の新しい値へのポインター。

ValueLength
新しい電源設定値のサイズをバイト単位で指定する ULONG 型の値。

コンテキスト
コールバックルーチンを登録した PoRegisterPowerSettingCallback の呼び出しでドライバーが指定したコンテキストへのポインター。

電源マネージャーは、IRQL = PASSIVE_LEVELで電源設定コールバックを呼び出します。

例

電源設定コールバックルーチンを定義するには、まず、定義するコールバック関数の種類を識別する関数宣言を指定する必要があります。 Windows には、ドライバーのコールバック関数型のセットが用意されています。コールバック関数の種類を使用して関数を宣言すると、ドライバーのコード分析、静的ドライバー検証ツール (SDV)、およびその他の検証ツールでエラーが検出され、Windows オペレーティングシステムのドライバーを記述するための要件になります。

たとえば、という名前 MyPowerSettingCallbackの電源設定コールバックルーチンを定義するには、次のコード例に示すように、POWER_SETTING_CALLBACK型を使用します。

POWER_SETTING_CALLBACK MyPowerSettingCallback;

次に、コールバックルーチンを次のように実装します。

_Use_decl_annotations_
NTSTATUS
  MyPowerSettingCallback(
    LPCGUID SettingGuid,
    PVOID Value,
    ULONG ValueLength,
    PVOID Context 
    )
  {
      // Function body
  }

POWER_SETTING_CALLBACK関数の種類は、Wdm.h ヘッダーファイルで定義されています。コード分析ツールの実行時にエラーをより正確に識別するには、必ず注釈を _Use_decl_annotations_ 関数定義に追加してください。注釈により _Use_decl_annotations_ 、ヘッダーファイル内のPOWER_SETTING_CALLBACK関数型に適用される注釈が確実に使用されます。関数宣言の要件の詳細については、「 WDM ドライバーの関数ロール型を使用して関数を宣言する」を参照してください。の詳細 _Use_decl_annotations_については、「関数の動作に注釈を付ける」を参照してください。

要件

要件	値
対象プラットフォーム	ユニバーサル
Header	wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む)
Library	NtosKrnl.lib
[DLL]	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (「解説」セクションを参照)