Méthode IWDFDevice2 ::AssignSxWakeSettings (wudfddi.h)

Article
02/27/2024

[Avertissement : UMDF 2 est la dernière version d’UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide d’UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et la prise en charge d’UMDF 1 est limitée sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Prise en main avec UMDF.]

La méthode AssignSxWakeSettings fournit des informations fournies par le pilote sur la capacité d’un appareil à déclencher un signal de veille alors que l’appareil et le système sont dans un état de faible consommation.

Syntaxe

HRESULT AssignSxWakeSettings(
  [in] DEVICE_POWER_STATE                    DxState,
  [in] WDF_POWER_POLICY_SX_WAKE_USER_CONTROL UserControlOfWakeSettings,
  [in] WDF_TRI_STATE                         Enabled
);

Paramètres

[in] DxState

Énumérateur de type DEVICE_POWER_STATE qui identifie l’état d’alimentation faible de l’appareil que l’appareil entre lorsque l’état d’alimentation du système passe à un état de faible consommation en éveil. La valeur de DxState ne peut pas être PowerDeviceD0. DEVICE_POWER_STATE valeurs sont définies dans wdm.h.

[in] UserControlOfWakeSettings

Énumérateur WDF_POWER_POLICY_SX_WAKE_USER_CONTROL qui indique si les utilisateurs ont la possibilité de modifier les paramètres de veille de l’appareil.

[in] Enabled

Énumérateur de type WDF_TRI_STATE qui indique si l’appareil peut sortir le système (autrement dit, restaurer le système sur S0) lorsque le système est dans un état de faible consommation. Ce membre peut avoir l’une des valeurs suivantes :

WdfTrue : l’éveil du système est activé.

WdfFalse : l’éveil du système est désactivé.

WdfUseDefault : l’éveil du système est initialement activé par défaut ; mais si le membre UserControlOfWakeSettings est défini sur WakeAllowUserControl, le paramètre de l’utilisateur ou le fichier INF du pilote remplace la valeur initiale.

Si le système est activé et que le système est sur le point d’entrer dans un état de faible consommation, le framework appelle la fonction de rappel IPowerPolicyCallbackWakeFromSx ::OnArmWakeFromSx du pilote avant que l’appareil ne passe à un état de faible consommation.

Valeur retournée

AssignSxWakeSettings retourne S_OK si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs suivantes :

Code de retour	Description
E_INVALIDARG	L’appelant a spécifié une valeur non valide pour un paramètre d’entrée.
HRESULT_FROM_NT(STATUS_INVALID_DEVICE_REQUEST)	Le pilote appelant n’est pas le propriétaire de la stratégie d’alimentation de l’appareil.
HRESULT_FROM_NT(STATUS_POWER_STATE_INVALID)	Le paramètre DxState spécifie un état d’alimentation du périphérique non valide, ou le pilote de bus indique que le périphérique ne peut pas déclencher un signal de sortie de veille.

Cette méthode peut retourner l’une des autres valeurs que Winerror.h contient.

Remarques

La première fois qu’un pilote appelle AssignSxWakeSettings, les actions suivantes se produisent :

L’infrastructure stocke les valeurs des paramètres.
Si le paramètre UserControlOfWakeSettings est défini sur WakeAllowUserControl et si le paramètre Enabled est défini sur WdfUseDefault, l’infrastructure lit le Registre pour déterminer si l’utilisateur a activé la veille du système.

Lors des appels suivants à AssignSxWakeSettings, l’infrastructure ne stocke pas la valeur du paramètre UserControlOfWakeSettings . En d’autres termes, l’infrastructure effectue les étapes suivantes la première fois que le pilote appelle AssignSxWakeSettings , mais pas lors des appels ultérieurs :

Stocke la valeur du paramètre UserControlOfWakeSettings .
Recherche un paramètre utilisateur dans le Registre, si la valeur du paramètre Enabled est WdfUseDefault.

Les règles suivantes s’appliquent à la valeur que vous spécifiez pour le paramètre DxState :

La valeur ne peut pas être PowerDeviceD0.
Si vous spécifiez DevicePowerMaximum, l’infrastructure utilise la valeur que le pilote en mode noyau pour le bus de l’appareil a fournie dans le membre DeviceWake de sa structure WDF_DEVICE_POWER_CAPABILITIES .
Vous ne pouvez pas spécifier un état d’alimentation du périphérique inférieur à l’état d’alimentation du périphérique dans le membre DeviceWake de la structure de WDF_DEVICE_POWER_CAPABILITIES du pilote de bus en mode noyau. (En d’autres termes, si la valeur DeviceWake du pilote de bus est PowerDeviceD2, la valeur DxState de votre pilote de fonction ne peut pas être PowerDeviceD3.)

Pour plus d’informations sur les entrées de Registre qui contrôlent les fonctionnalités de veille d’un appareil, consultez Contrôle utilisateur du comportement d’inactivité et d’éveil de l’appareil dans UMDF.

Pour plus d’informations sur la prise en charge des fonctionnalités de veille d’un appareil, consultez Prise en charge des Wake-Up système dans les pilotes basés sur UMDF.

L’exemple de code suivant obtient l’interface IWDFDevice2 , puis appelle AssignSxWakeSettings.

    IWDFDevice2 *pIWDFDevice2 = NULL;
    HRESULT hr;

    //
    // Get a pointer to the IWDFDevice2 interface.
    //
    hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
                                     (void**) &pIWDFDevice2);
    if (SUCCEEDED(hr)) 
    {
        hr = pIWDFDevice2->AssignSxWakeSettings(PowerDeviceMaximum,
                                                WakeAllowUserControl,
                                                WdfUseDefault);
    }
...
    SAFE_RELEASE(pIWDFDevice2);

Configuration requise

Condition requise	Valeur
Fin de la prise en charge	Non disponible dans UMDF 2.0 et versions ultérieures.
Plateforme cible	Desktop (Expérience utilisateur)
Version UMDF minimale	1,9
En-tête	wudfddi.h (inclure Wudfddi.h)
DLL	WUDFx.dll

Voir aussi

IWDFDevice2

IWDFDevice2 ::AssignS0IdleSettings

Partager via