função WinUsb_SetPowerPolicy (winusb.h)

Artigo
03/13/2024

A função WinUsb_SetPowerPolicy define a política de energia de um dispositivo.

Sintaxe

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

Parâmetros

[in] InterfaceHandle

Um identificador opaco para a primeira interface (padrão) no dispositivo, que é retornado por WinUsb_Initialize.

[in] PolicyType

Um valor que especifica a política de energia a ser definida. A tabela a seguir descreve constantes simbólicas definidas em winusbio.h.

Parâmetro de política	Descrição
AUTO_SUSPEND (0x81)	Especifica o tipo de política de suspensão automática; o parâmetro de política de energia deve ser especificado pelo chamador no parâmetro Value . Para a suspensão automática, o parâmetro Value deve apontar para uma variável UCHAR. Se Value for TRUE (diferente de zero), a pilha USB suspenderá o dispositivo se o dispositivo estiver ocioso. Um dispositivo fica ocioso se não houver transferências pendentes ou se as únicas transferências pendentes forem TRANSFERÊNCIAS IN para interromper ou pontos de extremidade em massa. O valor padrão é determinado pelo valor definido na configuração do registro DefaultIdleState . Por padrão, esse valor é TRUE.
SUSPEND_DELAY (0x83)	Especifica o tipo de política suspend-delay; o parâmetro de política de energia deve ser especificado pelo chamador no parâmetro Value . Para suspensão-atraso, Value deve apontar para uma variável ULONG. Value especifica a quantidade mínima de tempo, em milissegundos, que o driver WinUSB deve aguardar após a transferência antes que ele possa suspender o dispositivo. O valor padrão é determinado pelo valor definido na configuração do registro DefaultIdleTimeout . Por padrão, esse valor é de cinco segundos.

Parâmetro de política

Descrição

AUTO_SUSPEND

(0x81)

Especifica o tipo de política de suspensão automática; o parâmetro de política de energia deve ser especificado pelo chamador no parâmetro Value .

Para a suspensão automática, o parâmetro Value deve apontar para uma variável UCHAR.

Se Value for TRUE (diferente de zero), a pilha USB suspenderá o dispositivo se o dispositivo estiver ocioso. Um dispositivo fica ocioso se não houver transferências pendentes ou se as únicas transferências pendentes forem TRANSFERÊNCIAS IN para interromper ou pontos de extremidade em massa.

O valor padrão é determinado pelo valor definido na configuração do registro DefaultIdleState . Por padrão, esse valor é TRUE.

SUSPEND_DELAY

(0x83)

Especifica o tipo de política suspend-delay; o parâmetro de política de energia deve ser especificado pelo chamador no parâmetro Value .

Para suspensão-atraso, Value deve apontar para uma variável ULONG.

Value especifica a quantidade mínima de tempo, em milissegundos, que o driver WinUSB deve aguardar após a transferência antes que ele possa suspender o dispositivo.

O valor padrão é determinado pelo valor definido na configuração do registro DefaultIdleTimeout . Por padrão, esse valor é de cinco segundos.

[in] ValueLength

O tamanho, em bytes, do buffer em Valor.

[in] Value

O novo valor para o parâmetro de política de energia. O tipo de dados e o valor de Value dependem do tipo de política de energia passada em PolicyType. Para obter mais informações, consulte PolicyType.

Retornar valor

WinUsb_SetPowerPolicyretornará TRUE se a operação for bem-sucedida. Caso contrário, essa função retornará FALSE e o chamador poderá recuperar o erro registrado chamando GetLastError.

GetLastError pode retornar o código de erro a seguir.

Código de retorno	Descrição
ERROR_INVALID_HANDLE	O chamador passou NULL no parâmetro InterfaceHandle .
ERROR_INVALID_PARAMETER	O chamador passou um tamanho inválido para o buffer de parâmetro de política no parâmetro ValueLength .
ERROR_NOT_ENOUGH_MEMORY	Indica que não há memória suficiente para executar a operação.

Comentários

A lista a seguir resume os efeitos das alterações nos estados de gerenciamento de energia:

Todos os identificadores de pipe, identificadores de interface, bloqueios e configurações alternativas são preservados em eventos de gerenciamento de energia.
Todas as transferências em andamento são suspensas quando um dispositivo é transferido para um estado de baixa energia e são retomadas quando o dispositivo é restaurado para um estado de trabalho.
O dispositivo e o sistema devem estar em um estado de trabalho antes que o cliente possa restaurar uma configuração específica do dispositivo. Os clientes podem determinar se o dispositivo e o sistema estão em um estado de trabalho na mensagem WM_POWERBROADCAST.
O cliente pode indicar que uma interface está ociosa chamando WinUsb_SetPowerPolicy.