Fonction PoRegisterPowerSettingCallback (ntifs.h)

La routine PoRegisterPowerSettingCallback inscrit une routine de rappel de paramètre d’alimentation pour recevoir des notifications de modifications dans le 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 de cette inscription. Lorsque le paramètre d’alimentation spécifié change, le gestionnaire d’alimentation appelle la routine de rappel pour avertir le pilote de la modification et fournir la nouvelle valeur du paramètre. Pour plus d’informations, consultez Remarques.

[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 Power-Settingde rappel, 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 transmis à 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 de retour

PoRegisterPowerSettingCallback retourne l’une des valeurs suivantes :

Remarques

Un pilote appelle PoRegisterPowerSettingCallback pour inscrire une routine de rappel auprès du gestionnaire d’alimentation. Par la suite, le gestionnaire d’alimentation appelle cette routine de rappel pour avertir le pilote une fois qu’il y a une modification apportée au 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 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 lors de 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, Kernel-Mode pilotes KMDF (Driver Framework) doivent appeler PoRegisterPowerSettingCallback à partir de leur EvtDeviceSelfManagedIoInit fonction de rappel, et doivent appeler PoUnregisterPowerSettingCallback à partir de leur fonction de rappel EvtDeviceSelfManagedIoCleanup. Ces pilotes ne doivent pas appeler PoRegisterPowerSettingCallback à partir de leur EvtDriverDeviceAdd fonction de rappel ; sinon, la routine de rappel de paramètre d’alimentation peut être appelée avant la génération complète de la pile des pilotes.

La routine de rappel inscrite pour un paramètre d’alimentation particulier est appelée lorsqu’une transition dans l’état de l’alimentation se produit qui modifie la valeur du paramètre ou lorsque le gestionnaire de l’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 sur un ordinateur portable clique ou ferme. Le paramètre Valeur 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é de ouvert à fermé. Pour plus d’informations, consultez les définitions GUID de définition de l’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 que le PoRegisterPowerSettingCallback appel qui enregistre la routine retourne.

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

rappel Power-Setting

Le prototype de fonction de la routine de rappel power-setting et ses paramètres sont les suivants. Power Manager 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
);

Exemples

Pour définir une routine de rappel power-setting, 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 fonctions de rappel permet d'Analyse du code pour les pilotes, static Driver Verifier (SDV) et d’autres outils de vérification recherchent des erreurs, et il est nécessaire d’écrire des 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 les exigences relatives aux 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 annoter le comportement de la fonction.

Exigences

Voir aussi

DriverEntry

EvtDeviceSelfManagedIoCleanup

EvtDeviceSelfManagedIoInit

EvtDriverDeviceAdd

PoUnregisterPowerSettingCallback