función WinUsb_SetPowerPolicy (winusb.h)

Artículo
08/27/2023

La función WinUsb_SetPowerPolicy establece la directiva de energía de un dispositivo.

Sintaxis

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

Parámetros

[in] InterfaceHandle

Identificador opaco de la primera interfaz (predeterminada) del dispositivo, que devuelve WinUsb_Initialize.

[in] PolicyType

Valor que especifica la directiva de energía que se va a establecer. En la tabla siguiente se describen las constantes simbólicas que se definen en winusbio.h.

Parámetro de directiva	Descripción
AUTO_SUSPEND (0x81)	Especifica el tipo de directiva de suspensión automática; El autor de la llamada debe especificar el parámetro de directiva de energía en el parámetro Value . Para la suspensión automática, el parámetro Value debe apuntar a una variable UCHAR. Si Value es TRUE (distinto de cero), la pila USB suspende el dispositivo si el dispositivo está inactivo. Un dispositivo está inactivo si no hay transferencias pendientes o si las únicas transferencias pendientes son transferencias IN para interrumpir o realizar puntos de conexión masivos. El valor predeterminado viene determinado por el valor establecido en la configuración del Registro DefaultIdleState . De forma predeterminada, este valor es TRUE.
SUSPEND_DELAY (0x83)	Especifica el tipo de directiva suspend-delay; El autor de la llamada debe especificar el parámetro de directiva de energía en el parámetro Value . Para el retraso de suspensión, Value debe apuntar a una variable ULONG. Value especifica la cantidad mínima de tiempo, en milisegundos, que el controlador WinUSB debe esperar tras la transferencia antes de que pueda suspender el dispositivo. El valor predeterminado viene determinado por el valor establecido en la configuración del Registro DefaultIdleTimeout . De manera predeterminada, este valor es de cinco segundos.

Parámetro de directiva

Descripción

AUTO_SUSPEND

(0x81)

Especifica el tipo de directiva de suspensión automática; El autor de la llamada debe especificar el parámetro de directiva de energía en el parámetro Value .

Para la suspensión automática, el parámetro Value debe apuntar a una variable UCHAR.

Si Value es TRUE (distinto de cero), la pila USB suspende el dispositivo si el dispositivo está inactivo. Un dispositivo está inactivo si no hay transferencias pendientes o si las únicas transferencias pendientes son transferencias IN para interrumpir o realizar puntos de conexión masivos.

El valor predeterminado viene determinado por el valor establecido en la configuración del Registro DefaultIdleState . De forma predeterminada, este valor es TRUE.

SUSPEND_DELAY

(0x83)

Especifica el tipo de directiva suspend-delay; El autor de la llamada debe especificar el parámetro de directiva de energía en el parámetro Value .

Para el retraso de suspensión, Value debe apuntar a una variable ULONG.

Value especifica la cantidad mínima de tiempo, en milisegundos, que el controlador WinUSB debe esperar tras la transferencia antes de que pueda suspender el dispositivo.

El valor predeterminado viene determinado por el valor establecido en la configuración del Registro DefaultIdleTimeout . De manera predeterminada, este valor es de cinco segundos.

[in] ValueLength

Tamaño, en bytes, del búfer en Value.

[in] Value

Nuevo valor para el parámetro de directiva de energía. El tipo de datos y el valor de Value dependen del tipo de directiva de energía pasada en PolicyType. Para obtener más información, vea PolicyType.

Valor devuelto

WinUsb_SetPowerPolicy devuelve TRUE si la operación se realiza correctamente. De lo contrario, esta función devuelve FALSE y el autor de la llamada puede recuperar el error registrado llamando a GetLastError.

GetLastError puede devolver el siguiente código de error.

Código devuelto	Descripción
ERROR_INVALID_HANDLE	El llamador pasó NULL en el parámetro InterfaceHandle .
ERROR_INVALID_PARAMETER	El autor de la llamada pasó un tamaño no válido para el búfer de parámetros de directiva en el parámetro ValueLength .
ERROR_NOT_ENOUGH_MEMORY	Indica que no hay memoria suficiente para realizar la operación.

Comentarios

En la lista siguiente se resumen los efectos de los cambios en los estados de administración de energía:

Todos los identificadores de canalización, identificadores de interfaz, bloqueos y configuraciones alternativas se conservan en los eventos de administración de energía.
Las transferencias en curso se suspenden cuando un dispositivo se transfiere a un estado de bajo consumo y se reanudan cuando el dispositivo se restaura a un estado de funcionamiento.
El dispositivo y el sistema deben estar en estado de funcionamiento para que el cliente pueda restaurar una configuración específica del dispositivo. Los clientes pueden determinar si el dispositivo y el sistema están en estado de funcionamiento desde el mensaje WM_POWERBROADCAST.
El cliente puede indicar que una interfaz está inactiva llamando a WinUsb_SetPowerPolicy.