PoRegisterPowerSettingCallback-Funktion (ntifs.h)

Die PoRegisterPowerSettingCallback Routine registriert eine Power-Setting-Rückrufroutine, 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. Sie wird intern nur für Debuggingzwecke 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 Power-Setting-Rückrufroutine, 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-unten.

[in, optional] Context

Ein Zeiger auf den Kontext für die Rückrufroutine. Dieser Parameter ist optional. Es 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. Anschließend muss ein Treiber dieses Handle in einem Aufruf von PoUnregisterPowerSettingCallback bereitstellen, um die Registrierung der Rückrufroutine aufzuheben.

Rückgabewert

PoRegisterPowerSettingCallback gibt eine der folgenden Werte zurück:

Bemerkungen

Ein Treiber ruft PoRegisterPowerSettingCallback auf, um eine Rückrufroutine beim Power Manager zu registrieren. Anschließend ruft der Power Manager diese Rückrufroutine auf, um den Treiber zu benachrichtigen, nachdem eine Änderung an der angegebenen Energieeinstellung erfolgt ist. Darüber hinaus initialisiert der Power Manager die Energieeinstellung des Treibers, indem sofort die Rückrufroutine aufgerufen und der aktuelle Wert der Energieeinstellung übergeben wird. Der Power 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 Leistungseinstellung aufrufen, die der Treiber überwachen muss. Treiber sollten diese Routine in ihrer DriverEntry- Routine während der Initialisierung aufrufen. In der Regel übergeben die meisten Treiber einen Zeiger an eine Geräteerweiterung im parameter Context.

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

In der Regel sollten Kernel-Mode Driver Framework(KMDF)-Treiber PoRegisterPowerSettingCallback- aus ihrer EvtDeviceSelfManagedIoInit Rückruffunktion aufrufen und PoUnregisterPowerSettingCallback aus ihrer EvtDeviceSelfManagedIoCleanup- Rückruffunktion aufrufen. Diese Treiber sollten nicht PoRegisterPowerSettingCallback- aus ihrer EvtDriverDeviceAdd Rückruffunktion aufrufen; andernfalls wird die Rückrufroutine für die Energieeinstellung möglicherweise aufgerufen, bevor der Treiberstapel vollständig erstellt wird.

Die Rückrufroutine, die für eine bestimmte Energieeinstellung registriert ist, wird aufgerufen, wenn ein Übergang im Energiezustand auftritt, der den Wert der Einstellung ändert, oder wenn der Power Manager den Wert der Einstellung ändert. Wenn z. B. SettingGuid auf den GUID-Wert GUID_LIDSWITCH_STATE_CHANGE verweist, wird die Rückrufroutine aufgerufen, wenn der Deckel auf einen Laptopcomputer auf geöffnet oder geschlossen klickt. Der parameter Value, der an die Rückrufroutine in diesem Beispiel übergeben wird, verweist auf einen ULONG-Wert, der 1 ist, wenn der Zustand des Deckelschalters von "geschlossen" in "geöffnet" geändert wurde und 0 ist, wenn der Zustand des Deckelschalters von "geöffnet" in "geschlossen" geändert wurde. Weitere Informationen finden Sie in den POWER-Setting-GUID-Definitionen und umfangreichen Kommentaren in der Wdm.h-Headerdatei.

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

PoRegisterPowerSettingCallback- kann nur bei IRQL = PASSIVE_LEVEL aufgerufen werden.

Power-Setting Rückruf

Der Funktionsprototyp der Rückrufroutine für power-setting und deren Parameter sind wie folgt. Der Power Manager ruft einen Power-Setting-Rückruf bei IRQL = PASSIVE_LEVEL auf.

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

Beispiele

Um eine Power-Setting-Rückrufroutine zu definieren, müssen Sie zuerst eine Funktionsdeklaration bereitstellen, die den Typ der Rückruffunktion identifiziert, die Sie definieren. Windows stellt eine Reihe von Rückruffunktionstypen für Treiber bereit. Durch das Deklarieren einer Funktion mithilfe der Rückruffunktionstypen können Codeanalyse für Treiber, statische Treiberüberprüfung (SDV) und andere Überprüfungstools Fehler finden, und es ist eine Anforderung zum Schreiben von Treibern für das Windows-Betriebssystem.

Um beispielsweise eine Power-Setting-Rückrufroutine zu definieren, die MyPowerSettingCallbackgenannt wird, verwenden Sie den POWER_SETTING_CALLBACK Typ, 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 wird in der Wdm.h-Headerdatei definiert. Um Fehler genauer zu identifizieren, wenn Sie die Codeanalysetools ausführen, müssen Sie der Funktionsdefinition die Use_decl_annotations Anmerkung hinzufügen. Die Use_decl_annotations Anmerkung stellt sicher, dass die Anmerkungen, die auf den Funktionstyp POWER_SETTING_CALLBACK in der Headerdatei angewendet werden, verwendet 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_annotationsfinden Sie unter Annotating Function Behavior.

Anforderungen

Siehe auch

DriverEntry-

EvtDeviceSelfManagedIoCleanup

EvtDeviceSelfManagedIoInit

EvtDriverDeviceAdd

PoUnregisterPowerSettingCallback-