funzione WinUsb_SetPowerPolicy (winusb.h)

Articolo
03/04/2024

La funzione WinUsb_SetPowerPolicy imposta i criteri di alimentazione per un dispositivo.

Sintassi

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

Parametri

[in] InterfaceHandle

Handle opaco per la prima interfaccia (predefinita) nel dispositivo, restituita da WinUsb_Initialize.

[in] PolicyType

Valore che specifica i criteri di alimentazione da impostare. La tabella seguente descrive le costanti simboliche definite in winusbio.h.

Parametro criteri	Descrizione
AUTO_SUSPEND (0x81)	Specifica il tipo di criterio di sospensione automatica; il parametro di power policy deve essere specificato dal chiamante nel parametro Value . Per la sospensione automatica, il parametro Value deve puntare a una variabile UCHAR. Se Value è TRUE (diverso da zero), lo stack USB sospende il dispositivo se il dispositivo è inattiva. Un dispositivo è inattiva se non sono presenti trasferimenti in sospeso o se l'unico trasferimento in sospeso è IN trasferimenti in modo da interrompere o endpoint bulk. Il valore predefinito è determinato dal valore impostato nell'impostazione del Registro di sistema DefaultIdleState . Per impostazione predefinita, questo valore è TRUE.
SUSPEND_DELAY (0x83)	Specifica il tipo di criterio di ritardo di sospensione; il parametro di power policy deve essere specificato dal chiamante nel parametro Value . Per il ritardo della sospensione, Value deve puntare a una variabile ULONG. Il valore specifica la quantità minima di tempo, in millisecondi, che il driver WinUSB deve attendere il trasferimento prima di poter sospendere il dispositivo. Il valore predefinito è determinato dal valore impostato nell'impostazione del Registro di sistema DefaultIdleTimeout . Per impostazione predefinita, questo valore è di cinque secondi.

Parametro criteri

Descrizione

AUTO_SUSPEND

(0x81)

Specifica il tipo di criterio di sospensione automatica; il parametro di power policy deve essere specificato dal chiamante nel parametro Value .

Per la sospensione automatica, il parametro Value deve puntare a una variabile UCHAR.

Se Value è TRUE (diverso da zero), lo stack USB sospende il dispositivo se il dispositivo è inattiva. Un dispositivo è inattiva se non sono presenti trasferimenti in sospeso o se l'unico trasferimento in sospeso è IN trasferimenti in modo da interrompere o endpoint bulk.

Il valore predefinito è determinato dal valore impostato nell'impostazione del Registro di sistema DefaultIdleState . Per impostazione predefinita, questo valore è TRUE.

SUSPEND_DELAY

(0x83)

Specifica il tipo di criterio di ritardo di sospensione; il parametro di power policy deve essere specificato dal chiamante nel parametro Value .

Per il ritardo della sospensione, Value deve puntare a una variabile ULONG.

Il valore specifica la quantità minima di tempo, in millisecondi, che il driver WinUSB deve attendere il trasferimento prima di poter sospendere il dispositivo.

Il valore predefinito è determinato dal valore impostato nell'impostazione del Registro di sistema DefaultIdleTimeout . Per impostazione predefinita, questo valore è di cinque secondi.

[in] ValueLength

Dimensioni, in byte, del buffer in Valore.

[in] Value

Nuovo valore per il parametro di power policy. Il tipo di dati e il valore per Value dipendono dal tipo di criteri di alimentazione passati in PolicyType. Per altre informazioni, vedere PolicyType.

Valore restituito

WinUsb_SetPowerPolicy restituisce TRUE se l'operazione ha esito positivo. In caso contrario, questa funzione restituisce FALSE e il chiamante può recuperare l'errore registrato chiamando GetLastError.

GetLastError può restituire il codice di errore seguente.

Codice restituito	Descrizione
ERROR_INVALID_HANDLE	Il chiamante ha passato NULL nel parametro InterfaceHandle .
ERROR_INVALID_PARAMETER	Il chiamante ha passato una dimensione non valida per il buffer dei parametri dei criteri nel parametro ValueLength .
ERROR_NOT_ENOUGH_MEMORY	Indica che la memoria non è sufficiente per eseguire l'operazione.

Commenti

L'elenco seguente riepiloga gli effetti delle modifiche agli stati di risparmio energia:

Tutti gli handle della pipe, gli handle di interfaccia, i blocchi e le impostazioni alternative vengono mantenuti tra gli eventi di risparmio energia.
Tutti i trasferimenti in corso vengono sospesi quando un dispositivo trasferisce uno stato di alimentazione bassa e vengono ripresi quando il dispositivo viene ripristinato in uno stato di lavoro.
Il dispositivo e il sistema devono trovarsi in uno stato di lavoro prima che il client possa ripristinare una configurazione specifica del dispositivo. I client possono determinare se il dispositivo e il sistema si trovano in uno stato di lavoro dal messaggio di WM_POWERBROADCAST.
Il client può indicare che un'interfaccia è inattiva chiamando WinUsb_SetPowerPolicy.