IWDFDevice2 ::AssignS0IdleSettings, méthode (wudfddi.h)
[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 AssignS0IdleSettings fournit des informations fournies par le pilote que l’infrastructure utilise lorsqu’un appareil est inactif et que le système est dans son état de fonctionnement (S0).
Syntaxe
HRESULT AssignS0IdleSettings(
[in] WDF_POWER_POLICY_S0_IDLE_CAPABILITIES IdleCaps,
[in] DEVICE_POWER_STATE DxState,
[in] ULONG IdleTimeout,
[in] WDF_POWER_POLICY_S0_IDLE_USER_CONTROL UserControlOfIdleSettings,
[in] WDF_TRI_STATE Enabled
);
Paramètres
[in] IdleCaps
Énumérateur de type WDF_POWER_POLICY_S0_IDLE_CAPABILITIES qui identifie la capacité de l’appareil à se réveiller lui-même une fois qu’il est défini sur un état de faible consommation, tandis que le système reste dans son état de fonctionnement (S0).
[in] DxState
Énumérateur de type DEVICE_POWER_STATE qui identifie l’état d’alimentation faible de l’appareil que l’appareil entrera après la fin du délai d’inactivité. DEVICE_POWER_STATE valeurs sont définies dans wdm.h.
[in] IdleTimeout
Durée, en millisecondes, pendant laquelle l’appareil reste inactif avant que l’infrastructure le place dans l’état de faible consommation d’énergie fourni par DxState. Pour utiliser la valeur de délai d’inactivité par défaut de l’infrastructure, spécifiez IdleTimeoutDefaultValue Pour plus d’informations, consultez la section Notes.
[in] UserControlOfIdleSettings
Énumérateur WDF_POWER_POLICY_S0_IDLE_USER_CONTROL qui indique si les utilisateurs peuvent modifier les paramètres d’inactivité de l’appareil.
[in] Enabled
Énumérateur WDF_TRI_STATE qui indique si l’appareil sera mis hors tension s’il reste inactif et pendant que l’alimentation du système est à S0. Ce membre peut avoir l’une des valeurs suivantes :
WdfTrue : la mise sous tension est activée.
WdfFalse : la mise sous tension est désactivée.
WdfUseDefault : la mise hors tension est initialement activée par défaut ; mais si le paramètre UserControlOfIdleSettings est défini sur IdleAllowUserControl, le paramètre de l’utilisateur ou le fichier INF du pilote remplace la valeur initiale.
Si la mise hors tension est activée, l’appareil dispose d’une fonctionnalité de mise en éveil et la valeur du délai d’inactivité expire, l’infrastructure appelle la fonction de rappel IPowerPolicyCallbackWakeFromS0 ::OnArmWakeFromS0 du pilote avant que l’appareil ne passe à un état de faible consommation.
Valeur retournée
AssignS0IdleSettings retourne S_OK si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs suivantes :
| Code de retour | Description |
|---|---|
|
L’appelant a spécifié une valeur non valide pour un paramètre d’entrée. |
|
Le pilote appelant n’est pas le propriétaire de la stratégie d’alimentation de l’appareil. |
|
Le paramètre DxState spécifie un état d’alimentation du périphérique non valide, ou le paramètre IdleCaps indique que l’appareil peut se réveiller lui-même, mais le pilote de bus indique que l’appareil ne peut pas se réveiller lui-même. |
Cette méthode peut retourner l’une des autres valeurs que Winerror.h contient.
Remarques
La première fois qu’un pilote appelle AssignS0IdleSettings, les actions suivantes se produisent :
- L’infrastructure stocke les valeurs de tous les paramètres.
- Si le paramètre UserControlOfIdleSettings est défini sur IdleAllowUserControl 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 mise hors tension de l’appareil lorsqu’il est inactif.
- Si le pilote a déjà spécifié IdleCanWakeFromS0 pour la valeur du paramètre IdleCaps dans un appel précédent à AssignS0IdleSettings, il ne peut pas remplacer cette valeur par IdleUsbSelectiveSuspend.
- Si le pilote a déjà spécifié IdleUsbSelectiveSuspend pour la valeur du paramètre IdleCaps dans un appel précédent à AssignS0IdleSettings, il ne peut par la suite pas modifier cette valeur en IdleCanWakeFromS0.
Les règles suivantes s’appliquent à la valeur que vous spécifiez pour le paramètre DxState :
- La valeur ne peut pas être PowerDeviceD0.
- Pour les périphériques USB, la valeur ne peut pas être PowerDeviceD0 ou PowerDeviceD3.
- 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 .
- Si la valeur du paramètre IdleCaps est IdleCanWakeFromS0 ou IdleUsbSelectiveSuspend, vous ne pouvez pas spécifier un état d’alimentation de l’appareil inférieur à l’état d’alimentation de l’appareil 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 inactives d’un appareil, consultez Contrôle utilisateur du comportement d’inactivité et de veille de l’appareil dans UMDF.
Pour plus d’informations sur la prise en charge des fonctionnalités inactives d’un appareil, consultez Prise en charge des Power-Down inactifs dans les pilotes UMDF.
Exemples
L’exemple de code suivant est basé sur la version UMDF de l’exemple de grille-pain. L’exemple obtient l’interface IWDFDevice2 , puis appelle AssignS0IdleSettings.
IWDFDevice2 *pIWDFDevice2 = NULL;
HRESULT hr;
//
// Get a pointer to the IWDFDevice2 interface.
//
hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
(void**) &pIWDFDevice2);
if (SUCCEEDED(hr))
{
//
// The toaster device is virtual, so we tell the framework that the
// device cannot wake if it sleeps while the system is in S0. The device
// can return to D0 only when the driver stack receives an I/O request.
//
hr = pIWDFDevice2->AssignS0IdleSettings(IdleCannotWakeFromS0,
PowerDeviceD3,
IDLEWAKE_TIMEOUT_MSEC,
IdleAllowUserControl,
WdfTrue);
}
...
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 |