Функция PoRequestPowerIrp (wdm.h)

Статья
03/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

Указатель на целевой DEVICE_OBJECT для IRP. В Windows 2000 и более поздних версиях Windows этот параметр может указывать на объект физического устройства (PDO) или объект функционального устройства (FDO). В Windows 98/Me этот параметр должен указывать на PDO базового устройства.

[in] MinorFunction

Указывает один из следующих незначительных кодов IRP питания: IRP_MN_QUERY_POWER, IRP_MN_SET_POWER или IRP_MN_WAIT_WAKE.

[in] PowerState

Задает значение POWER_STATE , передаваемое в IRP. Для IRP_MN_SET_POWER и IRP_MN_QUERY_POWER укажите запрошенное новое состояние питания устройства. Возможные значения— DEVICE_POWER_STATE значения.

Для IRP_MN_WAIT_WAKE укажите наименьшее (наименьшее ) состояние питания системы , из которого устройству должно быть разрешено пробуждение системы. Возможные значения— SYSTEM_POWER_STATE значения.

[in, optional] CompletionFunction

Указатель на подпрограмму обратного вызова PowerCompletion вызывающего абонента. Диспетчер операций ввода-вывода вызывает эту подпрограмму после завершения IRP. Этот параметр является необязательным и может иметь значение NULL , если подпрограмма обратного вызова PowerCompletion не требуется.

[in, optional] Context

Указатель на предоставленный вызывающим объектом контекст для передачи обратному вызову PowerCompletion . Когда вызывающий объект запрашивает IRP с набором питания устройства в ответ на IRP набора системных наборов, контекст должен содержать системный набор IRP, который активировал запрос.

[out] Irp

Указатель на переменную, предоставленную вызывающей стороны, в которой PoRequestPowerIrp возвращает указатель на выделенный им IRP. Укажите значение для Irp , только если для параметра MinorFunction задано значение IRP_MN_WAIT_WAKE. В противном случае этот параметр всегда должен иметь значение NULL , так как IRP может быть завершен до возврата PoRequestPowerIrp , в результате чего этот параметр указывает на память, которая уже была удалена.

Возвращаемое значение

PoRequestPowerIrp возвращает одно из следующих элементов:

Код возврата	Описание
STATUS_PENDING	IRP отправлено.
STATUS_INSUFFICIENT_RESOURCES	Подпрограмме не удалось выделить IRP.
STATUS_INVALID_PARAMETER_2	MinorFunction не означает допустимый дополнительный код IRP мощности.

Драйвер вызывает PoRequestPowerIrp, а не IoAllocateIrp, чтобы выделить и отправить IRP с незначительным кодом IRP IRP_MN_SET_POWER, IRP_MN_QUERY_POWER или IRP_MN_WAIT_WAKE. (Драйвер должен вызвать IoAllocateIrp , чтобы отправить IRP питания с незначительным кодом IRP IRP_MN_POWER_SEQUENCE.)

Если PoRequestPowerIrp возвращает значение состояния STATUS_PENDING, подпрограмма успешно выделила IRP питания устройства и отправила его в верхнюю часть стека устройств для устройства. После того как водитель автобуса и все остальные водители завершили IRP, а диспетчер операций ввода-вывода вызвал все процедуры IoCompletion , заданные водителями при передаче IRP в стек устройств, диспетчер операций ввода-вывода вызывает подпрограмму PowerCompletion и передает ей указанное значение Контекста . Если 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, а драйверы должны выполнять irp в IRQL = PASSIVE_LEVEL.

Владелец политики управления питанием устройства вызывает PoRequestPowerIrp , чтобы отправить запрос устройства или установить IRP при получении системного запроса или настройки IRP питания. Драйвер должен задать подпрограмму IoCompletion в системном IRP и передать системный IRP следующему драйверу ниже. Подпрограмма IoCompletion вызывает PoRequestPowerIrp для отправки IRP устройства, передавая системный IRP в параметре Context . Затем параметр Context передается в подпрограмму PowerCompletion для IRP устройства. В подпрограмме 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	HwStorPortProhibitedDIs(storport), MarkDevicePower(wdm), PowerDownFail(wdm), PowerUpFail(wdm), RequestedPowerIrp(wdm)