WdfDeviceGetSystemPowerAction, fonction (wdfdevice.h)

  • Article

[S’applique à KMDF et UMDF]

La méthode WdfDeviceGetSystemPowerAction retourne l’action d’alimentation du système, le cas échéant, qui se produit actuellement pour l’ordinateur.

Syntaxe

POWER_ACTION WdfDeviceGetSystemPowerAction(
  [in] WDFDEVICE Device
);

Paramètres

[in] Device

Handle d’un objet d’appareil framework.

Valeur retournée

WdfDeviceGetSystemPowerAction retourne une valeur d’énumérateur de type POWER_ACTION. La valeur indique l’action d’alimentation du système qui se produit actuellement pour l’ordinateur. Pour plus d'informations, consultez la section Notes qui suit. L’énumération POWER_ACTION est définie dans wdm.h.

Un bogue case activée se produit si le pilote fournit un handle d’objet non valide.

Remarques

À compter de WDF version 1.31/2.31 (appelée « v31 »), WdfDeviceGetSystemPowerAction a été mis à jour pour signaler plus précisément l’action d’alimentation du système lorsque l’appareil est le propriétaire de la stratégie d’alimentation. Les pilotes doivent être recompilés avec v31 ou version ultérieure pour obtenir le nouveau comportement suivant :

  • Si l’appareil entre ou quitte D0 en raison de S0 Inactif (voir WdfDeviceAssignS0IdleSettings) alors qu’une transition d’alimentation système non liée est en cours, WdfDeviceGetSystemPowerAction peut renvoyer PowerActionSleep. Ce problème est résolu dans v31 et retourne maintenant PowerActionNone.

  • Lorsque le système se réveille à partir de la veille hybride (mise en veille avec un fichier de mise en veille prolongée), avant v31, WdfDeviceGetSystemPowerAction renvoyait toujours PowerActionHibernate. Ce problème est résolu dans v31 et retourne à présent :

    • PowerActionSleep s’il se réveille sans perte de puissance, ce qui signifie que le système est resté dans S3
    • PowerActionHibernate s’il se réveille après une perte de courant, ce qui signifie que le système a repris à partir du fichier de mise en veille prolongée

La méthode WdfDeviceGetSystemPowerAction permet à un pilote de déterminer si la transition d’alimentation d’un appareil se produit parce que l’appareil est inactif (ou se réveille), ou parce que l’ordinateur entier entre (ou quitte) un état d’alimentation faible.

Le pilote doit appeler WdfDeviceGetSystemPowerAction uniquement à partir des fonctions de rappel d’événements appelées par l’infrastructure lorsque l’appareil entre dans un état de faible consommation ou revient à son état de fonctionnement.

La valeur retournée par WdfDeviceGetSystemPowerAction dépend des situations suivantes :

  • Si l’ordinateur entre dans un état de faible consommation lorsque le pilote appelle WdfDeviceGetSystemPowerAction, la méthode retourne la raison pour laquelle l’ordinateur entre dans l’état de faible consommation. Par exemple, la méthode retourne PowerActionSleep si l’ordinateur entre dans son état de faible consommation S1, S2 ou S3.
  • Si l’ordinateur revient à son état de fonctionnement (S0) à partir d’un état de faible consommation lorsque le pilote appelle WdfDeviceGetSystemPowerAction, la méthode retourne la raison pour laquelle l’ordinateur est entré dans l’état de faible consommation. Par exemple, la méthode retourne PowerActionSleep si l’ordinateur quitte son état de faible consommation S1, S2 ou S3.
  • Si l’ordinateur est sous tension (après avoir été désactivé) lorsque le pilote appelle WdfDeviceGetSystemPowerAction, la méthode retourne PowerActionNone.
  • Si l’appareil entre dans un état d’inactivité à faible consommation ou retourne à son état de fonctionnement (D0) lorsque le pilote appelle WdfDeviceGetSystemPowerAction, alors que le reste du système reste à son état de fonctionnement (S0), la méthode retourne PowerActionNone.
  • Si l’ordinateur et l’appareil sont tous deux dans leur état de fonctionnement lorsque le pilote appelle WdfDeviceGetSystemPowerAction, la méthode retourne PowerActionNone.
Pour plus d’informations sur les états de faible consommation d’énergie, consultez Un appareil entre un état Low-Power.

Exemples

L’exemple de code suivant obtient l’activité de transition d’alimentation qui se produit actuellement pour l’ordinateur.

POWER_ACTION SysPowerAction;

SysPowerAction = WdfDeviceGetSystemPowerAction(device);

Configuration requise

Condition requise Valeur
Plateforme cible Universal
Version KMDF minimale 1,9
Version UMDF minimale 2.0
En-tête wdfdevice.h (include Wdf.h)
Bibliothèque Wdf01000.sys (KMDF) ; WUDFx02000.dll (UMDF)
IRQL <= DISPATCH_LEVEL
Règles de conformité DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)