PoFxRegisterDevice 関数 (wdm.h)

PoFxRegisterDevice ルーチンは、デバイスを電源管理フレームワーク (PoFx) に登録します。

構文

NTSTATUS PoFxRegisterDevice(
  [in]  PDEVICE_OBJECT Pdo,
  [in]  PPO_FX_DEVICE  Device,
  [out] POHANDLE       *Handle
);

パラメーター

[in] Pdo

物理デバイス オブジェクト (PDO) へのポインター。 このパラメーターは、登録されている物理デバイスを表す DEVICE_OBJECT 構造体を指します。 呼び出し元は、デバイスの電源ポリシー所有者であり、通常はデバイスのファンクション ドライバーです。

[in] Device

デバイスの登録情報を含む呼び出し元によって割り当てられた PO_FX_DEVICE 構造体へのポインター。 この構造体には、デバイス ドライバーによって実装されるコールバック ルーチンのセットへのポインターが含まれています。 PoFx は、ドライバーと通信するためにこれらのルーチンを呼び出します。

[out] Handle

PoFx を使用したデバイスの登録を表すハンドルをルーチンが書き込む場所へのポインター。 デバイス ドライバーは、このハンドルを、呼び出す他の PoFxXxx ルーチンに入力パラメーターとして渡します。 ドライバーは、デバイスを電源管理するために他の PoFxXxx ルーチンを呼び出す前に、まず PoFxRegisterDevice を呼び出してデバイスを登録する必要があります。

戻り値

PoFxRegisterDevice は 、ルーチンがデバイスを正常に登録した場合に STATUS_SUCCESS を返します。 エラーの戻り値として考えられるのは、次の状態コードです。

リターン コード 説明
STATUS_INVALID_PARAMETER
Pdo は NULL です。または 、PPO_FX_DEVICE 構造体に無効なバージョン番号または 0 のコンポーネント数があります。または、コンポーネントに対して指定されたアイドル状態の数が 0 です。またはアイドル状態の説明が無効です。
STATUS_DEVICE_NOT_READY
デバイスの準備ができていません。
STATUS_INSUFFICIENT_RESOURCES
登録を完了するために使用できるリソースが不足しています。

注釈

デバイス ドライバーは通常、ドライバーのIRP_MN_START_DEVICE要求ハンドラーからこのルーチン 呼び出します。 ドライバーは、デバイスが IRP_MN_START_DEVICE 要求を受信する前に、このルーチンを呼び出す必要があります。 デバイスは、デバイスが初めて起動されるときに、最初の IRP_MN_START_DEVICE 要求を受け取ります。 デバイスは、リソースの分散のために停止された後にデバイスが再起動されるたびに、追加の IRP_MN_START_DEVICE 要求を受け取ります。 既に登録されているデバイスを登録するための PoFxRegisterDevice 呼び出しは致命的なエラーであり、バグ チェックが発生します。 PoFx は、デバイス構造のメモリへのディープ コピーを実行することに注意してください。

ドライバーが PoFxRegisterDevice を呼び出す前に、デバイスは次の条件を満たしている必要があります。

  • デバイス (つまり、PDO) がまだ PoFx に登録されていません。
  • デバイスが D0 (完全にオン) の電源状態です。
  • デバイスが実行中の状態です。
  • デバイス内のすべてのコンポーネントは、F0 (完全にオン) の電源状態です。
  • すべてのコンポーネントがアクティブな状態にあります。
デバイスを PoFx に登録することで、ドライバーは、コンポーネントがアクティブに使用されている場合と、コンポーネントがアイドル状態のときに PoFx に通知する責任を負います。 デバイスが登録されている間、ドライバーは PoFxActivateComponent ルーチンを呼び出してコンポーネントのハードウェア レジスタにアクセスする必要があります。ドライバーは、コンポーネントへのアクセスが不要になったときに PoFx に通知するために PoFxIdleComponent ルーチンを呼び出す必要があります。

ドライバーが PoFxRegisterDevice を呼び出してデバイスを PoFx に登録すると、デバイス内のすべてのコンポーネントが完全にオンになり、アクティブな状態になるため、ドライバーはハードウェアの初期化を完了できます。 アクティブな電源管理を開始するには、ドライバーは PoFxStartDevicePowerManagement ルーチンを呼び出す必要があります。

既定では、 PoFxStartDevicePowerManagement は、すべてのコンポーネントをアイドル状態に切り替えます。 ドライバーが電源管理の開始直後にアクティブな状態になっているコンポーネントが必要な場合、ドライバーは PoFxActivateComponent ルーチンを呼び出してコンポーネントを明示的にアクティブ化する必要があります。この呼び出しは、 PoFxRegisterDevice 呼び出しの後、 PoFxStartDevicePowerManagement 呼び出しの前に発生する必要があります。

通常、単一コンポーネント デバイスの Kernel-Mode Driver Framework (KMDF) ドライバーは 、PoFxRegisterDevice を呼び出してデバイスを PoFx に登録しません。 代わりに、KMDF がドライバーの EvtDeviceWdmPostPoFxRegisterDevice コールバック関数を呼び出すと、このドライバーは PoFx 登録ハンドルを受け取ります。 詳細については、「 Single-Component デバイスの複数機能電源状態のサポート」を参照してください。

複数コンポーネントデバイスの KMDF ドライバーが PoFx に登録される方法については、「 Multiple-Component デバイスの複数の機能の電源状態をサポートする」を参照してください。

要件

要件
サポートされている最小のクライアント Windows 8 以降で使用できます。
対象プラットフォーム ユニバーサル
Header wdm.h
Library Ntoskrnl.lib
[DLL] Ntoskrnl.exe
IRQL PASSIVE_LEVEL

こちらもご覧ください

DEVICE_OBJECT

EvtDeviceWdmPostPoFxRegisterDevice

IRP_MN_START_DEVICE

PO_FX_DEVICE

PoFxActivateComponent

PoFxIdleComponent

PoFxStartDevicePowerManagement