PoRegisterPowerSettingCallback-Funktion (wdm.h)

Artikel
03/08/2023

Die PoRegisterPowerSettingCallback-Routine registriert eine Rückrufroutine für die Energieeinstellung, um Benachrichtigungen über Änderungen in der angegebenen Energieeinstellung zu erhalten.

Syntax

NTSTATUS PoRegisterPowerSettingCallback(
  [in, optional] PDEVICE_OBJECT          DeviceObject,
  [in]           LPCGUID                 SettingGuid,
  [in]           PPOWER_SETTING_CALLBACK Callback,
  [in, optional] PVOID                   Context,
  [out]          PVOID                   *Handle
);

Parameter

[in, optional] DeviceObject

Ein Zeiger auf eine DEVICE_OBJECT Struktur, die dem Aufrufer dieser Routine zugeordnet ist. Dieser Parameter ist optional. Es wird intern nur zu Debugzwecken verwendet. Wenn dieser Parameter nicht angegeben wird, muss er auf NULL festgelegt werden.

[in] SettingGuid

Ein Zeiger auf die GUID, die die Energieeinstellung für diese Registrierung darstellt. Wenn sich die angegebene Energieeinstellung ändert, ruft der Power Manager die Rückrufroutine auf, um den Treiber über die Änderung zu benachrichtigen und den neuen Wert der Einstellung anzugeben. Weitere Informationen finden Sie in den Hinweisen.

[in] Callback

Ein Zeiger auf eine vom Aufrufer implementierte Rückrufroutine für die Energieeinstellung, die der Power Manager aufruft, wenn sich die angegebene Energieeinstellung ändert. Den funktionalen Prototyp für die Rückrufroutine finden Sie unter Power-Setting Callback.

[in, optional] Context

Ein Zeiger auf den Kontext für die Rückrufroutine. Dieser Parameter ist optional. Sie wird bereitgestellt, damit ein Treiber- oder Gerätekontext an die Rückrufroutine übergeben werden kann. Wenn dieser Parameter nicht verwendet wird, muss er auf NULL festgelegt werden.

[out] Handle

Ein Handle, das der Power Manager verwendet, um die Rückrufroutine darzustellen. Ein Treiber muss dieses Handle anschließend in einem Aufruf von PoUnregisterPowerSettingCallback bereitstellen, um die Registrierung der Rückrufroutine aufzuheben.

Rückgabewert

PoRegisterPowerSettingCallback gibt eine der folgenden Rückgaben zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	Die Routine hat die Rückrufroutine registriert.
STATUS_INSUFFICIENT_RESOURCES	Die Routine konnte die Systemressourcen nicht zuordnen, die zum Registrieren der Rückrufroutine erforderlich sind.

Hinweise

Ein Treiber ruft PoRegisterPowerSettingCallback auf, um eine Rückrufroutine beim Power Manager zu registrieren. Der Energie-Manager ruft anschließend diese Rückrufroutine auf, um den Treiber zu benachrichtigen, nachdem die angegebene Energieeinstellung geändert wurde. Darüber hinaus initialisiert der Power-Manager die Energieeinstellung des Treibers, indem er sofort die Rückrufroutine aufruft und den aktuellen Wert der Energieeinstellung übergibt. Der Energie-Manager initialisiert die Energieeinstellung des Treibers auf diese Weise, unabhängig davon, ob sich die Energieeinstellung tatsächlich geändert hat.

Ein Treiber sollte PoRegisterPowerSettingCallback für jede Energieeinstellung aufrufen, die der Treiber überwachen muss. Treiber sollten diese Routine während der Initialisierung in ihrer DriverEntry-Routine aufrufen. In der Regel übergeben die meisten Treiber einen Zeiger auf eine Geräteerweiterung im Context-Parameter .

Um die Registrierung eines Powersetting-Rückrufs aufzuheben, rufen Sie die PoUnregisterPowerSettingCallback-Routine auf.

In der Regel sollten Kernel-Mode kmDF-Treiber (Driver Framework) PoRegisterPowerSettingCallback von ihrer EvtDeviceSelfManagedIoInit-Rückruffunktion aufrufen und PoUnregisterPowerSettingCallback von ihrer EvtDeviceSelfManagedIoCleanup-Rückruffunktion aufrufen. Diese Treiber sollten PoRegisterPowerSettingCallback nicht über ihre Rückruffunktion EvtDriverDeviceAdd aufrufen. Andernfalls kann die Rückrufroutine für die Energieeinstellung aufgerufen werden, bevor der Treiberstapel vollständig erstellt wird.

Die Rückrufroutine, die für eine bestimmte Energieeinstellung registriert ist, wird aufgerufen, wenn ein Übergang in den Energiezustand eintritt, der den Wert der Einstellung ändert, oder wenn der Power Manager den Wert der Einstellung ändert. Wenn SettingGuid beispielsweise auf den GUID-Wert GUID_LIDSWITCH_STATE_CHANGE zeigt, wird die Rückrufroutine aufgerufen, wenn der Deckel eines Laptopcomputers geöffnet oder geschlossen klickt. Der Value-Parameter , der in diesem Beispiel an die Rückrufroutine übergeben wird, verweist auf einen ULONG-Wert, der 1 ist, wenn der Zustand des Deckelschalters von geschlossen in geöffnet geändert wurde, und ist 0, wenn der Zustand des Deckelschalters von geöffnet in geschlossen geändert wurde. Weitere Informationen finden Sie unter Power-Setting-GUID-Definitionen und ausführliche Kommentare in der Wdm.h-Headerdatei.

Der anfängliche Aufruf einer Rückrufroutine kann unmittelbar erfolgen, bevor der PoRegisterPowerSettingCallback-Aufruf , der die Routine registriert, zurückgibt.

PoRegisterPowerSettingCallback kann nur unter IRQL = PASSIVE_LEVEL aufgerufen werden.

Power-Setting Rückruf

Der Funktionsprototyp der Rückrufroutine für die Energieeinstellung sieht wie folgt aus:

NTSTATUS
POWER_SETTING_CALLBACK (
  _In_ LPCGUID SettingGuid,
  _In_ PVOID Value,
  _In_ ULONG ValueLength,
  _Inout_opt_ PVOID Context
);

Die Parameter für den Power-Setting-Rückruf sind:

SettingGuid
Ein Zeiger auf eine GUID, die die geänderte Energieeinstellung darstellt. Energieeinstellungen und die entsprechenden GUIDs werden in Wdm.h definiert.

Wert
Ein Zeiger auf den neuen Wert der geänderten Energieeinstellung.

ValueLength
Ein Wert vom Typ ULONG, der die Größe des neuen Energieeinstellungswerts in Bytes angibt.

Context
Der Zeiger auf den Kontext, den ein Treiber im Aufruf von PoRegisterPowerSettingCallback bereitgestellt hat, der die Rückrufroutine registriert hat.

Der Power Manager ruft unter IRQL = PASSIVE_LEVEL einen Energieeinstellungsrückruf auf.

Beispiele

Zum Definieren einer Rückrufroutine für die Energieeinstellung müssen Sie zunächst eine Funktionsdeklaration bereitstellen, die den Typ der Rückruffunktion angibt, 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 Power-Setting-Rückrufroutine mit dem Namen MyPowerSettingCallbackzu definieren, verwenden Sie den typ POWER_SETTING_CALLBACK, wie in diesem Codebeispiel gezeigt:

POWER_SETTING_CALLBACK MyPowerSettingCallback;

Implementieren Sie dann Ihre Rückrufroutine wie folgt:

_Use_decl_annotations_
NTSTATUS
  MyPowerSettingCallback(
    LPCGUID SettingGuid,
    PVOID Value,
    ULONG ValueLength,
    PVOID Context 
    )
  {
      // Function body
  }

Der POWER_SETTING_CALLBACK 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 POWER_SETTING_CALLBACK 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	Universell
Header	wdm.h (einschließlich Wdm.h, Ntddk.h, Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (siehe Abschnitt "Hinweise")