PoCallDriver-Funktion (ntifs.h)

Artikel
07/11/2023

Die PoCallDriver-Routine übergibt einen Energie-IRP an den nächstniedrigen Treiber im Gerätestapel. (Nur Windows Server 2003, Windows XP und Windows 2000.)

Syntax

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

Parameter

[in] DeviceObject

Ein Zeiger auf die vom Treiber erstellte DEVICE_OBJECT , an die das IRP weitergeleitet werden soll.

[in, out] Irp

Ein Zeiger auf eine IRP.

Rückgabewert

PoCallDriver gibt STATUS_SUCCESS zurück, um den Erfolg anzugeben. Es gibt STATUS_PENDING zurück, wenn die IRP in die Warteschlange gestellt wurde.

Hinweise

Ab Windows Vista sollten Treiber IoCallDriver und nicht PoCallDriver aufrufen, um einen Energie-IRP an den nächstniedrigen Treiber zu übergeben. Unter Windows Server 2003, Windows XP und Windows 2000 müssen Treiber jedoch PoCallDriver und nicht IoCallDriver aufrufen, um eine Energie-IRP an den nächstniedrigen Treiber zu übergeben. Unter Windows Server 2003, Windows XP und Windows 2000 müssen Treiber auch PoStartNextPowerIrp aufrufen, bevor PoCallDriver aufgerufen wird.

Ein Treiber, der eine neue IRP erfordert, sollte PoRequestPowerIrp aufrufen. Ein Treiber darf keine eigenen Leistungs-IRP zuordnen.

Wenn ein Energie-IRP an den nächstniedrigen Treiber übergeben wird, sollte der Aufrufer IoSkipCurrentIrpStackLocation oder IoCopyCurrentIrpStackLocationToNext verwenden, um den IRP-Stapelspeicherort festzulegen, und dann PoCallDriver aufrufen. Verwenden Sie IoCopyCurrentIrpStackLocationToNext , wenn für die Verarbeitung des IRP das Festlegen einer IoCompletion-Routine erforderlich ist, oder IoSkipCurrentStackLocation , wenn keine IoCompletion-Routine erforderlich ist.

Wenn ein Gerät eingeschaltet wird, müssen dessen Treiber IoCompletion-Routinen zum Ausführen von Startaufgaben (Initialisieren des Geräts, Wiederherstellen des Kontexts usw.) festlegen, nachdem der Bustreiber das Gerät in den Betriebszustand versetzt hat. Legen Sie IoCompletion-Routinen fest, bevor Sie PoCallDriver aufrufen.

Wenn ein Gerät heruntergefahren wird, müssen dessen Treiber die erforderlichen Powerdown-Aufgaben ausführen, bevor das IRP an den nächstniedrigen Treiber übergeben wird. Nachdem der IRP den Bustreiber erreicht hat, wird das Gerät ausgeschaltet, und seine Treiber haben keinen Zugriff mehr darauf. Unter Windows Server 2003, Windows XP und Windows 2000 ist eine IoCompletion-Routine , die einem Powerdown-IRP zugeordnet ist, nur erforderlich, um PoStartNextPowerIrp aufzurufen.

Es kann jeweils nur ein Inrush-IRP im System aktiv sein. Beim Übergeben eines Power-Up-IRP für ein Gerät, das Einen Einschaltstrom benötigt (d. h. das DO_POWER_INRUSH-Flag ist im Geräteobjekt festgelegt), überprüft PoCallDriver , ob bereits eine andere Einschalt-IRP aktiv ist. Wenn dies der Grund ist, stellt PoCallDriver die aktuelle IRP für die Verarbeitung in die Warteschlange, nachdem die vorherige IRP abgeschlossen wurde, in die Warteschlange und gibt dann STATUS_PENDING zurück. Weitere Informationen zu Inrush-IRPs finden Sie unter Festlegen von Geräteobjektflags für die Energieverwaltung.

Wenn eine IRP_MN_SET_POWER - oder IRP_MN_QUERY_POWER-Anforderung für DeviceObject bereits aktiv ist, stellt PoCallDriver diese IRP in die Warteschlange und gibt STATUS_PENDING zurück.

Auf Windows 2000- und höher-Systemen müssen Auslagerungstreiber (das DO_POWER_PAGABLE-Flag ist im Geräteobjekt festgelegt) PoCallDriver unter IRQL = PASSIVE_LEVEL aufrufen. Treiber, die nicht ausgelagert werden können (DO_POWER_PAGABLE im Geräteobjekt nicht festgelegt ist) oder die Inrushstrom erfordern (DO_POWER_INRUSH im Geräteobjekt festgelegt ist), können PoCallDriver unter IRQL = PASSIVE_LEVEL oder DISPATCH_LEVEL aufrufen.

Unter Windows 98/Me rufen alle Treiber PoCallDriver unter IRQL = PASSIVE_LEVEL auf.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 2000.
Zielplattform	Universell
Header	ntifs.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Weitere Informationen finden Sie im Abschnitt mit den Hinweisen.
DDI-Complianceregeln	CompleteRequestStatusCheck(wdm), CompletionRoutineRegistered(wdm), DeleteDevice(wdm), ForwardedAtBadIrql(wdm), ForwardedAtBadIrqlAllocate(wdm), ForwardedAtBadIrqlFsdAsync(wdm), ForwardedAtBadIrqlFsdSync(wdm), HwStorPortProhibitedDIs(storport), IoAllocateForward(wdm), IoAllocateIrpSignalEventInCompletionTimeout(wdm), IoBuildDeviceControlWait(wdm), IoBuildDeviceControlWaitTimeout(wdm), IoBuildFsdForward(wdm), IoBuildSynchronousFsdRequestWait(wdm), IoBuildSynchronousFsdRequestWaitTimeout(wdm), IoSetCompletionRoutineExCheck(wdm), IrpProcessingComplete(wdm), LowerDriverReturn(wdm), MarkDevicePower(wdm), MarkingQueuedIrps(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)