PoFxActivateComponent 関数 (wdm.h)
PoFxActivateComponent ルーチンは、指定されたコンポーネントのアクティブ化参照カウントをインクリメントします。
構文
void PoFxActivateComponent(
[in] POHANDLE Handle,
[in] ULONG Component,
[in] ULONG Flags
);
パラメーター
[in] Handle
電源管理フレームワーク (PoFx) を使用したデバイスの登録を表すハンドル。 デバイス ドライバーは、以前に PoFxRegisterDevice ルーチンからこのハンドルを受信しました。
[in] Component
コンポーネントを識別するインデックス。 このパラメーターは、デバイス ドライバーが PoFx にデバイスを登録するために使用したPO_FX_DEVICE構造体の Components 配列へのインデックスです。 Components 配列に N 個の要素が含まれている場合、コンポーネント インデックスの範囲は 0 から N ~ 1 です。
[in] Flags
アクティブ化操作のフラグ。 このメンバーを 0 に設定するか、次のいずれかのフラグPO_FX_FLAG_XXX ビットに設定します。
これら 2 つのフラグ ビットは相互に排他的です。 詳細については、「解説」を参照してください。
戻り値
なし
解説
デバイス ドライバーがデバイス内のコンポーネントにアクセスする前に、ドライバーはまず PoFxActivateComponent を呼び出して、コンポーネントへのアクティブ化参照を取得する必要があります。 コンポーネントがまだアクティブな条件にない場合、この呼び出しはアイドル状態からアクティブ条件への遷移を開始します。 この遷移が完了すると、PoFx はドライバーの ComponentActiveConditionCallback ルーチンを呼び出してドライバーに通知します。 ドライバーは、コンポーネントがアクティブな状態にある場合にのみ、コンポーネント内のハードウェア レジスタにアクセスできます。
PoFxActivateComponent が呼び出されたときにコンポーネントがアクティブな状態にある場合、遷移は必要なく、ComponentActiveConditionCallback ルーチンは呼び出されません。
コンポーネントがアクティブな条件に入った後は、ドライバーがコンポーネントに対する 1 つ以上のアクティブ化参照を保持している限り、アクティブな状態のままになります。 アクティブ化参照を解放するために、ドライバーは PoFxIdleComponent ルーチンを呼び出します。 ドライバーがコンポーネントの最後のアクティブ化参照を解放すると、 PoFxIdleComponent はアクティブな条件からアイドル状態への移行を開始します。 アイドル状態のコンポーネントは、低電力 Fx 状態になる可能性があります。
Flags = がPO_FX_FLAG_BLOCKING場合、PoFxActivateComponent 呼び出しは同期です。 コンポーネントが既にアクティブな状態にある場合、呼び出しはアクティブ化参照カウントをインクリメントし、待機せずに を返します。 それ以外の場合、 PoFxActivateComponent は、コンポーネントがアクティブな条件への切り替えを完了するまで、戻るのを待機します。 この場合、呼び出しが発生したときにコンポーネントがまだ F0 状態でない場合、 PoFxActivateComponent はドライバーの ComponentIdleStateCallback ルーチンを呼び出して F0 への切り替えを開始します。 コンポーネントが F0 状態に入った後、 PoFxActivateComponent はドライバーの ComponentActiveConditionCallback ルーチンを呼び出して、コンポーネントがアクティブな状態であることをドライバーに通知します。 これらのコールバックは 、PoFxActivateComponent の呼び出しと同じスレッドで発生し、 PoFxActivateComponent は ComponentActiveConditionCallback コールバックが返された後にのみを返します。
Flags = がPO_FX_FLAG_ASYNC_ONLY場合、PoFxActivateComponent 呼び出しは非同期です。 コンポーネントが既にアクティブな状態にある場合、呼び出しによってアクティブ化参照カウントがインクリメントされ、 が返されます。 それ以外の場合、 PoFxActivateComponent は ComponentIdleStateCallback (必要に応じて) コールバックと ComponentActiveConditionCallback コールバックを別のスレッドで実行するようにスケジュールし、いずれかのコールバックが発生するのを待たずに を返します。 コールバックは、 PoFxActivateComponent から返される前または後に発生する可能性があります。 ドライバーは ComponentActiveConditionCallback コールバックに依存して、コンポーネントがアクティブな条件への切り替えをいつ完了するかを判断します。
ドライバーは、PoFxActivateComponent 呼び出しが同期か非同期かを気にしないことを示すフラグ = 0 を設定できます。 この場合、PoFx は呼び出しを同期または非同期にするかどうかを決定します。
同じドライバー内の 2 つ以上のコード パスが、特定のコンポーネントに同時にアクセスする必要がある場合があります。 PoFxActivateComponent ルーチンと PoFxIdleComponent ルーチンは、アクティブ化参照カウントを使用して、ドライバーがコンポーネントへのアクセスを一元的に管理しなくても、ドライバーのさまざまな部分がコンポーネントへのアクセスを個別に維持できるようにします。
PoFx は、デバイス内の各コンポーネントのアクティブ化参照数を保持します。 PoFxActivateComponent 呼び出しによってこのカウントが 1 ずつインクリメントされ、PoFxIdleComponent 呼び出しによってカウントが 1 ずつデクリメントされます。 カウントが 0 以外の場合、コンポーネントはアクティブな状態にあるか、アクティブな条件に切り替える処理中です。 カウントが 0 のコンポーネントは、アイドル状態にあるか、アイドル状態に切り替える処理中です。
PoFxActivateComponent 呼び出しによってアクティブ化参照カウントが 0 から 1 に増加すると、PoFxActivateComponent はアイドル状態からアクティブ状態への移行を開始します。 PoFxIdleComponent 呼び出しによってカウントが 1 から 0 に減少すると、PoFxIdleComponent はアクティブな条件からアイドル状態への切り替えを開始します。
PoFx は、アクティブな条件とアイドル状態の間の遷移が発生したときにドライバーに通知します。 ComponentActiveConditionCallback コールバックは、アクティブな条件への遷移をドライバーに通知し、ComponentIdleConditionCallback コールバックは、アイドル状態への遷移をドライバーに通知します。 PoFxActivateComponent または PoFxIdleComponent 呼び出しで、このような遷移を引き起こさずにアクティブ化参照カウントをインクリメントまたはデクリメントするだけで、ドライバーは通知を受け取ることはありません。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 8以降で使用できます。 |
| 対象プラットフォーム | ユニバーサル |
| Header | wdm.h |
| Library | Ntoskrnl.lib |
| [DLL] | Ntoskrnl.exe |
| IRQL | <= DISPATCH_LEVEL |