PoCallDriver-Funktion (wdm.h)

Artikel
08/08/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 eingereiht wurde.

Hinweise

Ab Windows Vista sollten Treiber IoCallDriver und nicht PoCallDriver aufrufen, um eine 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, windows 2000, müssen Treiber auch PoStartNextPowerIrp aufrufen, bevor PoCallDriver aufgerufen wird.

Ein Treiber, der ein neues IRP erfordert, sollte PoRequestPowerIrp aufrufen. Ein Treiber darf keine eigene Leistungs-IRP zuordnen.

Wenn Sie eine Energie-IRP an den nächstniedrigen Treiber übergeben, 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 seine Treiber IoCompletion-Routinen einrichten, um Startaufgaben (Initialisieren des Geräts, Wiederherstellen des Kontexts usw.) auszuführen, nachdem der Bustreiber das Gerät im Betriebszustand festgelegt hat. Legen Sie IoCompletion-Routinen fest, bevor Sie PoCallDriver aufrufen.

Wenn ein Gerät heruntergefahren wird, müssen seine Treiber die erforderlichen Herunterschaltvorgänge ausführen, bevor sie den IRP an den nächstniedrigen Treiber übergeben. Nachdem das 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 Herunterschalt-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 Einschaltstrom benötigt (d. h. das DO_POWER_INRUSH Flag ist im Geräteobjekt festgelegt), überprüft PoCallDriver , ob bereits ein anderer Inrush-IRP aktiv ist. Wenn dies der Grund ist, stellt PoCallDriver den aktuellen IRP zur Behandlung nach Abschluss des vorherigen IRP 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 bereits für DeviceObject aktiv ist, wird dieser IRP von PoCallDriver in die Warteschlange gestellt und STATUS_PENDING zurückgegeben.

Auf Systemen unter Windows 2000 und höher müssen ausgelagerte Treiber (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 ist im Geräteobjekt nicht festgelegt) oder die Inrush-Strom erfordern (DO_POWER_INRUSH ist im Geräteobjekt festgelegt), 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)	Verfügbar ab Windows 2000.
Zielplattform	Universell
Header	wdm.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)