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

リターン コード 説明
STATUS_PENDING
 IRP が送信されました。
STATUS_INSUFFICIENT_RESOURCES
 ルーチンは IRP を割り当てませんでした。
STATUS_INVALID_PARAMETER_2
 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)

こちらもご覧ください

IO_STATUS_BLOCK

IRP

IRP_MN_POWER_SEQUENCE

IRP_MN_QUERY_POWER

IRP_MN_SET_POWER

IRP_MN_WAIT_WAKE

IoAllocateIrp

PoStartNextPowerIrp

PowerCompletion