PoRequestPowerIrp 関数 (wdm.h)
PoRequestPowerIrp ルーチンは、電源 IRP を割り当て、指定したデバイスのデバイス スタック内の最上位ドライバーに送信します。
構文
NTSTATUS PoRequestPowerIrp(
[in] PDEVICE_OBJECT DeviceObject,
[in] UCHAR MinorFunction,
[in] POWER_STATE PowerState,
[in, optional] PREQUEST_POWER_COMPLETE CompletionFunction,
[in, optional] __drv_aliasesMem PVOID Context,
[out] PIRP *Irp
);
パラメーター
[in] DeviceObject
IRP のターゲット DEVICE_OBJECT へのポインター。 Windows 2000 以降のバージョンの Windows では、このパラメーターは物理デバイス オブジェクト (PDO) または機能デバイス オブジェクト (FDO) を指すことができます。 Windows 98/Me では、このパラメーターは基になるデバイスの PDO を指す必要があります。
[in] MinorFunction
IRP_MN_QUERY_POWER、IRP_MN_SET_POWER、またはIRP_MN_WAIT_WAKEのいずれかのマイナー電源 IRP コードを指定します。
[in] PowerState
IRP で渡 すPOWER_STATE 値を指定します。 IRP_MN_SET_POWERとIRP_MN_QUERY_POWERでは、要求された新しいデバイスの電源状態を指定します。 使用できる値は 、DEVICE_POWER_STATE 値です。
IRP_MN_WAIT_WAKEの場合は、デバイスのスリープ解除を許可する最小 (最小電力) のシステム電源状態を指定します。 使用できる値は 、SYSTEM_POWER_STATE 値です。
[in, optional] CompletionFunction
呼び出し元の PowerCompletion コールバック ルーチンへのポインター。 I/O マネージャーは、IRP が完了すると、このルーチンを呼び出します。 このパラメーターは省略可能であり、PowerCompletion コールバック ルーチンが必要ない場合は NULL に設定できます。
[in, optional] Context
PowerCompletion コールバックに渡される呼び出し元が指定したコンテキストへのポインター。 呼び出し元がシステムの set-power IRP に応答してデバイスの set-power IRP を要求すると、 コンテキスト には、要求をトリガーしたシステム セット電源 IRP が含まれている必要があります。
[out] Irp
PoRequestPowerIrp が割り当てる IRP へのポインターを返す、呼び出し元が指定した変数へのポインター。 MinorFunction パラメーターが IRP_MN_WAIT_WAKE に設定されている場合にのみ、Irp の値を指定します。 それ以外の場合、PoRequestPowerIrp が返される前に IRP が完了し、このパラメーターが既に破棄されているメモリを指す可能性があるため、このパラメーターは常に NULL にする必要があります。
戻り値
PoRequestPowerIrp は、次のいずれかを返します。
| リターン コード | 説明 |
|---|---|
|
IRP が送信されました。 |
|
ルーチンは IRP を割り当てませんでした。 |
|
MinorFunction は、有効なマイナー電源 IRP コードを示していません。 |
注釈
デバイス電源ポリシーの所有者は、待機/スリープ解除、クエリ、または set-power IRP を送信するには、このルーチンを呼び出します。
ドライバーは、IoAllocateIrp ではなく PoRequestPowerIrp を呼び出して、マイナー IRP コード IRP_MN_SET_POWER、IRP_MN_QUERY_POWER、またはIRP_MN_WAIT_WAKEを持つ power IRP を割り当てて送信します。 (ドライバーは、マイナー IRP コード IRP_MN_POWER_SEQUENCEを使用して電源 IRP を送信するには、IoAllocateIrp を呼び出す必要があります。
PoRequestPowerIrp がSTATUS_PENDINGの状態値を返した場合、ルーチンは正常にデバイス電源 IRP を割り当て、デバイスのデバイス スタックの最上位に送信しました。 バス ドライバーとその他のすべてのドライバーが IRP を完了し、I/O マネージャーが IRP をデバイス スタックに渡すと、ドライバーによって設定されたすべての IoCompletion ルーチンを呼び出した後、I/O マネージャーは PowerCompletion ルーチンを呼び出し、指定された Context 値をこのルーチンに渡します。 PoRequestPowerIrp がSTATUS_PENDING以外の状態を返した場合、ルーチンはデバイス電源 IRP を送信せず、PowerCompletion ルーチンは呼び出されません。
PowerCompletion ルーチンは、他のすべてのドライバーが IRP を完了した後、IRP の送信者が必要とする追加のタスクを実行します。 IRP を解放する必要はありません。電源マネージャーが行います。 Windows 2000 以降のバージョンの Windows では、 PowerCompletion ルーチンは IRQL = PASSIVE_LEVEL または IRQL = DISPATCH_LEVELで呼び出すことができます。 Windows 98/Me では、 PowerCompletion ルーチンは常に IRQL = PASSIVE_LEVEL で呼び出され、ドライバーは IRQL = PASSIVE_LEVELで IRP を完了する必要があります。
デバイスの電源ポリシー所有者は 、PoRequestPowerIrp を呼び出して、システム クエリまたは set-power IRP を受信したときにデバイス クエリまたは set-power IRP を送信します。 ドライバーは、システム IRP で IoCompletion ルーチンを設定し、システム IRP を次の下位ドライバーに渡す必要があります。 IoCompletion ルーチンは、PoRequestPowerIrp を呼び出してデバイス IRP を送信し、Context パラメーターでシステム IRP を渡します。 Context パラメーターは、その後、デバイス IRP の PowerCompletion ルーチンに渡されます。 PowerCompletion ルーチンでは、ドライバーはシステム IRP を完了できます。 詳細については、「 デバイスの電源状態のIRP_MN_QUERY_POWERまたはIRP_MN_SET_POWERの送信 」および「 待機/スリープ解除コールバック ルーチン」を参照してください。
ドライバーは、返された Irp を 使用して 、IRP_MN_WAIT_WAKE IRP を取り消すことができます。 他の種類の電源 IRP を要求しているドライバーは、このパラメーターに NULL を 渡す必要があります。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows 2000 以降で使用できます。 |
| 対象プラットフォーム | ユニバーサル |
| Header | wdm.h (Wdm.h、Ntddk.h、Ntifs.h を含む) |
| Library | NtosKrnl.lib |
| [DLL] | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |
| DDI コンプライアンス規則 | HwStorPortProhibitedDDIs(storport), MarkDevicePower(wdm), PowerDownFail(wdm), PowerUpFail(wdm), RequestedPowerIrp(wdm) |