Fonction PoRegisterPowerSettingCallback (wdm.h)

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ètres d’alimentation implémentée par l’appelant que le gestionnaire d’alimentation appelle lorsque le paramètre d’alimentation spécifié change. Pour obtenir le prototype fonctionnel de la routine de rappel, consultez Rappel de définition de l’alimentation.

[in, optional] Context

Pointeur vers le contexte de la routine de rappel. Ce paramètre est facultatif. Il est fourni pour qu’un pilote ou un contexte d’appareil 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’un des éléments suivants :

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 passant 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 ou non 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 d’appareil 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, Kernel-Mode pilotes KMDF (Driver Framework) 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 ; dans le cas contraire, la routine de rappel du paramètre d’alimentation peut être appelée avant que la pile de pilotes ne 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 qui 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 ouvert ou fermé. 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 inscrit la routine retourne.

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

rappel Power-Setting

Le prototype de fonction de la routine de rappel de paramètre d’alimentation est le suivant :

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

Les paramètres de rappel du paramètre d’alimentation sont les suivants :

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.

Le gestionnaire d’alimentation appelle un rappel de paramètre d’alimentation à IRQL = PASSIVE_LEVEL.

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 aide l’analyse du code pour les pilotes, le vérificateur de pilotes statique (SDV) et d’autres outils de vérification à la recherche d’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 lorsque vous exécutez les 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

Voir aussi

DriverEntry

EvtDeviceSelfManagedIoCleanup

EvtDeviceSelfManagedIoInit

EvtDriverDeviceAdd

PoUnregisterPowerSettingCallback