Функция PoCallDriver (ntifs.h)

Статья
07/11/2023

Подпрограмма PoCallDriver передает IRP питания следующему ниже драйверу в стеке устройств. (Только Windows Server 2003, Windows XP и Windows 2000.)

Синтаксис

NTSTATUS PoCallDriver(
  [in]      PDEVICE_OBJECT        DeviceObject,
  [in, out] __drv_aliasesMem PIRP Irp
);

Параметры

[in] DeviceObject

Указатель на созданный драйвером DEVICE_OBJECT , на который будет направляться IRP.

[in, out] Irp

Указатель на IRP.

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

PoCallDriver возвращает STATUS_SUCCESS, чтобы указать на успешное выполнение. Он возвращает STATUS_PENDING, если он поставил IRP в очередь.

Начиная с Windows Vista, драйверы должны вызывать IoCallDriver, а не PoCallDriver , чтобы передать IRP питания следующему более низкому драйверу. Однако в Windows Server 2003, Windows XP и Windows 2000 драйверы должны вызывать PoCallDriver, а не IoCallDriver , чтобы передать IRP питания следующему ниже драйверу. В Windows Server 2003, Windows XP и Windows 2000 драйверы также должны вызывать PoStartNextPowerIrp перед вызовом PoCallDriver.

Драйвер, требующий нового IRP, должен вызвать PoRequestPowerIrp. Драйвер не должен выделять собственный IRP питания.

При передаче IRP питания в драйвер следующего уровня ниже вызывающий объект должен использовать IoSkipCurrentIrpStackLocation или IoCopyCurrentIrpStackLocationToNext , чтобы задать расположение стека IRP, а затем вызвать PoCallDriver. Используйте IoCopyCurrentIrpStackLocationToNext , если для обработки IRP требуется задать подпрограмму IoCompletion , или IoSkipCurrentStackLocation , если подпрограмма IoCompletion не требуется.

Когда устройство включается, его драйверы должны настроить процедуры IoCompletion для выполнения задач запуска (инициализация устройства, восстановление контекста и т. д.) после того, как драйвер шины настроит устройство в рабочее состояние. Настройте процедуры IoCompletion перед вызовом PoCallDriver.

Когда устройство отключается, его драйверы должны выполнять необходимые задачи выключения питания перед передачей IRP следующему более низкому драйверу. После того как IRP достигнет водителя автобуса, устройство будет выключено, и его водители больше не будут иметь к нему доступ. В Windows Server 2003, Windows XP и Windows 2000 подпрограмма IoCompletion , связанная с выключенным IRP, требуется только для вызова PoStartNextPowerIrp.

Одновременно в системе может быть активна только одна вхощвающая функция IRP. При передаче IRP выключения для устройства, которому требуется текущий ввод (иными словами, в объекте устройства установлен флаг DO_POWER_INRUSH), PoCallDriver проверяет, активен ли уже другой входной IRP. Если это так, PoCallDriver помещает текущий IRP в очередь для обработки после завершения предыдущего IRP, а затем возвращает STATUS_PENDING. Дополнительные сведения о входных IRP см. в разделе Настройка флагов объектов устройства для управления питанием.

Если запрос IRP_MN_SET_POWER или IRP_MN_QUERY_POWER уже активен для DeviceObject, PoCallDriver помещает его в очередь и возвращает STATUS_PENDING.

В Windows 2000 и более поздних версиях драйверы с возможностью просмотра (флаг DO_POWER_PAGABLE установлен в объекте устройства) должны вызывать PoCallDriver по адресу IRQL = PASSIVE_LEVEL. Драйверы, которые не могут быть выгружены на страницы (DO_POWER_PAGABLE не заданы в объекте устройства) или требуют встраивки (DO_POWER_INRUSH задано в объекте устройства), могут вызывать PoCallDriver по адресу IRQL = PASSIVE_LEVEL или DISPATCH_LEVEL.

В Windows 98/Me все драйверы вызывают PoCallDriver по адресу IRQL = PASSIVE_LEVEL.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000.
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	См. раздел "Примечания".
Правила соответствия DDI	CompleteRequestStatusCheck(wdm), CompletionRoutineRegistered(wdm), DeleteDevice(wdm), ForwardedAtBadIrql(wdm), ForwardedAtBadIrqlAllocate(wdm), ForwardedAtBadIrqlFsdAsync(wdm), ForwardedAtBadIrqlFsdSync(wdm), HwStorPortProhibitedDDIs(storport), IoAllocateForward(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildFsdForward(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), IoSetCompletionRoutineExCheck(wdm), IrpProcessingComplete(wdm), LowerDriverReturn(wdm), MarkDevicePower(wdm), MarkQueuedIrps(wdm), MarkIrpPending(wdm), MarkIrpPending2(wdm), MarkPower(wdm) , MarkPowerDown(wdm), MarkQueryRelations(wdm), MarkStartDevice(wdm), PendedCompletedRequest(wdm), PendedCompletedRequest2(wdm), PendedCompletedRequest3(wdm), PendedCompletedRequestEx(wdm), PnpIrpCompletion(wdm), PowerDownFail(wdm), PowerUpFail(wdm), RemoveLockForward(wdm), RemoveLockForward2(wdm), RemoveLockForwardDeviceControl(wdm), RemoveLockForwardDeviceControl2(wdm), RemoveLockForwardDeviceControlInternal(wdm), RemoveLockForwardDeviceControlInternal2(wdm), RemoveLockForwardRead(wdm), RemoveLockForwardRead2(wdm), RemoveLockForwardWrite(wdm), RemoveLockForwardWrite2(wdm), RemoveLockMnRemove2(wdm), RemoveLockMnSurpriseRemove(wdm), RemoveLockQueryMnRemove(wdm), TargetRelationNeedsRef(wdm), WmiForward(wdm)