PoRequestPowerIrp 함수(wdm.h)

아티클
08/08/2023

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 콜백 루틴에 대한 포인터입니다. IRP가 완료되면 I/O 관리자가 이 루틴을 호출합니다. 이 매개 변수는 선택 사항이며 PowerCompletion 콜백 루틴이 필요하지 않은 경우 NULL로 설정할 수 있습니다.

[in, optional] Context

PowerCompletion 콜백에 전달할 호출자가 제공한 컨텍스트에 대한 포인터입니다. 호출자가 시스템 설정 전원 IRP에 대한 응답으로 디바이스 설정 전원 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 코드를 의미하지 않습니다.

설명

디바이스 전원 정책 소유자는 이 루틴을 호출하여 대기/절전 모드 해제, 쿼리 또는 전원 설정 IRP를 보냅니다.

드라이버는 IoAllocateIrp가 아닌 PoRequestPowerIrp를 호출하여 부 IRP 코드 IRP_MN_SET_POWER, IRP_MN_QUERY_POWER또는IRP_MN_WAIT_WAKE 있는 전원 IRP를 할당하고 보냅니다. (드라이버가 IoAllocateIrp 를 호출하여 IRP_MN_POWER_SEQUENCE 부 IRP 코드가 있는 전원 IRP를 보내야 합니다.)

PoRequestPowerIrp이 STATUS_PENDING 상태 값을 반환하는 경우 루틴은 디바이스 전원 IRP를 성공적으로 할당하고 디바이스에 대한 디바이스 스택의 맨 위로 보냈습니다. 버스 드라이버와 다른 모든 드라이버가 IRP를 완료하고 I/O 관리자가 IRP를 디바이스 스택 아래로 전달할 때 드라이버가 설정한 모든 IoCompletion 루틴을 호출한 후 I/O 관리자는 PowerCompletion 루틴을 호출하고 이 루틴에 지정된 컨텍스트 값을 전달합니다. PoRequestPowerIrp이 STATUS_PENDING 이외의 상태 반환하는 경우 루틴이 디바이스 전원 IRP를 보내지 않았고 PowerCompletion 루틴이 호출되지 않습니다.

PowerCompletion 루틴은 다른 모든 드라이버가 IRP를 완료한 후 IRP 보낸 사람에게 필요한 추가 작업을 수행합니다. IRP를 해제할 필요가 없습니다. 이 작업을 수행합니다. Windows 2000 이상 버전의 Windows에서는 IRQL = PASSIVE_LEVEL 또는 IRQL = DISPATCH_LEVEL PowerCompletion 루틴을 호출할 수 있습니다. Windows 98/Me에서 PowerCompletion 루틴은 항상 IRQL = PASSIVE_LEVEL 호출되며 드라이버는 IRQL = PASSIVE_LEVEL IRP를 완료해야 합니다.

디바이스 전원 정책 소유자는 PoRequestPowerIrp 를 호출하여 시스템 쿼리 또는 전원 설정 IRP를 수신할 때 디바이스 쿼리 또는 전원 설정 IRP를 보냅니다. 드라이버는 시스템 IRP에서 IoCompletion 루틴을 설정하고 시스템 IRP를 다음 하위 드라이버에 전달해야 합니다. IoCompletion 루틴은 PoRequestPowerIrp를 호출하여 디바이스 IRP를 보내고 Context 매개 변수에서 시스템 IRP를 전달합니다. 컨텍스트 매개 변수는 이후에 디바이스 IRP에 대한 PowerCompletion 루틴에 전달됩니다. PowerCompletion 루틴에서 드라이버는 시스템 IRP를 완료할 수 있습니다. 자세한 내용은 디바이스 전원 상태 및 대기/절전 모드 해제 콜백 루틴 에 대한 IRP_MN_QUERY_POWER 또는 IRP_MN_SET_POWER 보내기를 참조하세요.

드라이버는 반환된 Irp 를 사용하여 IRP_MN_WAIT_WAKE IRP를 취소할 수 있습니다. 다른 유형의 전원 IRP를 요청하는 드라이버는 이 매개 변수에 대해 NULL 을 전달해야 합니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows 2000부터 사용할 수 있습니다.
대상 플랫폼	유니버설
헤더	wdm.h(Wdm.h, Ntddk.h, Ntifs.h 포함)
라이브러리	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL
DDI 규정 준수 규칙	HwStorPortProhibitedDDIs(storport), MarkDevicePower(wdm), PowerDownFail(wdm), PowerUpFail(wdm), RequestedPowerIrp(wdm)