Funzione PoRegisterPowerSettingCallback (ntifs.h)

Articolo
02/26/2024

La routine PoRegisterPowerSettingCallback registra una routine di callback di impostazione alimentazione per ricevere notifiche di modifiche nell'impostazione di risparmio energia specificata.

Sintassi

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

Parametri

[in, optional] DeviceObject

Puntatore a una struttura DEVICE_OBJECT associata al chiamante di questa routine. Questo parametro è facoltativo e, Viene usato internamente solo a scopo di debug. Se questo parametro non viene specificato, deve essere impostato su NULL.

[in] SettingGuid

Puntatore al GUID che rappresenta l'impostazione di risparmio energia per questa registrazione. Quando cambia l'impostazione di risparmio energia specificata, il risparmio energia chiama la routine di callback per notificare al driver la modifica e fornire il nuovo valore dell'impostazione. Per altre informazioni, vedere la sezione Osservazioni.

[in] Callback

Puntatore a una routine di callback implementata dal chiamante che il risparmio energia chiama quando cambia l'impostazione di risparmio energia specificata. Per il prototipo funzionale per la routine di callback, vedere Callback di Power-Setting, di seguito.

[in, optional] Context

Puntatore al contesto per la routine di callback. Questo parametro è facoltativo e, Viene fornito in modo che un driver o un contesto di dispositivo possa essere passato alla routine di callback. Se questo parametro non viene usato, deve essere impostato su NULL.

[out] Handle

Handle utilizzato dal risparmio energia per rappresentare la routine di callback. Un driver deve successivamente fornire questo handle in una chiamata a PoUnregisterPowerSettingCallback per annullare la registrazione della routine di callback.

Valore restituito

PoRegisterPowerSettingCallback restituisce uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	La routine ha registrato la routine di callback.
STATUS_ INSUFFICIENT_RESOURCES	La routine non è in grado di allocare le risorse di sistema necessarie per registrare la routine di callback.

Commenti

Un driver chiama PoRegisterPowerSettingCallback per registrare una routine di callback con il risparmio energia. Il risparmio energia chiama successivamente questa routine di callback per notificare al driver dopo che è stata apportata una modifica all'impostazione di alimentazione specificata. Inoltre, il risparmio energia inizializza l'impostazione di alimentazione del driver chiamando immediatamente la routine di callback e passando il valore corrente dell'impostazione di alimentazione. Il risparmio energia inizializza l'impostazione di alimentazione del driver in questo modo, indipendentemente dal fatto che l'impostazione di alimentazione sia effettivamente cambiata.

Un driver deve chiamare PoRegisterPowerSettingCallback per ogni impostazione di alimentazione che il driver deve monitorare. I driver devono chiamare questa routine nella routine DriverEntry durante l'inizializzazione. In genere, la maggior parte dei driver passa un puntatore a un'estensione del dispositivo nel parametro Context .

Per annullare la registrazione di un callback di impostazione alimentazione, chiamare la routine PoUnregisterPowerSettingCallback .

In genere, i driver Kernel-Mode Driver Framework (KMDF) devono chiamare PoRegisterPowerSettingCallback dalla funzione di callback EvtDeviceSelfManagedIoInit e devono chiamare PoUnregisterPowerSettingCallback dalla funzione di callback EvtDeviceSelfManagedIoCleanup . Questi driver non devono chiamare PoRegisterPowerSettingCallback dalla funzione di callback EvtDriverDeviceAdd ; in caso contrario, la routine di callback di impostazione alimentazione potrebbe essere chiamata prima che lo stack di driver sia completamente compilato.

La routine di callback registrata per una determinata impostazione di risparmio energia viene chiamata quando si verifica una transizione nello stato di alimentazione che modifica il valore dell'impostazione o quando il risparmio energia modifica il valore dell'impostazione. Ad esempio, se SettingGuid punta al valore GUID GUID_LIDSWITCH_STATE_CHANGE, la routine di callback viene chiamata quando il coperchio di un computer portatile fa clic su aperto o chiuso. Il parametro Value passato alla routine di callback in questo esempio punta a un valore ULONG pari a 1 se lo stato dell'interruttore del coperchio è passato da chiuso a aperto e è 0 se lo stato dell'interruttore del coperchio è cambiato da aperto a chiuso. Per altre informazioni, vedere le definizioni GUID delle impostazioni di risparmio energia e i commenti completi nel file di intestazione Wdm.h.

La chiamata iniziale a una routine di callback può verificarsi immediatamente prima della chiamata PoRegisterPowerSettingCallback che registra la routine restituita.

PoRegisterPowerSettingCallback può essere chiamato solo in IRQL = PASSIVE_LEVEL.

callback Power-Setting

Di seguito è riportato il prototipo di funzione della routine di callback di impostazione alimentazione e dei relativi parametri. Il risparmio energia chiama un callback di impostazione alimentazione in IRQL = PASSIVE_LEVEL.

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

Parametro	Descrizione
SettingGuid	Puntatore a un GUID che rappresenta l'impostazione di risparmio energia modificata. Le impostazioni di risparmio energia e i GUID corrispondenti sono definiti in Wdm.h.
Valore	Puntatore al nuovo valore dell'impostazione di risparmio energia modificata.
ValueLength	Valore di tipo ULONG che specifica le dimensioni, in byte, del nuovo valore dell'impostazione di alimentazione.
Contesto	Puntatore al contesto fornito da un driver nella chiamata a PoRegisterPowerSettingCallback che ha registrato la routine di callback.

Esempio

Per definire una routine di callback di impostazione alimentazione, è necessario innanzitutto fornire una dichiarazione di funzione che identifica il tipo di funzione di callback che si sta definendo. Windows fornisce un set di tipi di funzione di callback per i driver. La dichiarazione di una funzione tramite i tipi di funzione di callback consente di analizzare il codice per i driver, l'SDV ( Static Driver Verifier ) e altri strumenti di verifica di trovare errori ed è un requisito per la scrittura di driver per il sistema operativo Windows.

Ad esempio, per definire una routine di callback di impostazione alimentazione denominata MyPowerSettingCallback, usare il tipo di POWER_SETTING_CALLBACK, come illustrato nell'esempio di codice seguente:

POWER_SETTING_CALLBACK MyPowerSettingCallback;

Implementare quindi la routine di callback come indicato di seguito:

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

Il tipo di funzione POWER_SETTING_CALLBACK è definito nel file di intestazione Wdm.h. Per identificare in modo più accurato gli errori quando si eseguono gli strumenti di analisi del codice, assicurarsi di aggiungere l'annotazione Use_decl_annotations alla definizione della funzione. L'annotazione Use_decl_annotations garantisce che vengano utilizzate le annotazioni applicate al tipo di funzione POWER_SETTING_CALLBACK nel file di intestazione. Per altre informazioni sui requisiti per le dichiarazioni di funzione, vedere Dichiarazione di funzioni tramite tipi di ruolo di funzione per i driver WDM. Per informazioni sulle Use_decl_annotations, vedere Annotazione del comportamento della funzione.

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista
Piattaforma di destinazione	Universale
Intestazione	ntifs.h (include Wdm.h, Ntddk.h, Ntifs.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (vedere la sezione Osservazioni)