fonction WinUsb_SetPowerPolicy (winusb.h)

Article
08/27/2023

La fonction WinUsb_SetPowerPolicy définit la stratégie d’alimentation d’un appareil.

Syntaxe

BOOL WinUsb_SetPowerPolicy(
  [in] WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in] ULONG                   PolicyType,
  [in] ULONG                   ValueLength,
  [in] PVOID                   Value
);

Paramètres

[in] InterfaceHandle

Handle opaque à la première interface (par défaut) de l’appareil, qui est retourné par WinUsb_Initialize.

[in] PolicyType

Valeur qui spécifie la stratégie d’alimentation à définir. Le tableau suivant décrit les constantes symboliques définies dans winusbio.h.

Paramètre de stratégie	Description
AUTO_SUSPEND (0x81)	Spécifie le type de stratégie de suspension automatique ; le paramètre power policy doit être spécifié par l’appelant dans le paramètre Value . Pour la suspension automatique, le paramètre Value doit pointer vers une variable UCHAR. Si La valeur est TRUE (différente de zéro), la pile USB suspend l’appareil si l’appareil est inactif. Un appareil est inactif s’il n’y a aucun transfert en attente ou si les seuls transferts en attente sont des transferts IN pour interrompre ou des points de terminaison en bloc. La valeur par défaut est déterminée par la valeur définie dans le paramètre de Registre DefaultIdleState . Par défaut, cette valeur est TRUE.
SUSPEND_DELAY (0x83)	Spécifie le type de stratégie suspend-delay ; le paramètre power policy doit être spécifié par l’appelant dans le paramètre Value . Pour la suspension-délai, La valeur doit pointer vers une variable ULONG. Value spécifie la durée minimale, en millisecondes, que le pilote WinUSB doit attendre après le transfert avant de pouvoir suspendre l’appareil. La valeur par défaut est déterminée par la valeur définie dans le paramètre de Registre DefaultIdleTimeout . Par défaut, cette valeur est 5 secondes.

Paramètre de stratégie

Description

AUTO_SUSPEND

(0x81)

Spécifie le type de stratégie de suspension automatique ; le paramètre power policy doit être spécifié par l’appelant dans le paramètre Value .

Pour la suspension automatique, le paramètre Value doit pointer vers une variable UCHAR.

Si La valeur est TRUE (différente de zéro), la pile USB suspend l’appareil si l’appareil est inactif. Un appareil est inactif s’il n’y a aucun transfert en attente ou si les seuls transferts en attente sont des transferts IN pour interrompre ou des points de terminaison en bloc.

La valeur par défaut est déterminée par la valeur définie dans le paramètre de Registre DefaultIdleState . Par défaut, cette valeur est TRUE.

SUSPEND_DELAY

(0x83)

Spécifie le type de stratégie suspend-delay ; le paramètre power policy doit être spécifié par l’appelant dans le paramètre Value .

Pour la suspension-délai, La valeur doit pointer vers une variable ULONG.

Value spécifie la durée minimale, en millisecondes, que le pilote WinUSB doit attendre après le transfert avant de pouvoir suspendre l’appareil.

La valeur par défaut est déterminée par la valeur définie dans le paramètre de Registre DefaultIdleTimeout . Par défaut, cette valeur est 5 secondes.

[in] ValueLength

Taille, en octets, de la mémoire tampon sur Valeur.

[in] Value

Nouvelle valeur pour le paramètre power policy. Le type de données et la valeur pour Value dépendent du type de stratégie d’alimentation passé dans PolicyType. Pour plus d’informations, consultez PolicyType.

Valeur retournée

WinUsb_SetPowerPolicy retourne TRUE si l’opération réussit. Sinon, cette fonction retourne FALSE et l’appelant peut récupérer l’erreur journalisée en appelant GetLastError.

GetLastError peut retourner le code d’erreur suivant.

Code de retour	Description
ERROR_INVALID_HANDLE	L’appelant a passé la valeur NULL dans le paramètre InterfaceHandle .
ERROR_INVALID_PARAMETER	L’appelant a passé une taille non valide pour la mémoire tampon de paramètre de stratégie dans le paramètre ValueLength .
ERROR_NOT_ENOUGH_MEMORY	Indique que la mémoire est insuffisante pour effectuer l’opération.

Remarques

La liste suivante récapitule les effets des modifications apportées aux états de gestion de l’alimentation :

Tous les handles de canal, les poignées d’interface, les verrous et les autres paramètres sont conservés dans les événements de gestion de l’alimentation.
Tous les transferts en cours sont suspendus lorsqu’un appareil passe à un état d’alimentation faible, et ils sont repris lorsque l’appareil est restauré à un état de fonctionnement.
L’appareil et le système doivent être à l’état opérationnel avant que le client puisse restaurer une configuration spécifique à l’appareil. Les clients peuvent déterminer si l’appareil et le système sont dans un état opérationnel à partir du message WM_POWERBROADCAST.
Le client peut indiquer qu’une interface est inactive en appelant WinUsb_SetPowerPolicy.