REQUEST_POWER_COMPLETE Rückruffunktion (wdm.h)

Artikel
02/27/2024

Die PowerCompletion-Rückrufroutine schließt die Verarbeitung einer Energie-IRP ab.

Syntax

REQUEST_POWER_COMPLETE RequestPowerComplete;

void RequestPowerComplete(
  [in]           PDEVICE_OBJECT DeviceObject,
  [in]           UCHAR MinorFunction,
  [in]           POWER_STATE PowerState,
  [in, optional] PVOID Context,
  [in]           PIO_STATUS_BLOCK IoStatus
)
{...}

Parameter

[in] DeviceObject

Ein Zeiger auf das Ziel DEVICE_OBJECT für die abgeschlossene Leistungs-IRP.

[in] MinorFunction

Gibt den Nebenfunktionscode im Power-IRP an. Weitere Informationen finden Sie in der Liste der unterstützten IRP_MN_XXX-Codes im Abschnitt Hinweise.

[in] PowerState

Gibt den Energiezustand des Geräts oder den Systemleistungszustand an, der an die PoRequestPowerIrp-Routine übergeben wurde.

[in, optional] Context

Ein Zeiger auf den Kontext, der an PoRequestPowerIrp übergeben wurde.

[in] IoStatus

Ein Zeiger auf die IO_STATUS_BLOCK-Struktur für die abgeschlossene IRP.

Rückgabewert

Keine

Bemerkungen

Ein Treiber, der ein Energie-IRP sendet, muss möglicherweise zusätzliche Aufgaben ausführen, nachdem alle anderen Treiber die IRP abgeschlossen haben. Wenn ja, sollte der sendende Treiber während des Aufrufs der PoRequestPowerIrp-Routine, die den IRP zuordnet, eine PowerCompletion-Rückrufroutine registrieren.

Die PowerCompletion-Rückrufroutine eines Treibers wird nur für IRP_MJ_POWER IRPs verwendet, die über kleinere IRP-Codes von IRP_MN_SET_POWER, IRP_MN_QUERY_POWER und IRP_MN_WAIT_WAKE verfügen. Weitere Informationen finden Sie unter Senden von IRP_MN_QUERY_POWER oder IRP_MN_SET_POWER für Gerätestromzustände und Warte-/Aktivierungsrückrufroutinen.

Der E/A-Manager ruft die PowerCompletion-Routine des sendenden Treibers erst auf, nachdem der E/A-Manager alle IoCompletion-Routinen aufgerufen hat, die von anderen Treibern festgelegt wurden, während sie den IRP im Stapel übergeben haben. Die PowerCompletion-Routine führt alle zusätzlichen Aufgaben aus, die der Absender des IRP benötigt, nachdem alle anderen Treiber den IRP abgeschlossen haben. Die PowerCompletion-Routine sollte die IRP nicht freigeben. Dies wird vom Power Manager ausgeführt.

Die PowerCompletion-Routine wird unter IRQL = PASSIVE_LEVEL oder IRQL = DISPATCH_LEVEL aufgerufen.

Beispiele

Um eine PowerCompletion-Rückrufroutine zu definieren, müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückrufroutine identifiziert, die Sie definieren. Windows bietet eine Reihe von Rückruffunktionstypen für Treiber. Das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen hilft der Codeanalyse für Treiber, der statischen Treiberüberprüfung (Static Driver Verifier , SDV) und anderen Überprüfungstools, Fehler zu finden, und es ist eine Voraussetzung für das Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine PowerCompletion-Rückrufroutine mit dem Namen MyPowerCompletionzu definieren, verwenden Sie den typ REQUEST_POWER_COMPLETE, wie in diesem Codebeispiel gezeigt:

REQUEST_POWER_COMPLETE MyPowerCompletion;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
VOID
  MyPowerCompletion(
    PDEVICE_OBJECT DeviceObject,
    UCHAR MinorFunction,
    POWER_STATE PowerState,
    PVOID Context,
    PIO_STATUS_BLOCK IoStatus
    )
  {
      // Function body
  }

Der REQUEST_POWER_COMPLETE Funktionstyp ist in der Wdm.h-Headerdatei definiert. Um Fehler beim Ausführen der Codeanalysetools genauer zu identifizieren, fügen Sie die _Use_decl_annotations_ Anmerkung ihrer Funktionsdefinition hinzu. Die _Use_decl_annotations_ Anmerkung stellt sicher, dass die Anmerkungen verwendet werden, die auf den REQUEST_POWER_COMPLETE Funktionstyp in der Headerdatei angewendet werden. Weitere Informationen zu den Anforderungen für Funktionsdeklarationen finden Sie unter Deklarieren von Funktionen mithilfe von Funktionsrollentypen für WDM-Treiber. Informationen zu _Use_decl_annotations_finden Sie unter Verhalten von Funktionen mit Anmerkungen.

Anforderungen

Anforderung	Wert
Zielplattform	Desktop
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Wird unter IRQL <= DISPATCH_LEVEL aufgerufen (siehe Abschnitt "Hinweise").