Fonction PoRegisterPowerSettingCallback (ntifs.h)

Article
07/11/2023

La routine PoRegisterPowerSettingCallback enregistre une routine de rappel de paramètre d’alimentation pour recevoir des notifications des modifications apportées au paramètre d’alimentation spécifié.

Syntaxe

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

Paramètres

[in, optional] DeviceObject

Pointeur vers une structure DEVICE_OBJECT associée à l’appelant de cette routine. Ce paramètre est facultatif. Il est utilisé en interne uniquement à des fins de débogage. Si ce paramètre n’est pas fourni, il doit être défini sur NULL.

[in] SettingGuid

Pointeur vers le GUID qui représente le paramètre d’alimentation pour cette inscription. Lorsque le paramètre d’alimentation spécifié change, le gestionnaire d’alimentation appelle la routine de rappel pour informer le pilote de la modification et pour fournir la nouvelle valeur du paramètre. Pour plus d'informations, consultez la section Notes.

[in] Callback

Pointeur vers une routine de rappel de paramètre d’alimentation implémentée par l’appelant que le gestionnaire d’alimentation appelle lorsque le paramètre d’alimentation spécifié change. Pour le prototype fonctionnel de la routine de rappel, consultez Rappel de définition de l’alimentation ci-dessous.

[in, optional] Context

Pointeur vers le contexte de la routine de rappel. Ce paramètre est facultatif. Il est fourni afin qu’un contexte de pilote ou de périphérique puisse être passé à la routine de rappel. Si ce paramètre n’est pas utilisé, il doit être défini sur NULL.

[out] Handle

Handle que le gestionnaire d’alimentation utilise pour représenter la routine de rappel. Un pilote doit ensuite fournir ce handle dans un appel à PoUnregisterPowerSettingCallback pour annuler l’inscription de la routine de rappel.

Valeur retournée

PoRegisterPowerSettingCallback retourne l’une des valeurs suivantes :

Code de retour	Description
STATUS_SUCCESS	La routine a inscrit la routine de rappel.
STATUS_ INSUFFICIENT_RESOURCES	La routine n’a pas pu allouer les ressources système requises pour inscrire la routine de rappel.

Remarques

Un pilote appelle PoRegisterPowerSettingCallback pour inscrire une routine de rappel auprès du gestionnaire d’alimentation. Le gestionnaire d’alimentation appelle ensuite cette routine de rappel pour avertir le pilote après une modification du paramètre d’alimentation spécifié. En outre, le gestionnaire d’alimentation initialise le paramètre d’alimentation du pilote en appelant immédiatement la routine de rappel et en transmettant la valeur actuelle du paramètre d’alimentation. Le gestionnaire d’alimentation initialise le paramètre d’alimentation du pilote de cette façon, que le paramètre d’alimentation ait réellement changé.

Un pilote doit appeler PoRegisterPowerSettingCallback pour chaque paramètre d’alimentation que le pilote doit surveiller. Les pilotes doivent appeler cette routine dans leur routine DriverEntry pendant l’initialisation. En règle générale, la plupart des pilotes passent un pointeur vers une extension de périphérique dans le paramètre Context .

Pour annuler l’inscription d’un rappel de paramètre d’alimentation, appelez la routine PoUnregisterPowerSettingCallback .

En règle générale, les pilotes Kernel-Mode Driver Framework (KMDF) doivent appeler PoRegisterPowerSettingCallback à partir de leur fonction de rappel EvtDeviceSelfManagedIoInit et doivent appeler PoUnregisterPowerSettingCallback à partir de leur fonction de rappel EvtDeviceSelfManagedIoCleanup . Ces pilotes ne doivent pas appeler PoRegisterPowerSettingCallback à partir de leur fonction de rappel EvtDriverDeviceAdd ; sinon, la routine de rappel de paramètre d’alimentation peut être appelée avant que la pile des pilotes soit entièrement générée.

La routine de rappel inscrite pour un paramètre d’alimentation particulier est appelée lorsqu’une transition dans l’état d’alimentation se produit et modifie la valeur du paramètre, ou lorsque le gestionnaire d’alimentation modifie la valeur du paramètre. Par exemple, si SettingGuid pointe vers la valeur GUID GUID_LIDSWITCH_STATE_CHANGE, la routine de rappel est appelée lorsque le couvercle d’un ordinateur portable clique sur ouvrir ou fermer. Le paramètre Value passé à la routine de rappel dans cet exemple pointe vers une valeur ULONG qui est 1 si l’état du commutateur de couvercle est passé de fermé à ouvert, et est 0 si l’état du commutateur de couvercle est passé d’ouvert à fermé. Pour plus d’informations, consultez les définitions de GUID de paramètre d’alimentation et les commentaires détaillés dans le fichier d’en-tête Wdm.h.

L’appel initial à une routine de rappel peut se produire immédiatement, avant l’appel PoRegisterPowerSettingCallback qui enregistre la routine retournée.

PoRegisterPowerSettingCallback peut être appelé uniquement à l’adresse IRQL = PASSIVE_LEVEL.

rappel Power-Setting

Le prototype de fonction de la routine de rappel de paramètre d’alimentation et ses paramètres sont les suivants. Le gestionnaire d’alimentation appelle un rappel de paramètre d’alimentation à IRQL = PASSIVE_LEVEL.

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

Paramètre	Description
SettingGuid	Pointeur vers un GUID qui représente le paramètre d’alimentation modifié. Les paramètres d’alimentation et leurs GUID correspondants sont définis dans Wdm.h.
Valeur	Pointeur vers la nouvelle valeur du paramètre d’alimentation qui a changé.
ValueLength	Valeur de type ULONG qui spécifie la taille, en octets, de la nouvelle valeur de paramètre d’alimentation.
Contexte	Pointeur vers le contexte fourni par un pilote dans l’appel à PoRegisterPowerSettingCallback qui a inscrit la routine de rappel.

Exemples

Pour définir une routine de rappel de paramètre d’alimentation, vous devez d’abord fournir une déclaration de fonction qui identifie le type de fonction de rappel que vous définissez. Windows fournit un ensemble de types de fonctions de rappel pour les pilotes. La déclaration d’une fonction à l’aide des types de fonction de rappel permet à l’analyse du code pour les pilotes, au vérificateur de pilotes statiques (SDV) et à d’autres outils de vérification de trouver des erreurs. Il s’agit d’une exigence pour l’écriture de pilotes pour le système d’exploitation Windows.

Par exemple, pour définir une routine de rappel de paramètre d’alimentation nommée MyPowerSettingCallback, utilisez le type POWER_SETTING_CALLBACK comme indiqué dans cet exemple de code :

POWER_SETTING_CALLBACK MyPowerSettingCallback;

Ensuite, implémentez votre routine de rappel comme suit :

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

Le type de fonction POWER_SETTING_CALLBACK est défini dans le fichier d’en-tête Wdm.h. Pour identifier plus précisément les erreurs lors de l’exécution des outils d’analyse du code, veillez à ajouter l’annotation Use_decl_annotations à votre définition de fonction. L’annotation Use_decl_annotations garantit que les annotations appliquées au type de fonction POWER_SETTING_CALLBACK dans le fichier d’en-tête sont utilisées. Pour plus d’informations sur la configuration requise pour les déclarations de fonction, consultez Déclaration de fonctions à l’aide de types de rôles de fonction pour les pilotes WDM. Pour plus d’informations sur Use_decl_annotations, consultez Annotating Function Behavior.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Plateforme cible	Universal
En-tête	ntifs.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL (voir la section Remarques)