WdfDeviceAssignS0IdleSettings, fonction (wdfdevice.h)

Article
08/08/2023

[S’applique à KMDF et UMDF]

La méthode WdfDeviceAssignS0IdleSettings fournit des informations fournies par le pilote que le framework utilise lorsqu’un appareil est inactif et que le système est dans son état de fonctionnement (S0).

Syntaxe

NTSTATUS WdfDeviceAssignS0IdleSettings(
  [in] WDFDEVICE                              Device,
  [in] PWDF_DEVICE_POWER_POLICY_IDLE_SETTINGS Settings
);

Paramètres

[in] Device

Handle pour un objet d’appareil d’infrastructure.

[in] Settings

Pointeur vers une structure de WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS fournie par l’appelant.

Valeur retournée

Si l’opération réussit, WdfDeviceAssignS0IdleSettings retourne STATUS_SUCCESS. Les valeurs de retour supplémentaires sont les suivantes :

Code de retour	Description
STATUS_INVALID_DEVICE_REQUEST	Le pilote appelant n’est pas le propriétaire de la stratégie d’alimentation de l’appareil.
STATUS_INVALID_PARAMETER	Une valeur Settings non valide est détectée.
STATUS_INFO_LENGTH_MISMATCH	La taille de la structure WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS est incorrecte.
STATUS_POWER_STATE_INVALID	Cette valeur est retournée si l’une des opérations suivantes se produit : La structure WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS contient un état d’alimentation de périphérique non valide. Le membre IdleCaps de la structure WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS indique que l’appareil peut se réveiller lui-même, mais que le pilote de bus indique que l’appareil ne peut pas se réveiller lui-même. À compter de KMDF version 1.11 s’exécutant sur Windows 8, le framework vérifie si le microprogramme du système peut gérer un signal de sortie de veille alors que le système est dans son état d’alimentation complet (S0). Si la machine échoue à ce case activée, WdfDeviceAssignS0IdleSettings retourne STATUS_POWER_STATE_INVALID et l’appareil reste dans son état d’alimentation complet (D0) tant que le système reste dans S0. Dans ce cas, le pilote ne doit pas retourner une erreur status valeur à partir d’EvtDriverDeviceAdd ou de tout autre rappel d’exécution. Au maximum, le pilote peut enregistrer une erreur indiquant que l’appareil consommera plus d’énergie qu’il ne le ferait normalement.

La méthode peut retourner d’autres valeurs NTSTATUS.

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

Remarques

Si le pilote définit le membre IdleTimeoutType de WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS sur SystemManagedIdleTimeout ou SystemManagedIdleTimeoutWithHint, il doit appeler WdfDeviceAssignS0IdleSettings avant de revenir à partir d’EvtDeviceD0Entry. En règle générale, un pilote appelle d’abord WdfDeviceAssignS0IdleSettings à partir d’EvtDriverDeviceAdd.

Des appels supplémentaires à WdfDeviceAssignS0IdleSettings peuvent être effectués à tout moment. Toutefois, une fois que le pilote a défini la valeur du membre IdleTimeoutType dans son premier appel à WdfDeviceAssignS0IdleSettings, il ne doit pas modifier cette valeur dans les appels ultérieurs à cette méthode.

Si le pilote s’inscrit pour des notifications asynchrones dans EvtDriverDeviceAdd (par exemple en appelant PoRegisterPowerSettingCallback ou IoRegisterPlugPlayNotification), le pilote ne doit pas appeler par la suite WdfDeviceAssignS0IdleSettings à partir de la routine de rappel de pilote qu’il a inscrite.

Pour plus d’informations, consultez Prise en charge de la mise hors tension inactive.

Exemples

L’exemple de code suivant initialise une structure de WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS , définit une valeur de délai d’inactivité de 10 secondes et appelle WdfDeviceAssignS0IdleSettings.

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS  idleSettings;
NTSTATUS  status = STATUS_SUCCESS;

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS_INIT(
                                           &idleSettings,
                                           IdleCanWakeFromS0
                                           );
idleSettings.IdleTimeout = 10000;

status = WdfDeviceAssignS0IdleSettings(
                                       device,
                                       &idleSettings
                                       );
if (!NT_SUCCESS(status)) {
    return status;
}

Configuration requise

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

Voir aussi

WDF_DEVICE_POWER_POLICY_IDLE_SETTINGS

WdfDeviceAssignSxWakeSettings

Partager via