Функция 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
Указатель на целевой 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 возвращает одно из следующих элементов:
Код возврата | Описание |
---|---|
|
IRP отправлено. |
|
Подпрограмме не удалось выделить IRP. |
|
MinorFunction не означает допустимый дополнительный код IRP мощности. |
Комментарии
Владелец политики питания устройства вызывает эту подпрограмму для отправки ожидания, пробуждения, запроса или настройки 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) |