PoFxRegisterDevice 関数 (wdm.h)

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

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