PoRegisterPowerSettingCallback 関数 (ntifs.h)

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 は、次のいずれかを返します。

注釈

ドライバーは 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 コールバック

電源設定コールバック ルーチンとそのパラメーターの関数プロトタイプは次のとおりです。 電源マネージャーは、IRQL = PASSIVE_LEVELで電源設定コールバックを呼び出します。

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

例

電源設定コールバック ルーチンを定義するには、まず、定義するコールバック関数の種類を識別する関数宣言を指定する必要があります。 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の詳細については、「関数の動作に注釈を付ける」を参照してください。

要件

こちらもご覧ください

DriverEntry

EvtDeviceSelfManagedIoCleanup

EvtDeviceSelfManagedIoInit

EvtDriverDeviceAdd

PoUnregisterPowerSettingCallback