IWDFDevice2 ::AssignS0IdleSettings, méthode (wudfddi.h)
[Avertissement : UMDF 2 est la dernière version de UMDF et remplace UMDF 1. Tous les nouveaux pilotes UMDF doivent être écrits à l’aide de UMDF 2. Aucune nouvelle fonctionnalité n’est ajoutée à UMDF 1 et il existe une prise en charge limitée de UMDF 1 sur les versions plus récentes de Windows 10. Les pilotes Windows universels doivent utiliser UMDF 2. Pour plus d’informations, consultez Bien démarrer 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 travail (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 WDF_POWER_POLICY_S0_IDLE_CAPABILITIES-typé qui identifie la capacité de l’appareil à se réveiller une fois qu’il est défini sur un état de faible puissance, tandis que le système reste dans son état de fonctionnement (S0).
[in] DxState
Énumérateur DEVICE_POWER_STATE-typé qui identifie l’état d’alimentation de l’appareil faible que l’appareil entre après la fin de la période 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 le DxStateétat de faible alimentation fourni. Pour utiliser la valeur de délai d’inactivité par défaut du framework, spécifiez IdleTimeoutDefaultValue Pour plus d’informations, consultez la section Remarques.
[in] UserControlOfIdleSettings
Énumérateur WDF_POWER_POLICY_S0_IDLE_USER_CONTROL-typé qui indique si les utilisateurs ont la possibilité de modifier les paramètres inactifs de l’appareil.
[in] Enabled
Énumérateur WDF_TRI_STATE-typé qui indique si l’appareil sera mis hors tension s’il reste inactif et pendant que la puissance 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 en panne est désactivée.
WdfUseDefault : la mise sous tension est initialement activée par défaut ; mais si le paramètre UserControlOfIdleSettings est défini sur IdleAllowUserControl, le paramètre 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 le IPowerPolicyCallbackWakeFromS0 ::OnArmWakeFromS0 fonction de rappel avant que l’appareil ne passe à un état de faible alimentation.
Valeur de retour
AssignS0IdleSettings retourne S_OK si l’opération réussit. Sinon, la méthode peut retourner l’une des valeurs suivantes :
| Retourner le code | 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 d’appareil 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 Activé est défini sur WdfUseDefault, l’infrastructure lit le Registre pour savoir si l’utilisateur a activé la mise hors tension de l’appareil lorsqu’il est inactif.
- Si le pilote a jamais spécifié IdleCanWakeFromS0 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 IdleUsbSelectiveSuspend.
- Si le pilote n’a jamais 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 du bus de l’appareil fourni dans le DeviceWake membre de sa structure de 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 d’appareil inférieur à l’état d’alimentation de l’appareil dans le DeviceWake membre de la structure WDF_DEVICE_POWER_CAPABILITIES du pilote de bus en mode noyau. (En d’autres termes, si la valeur de deviceWake du pilote de bus est PowerDeviceD2, la valeur DxState du 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 inactif 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 basés sur 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);
Exigences
| Exigence | Valeur |
|---|---|
| fin du support | Indisponible dans UMDF 2.0 et versions ultérieures. |
| plateforme cible | Bureau |
| version minimale de UMDF | 1.9 |
| d’en-tête | wudfddi.h (include Wudfddi.h) |
| DLL | WUDFx.dll |