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

Статья
08/08/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 помещает этот IRP в очередь и возвращает 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.
Целевая платформа	Универсальное
Верхняя часть	wdm.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)