Método IWDFDevice2::AssignS0IdleSettings (wudfddi.h)
[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum novo recurso está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Drivers universais do Windows devem usar UMDF 2. Para obter mais informações, consulte Introdução com UMDF.]
O método AssignS0IdleSettings fornece informações fornecidas pelo driver que a estrutura usa quando um dispositivo está ocioso e o sistema está em seu estado de trabalho (S0).
Sintaxe
HRESULT AssignS0IdleSettings(
[in] WDF_POWER_POLICY_S0_IDLE_CAPABILITIES IdleCaps,
[in] DEVICE_POWER_STATE DxState,
[in] ULONG IdleTimeout,
[in] WDF_POWER_POLICY_S0_IDLE_USER_CONTROL UserControlOfIdleSettings,
[in] WDF_TRI_STATE Enabled
);
Parâmetros
[in] IdleCaps
Um enumerador de tipo WDF_POWER_POLICY_S0_IDLE_CAPABILITIES que identifica a capacidade do dispositivo de se ativar depois de ser definido como um estado de baixa potência, enquanto o sistema permanece em seu estado de trabalho (S0).
[in] DxState
Um enumerador de tipo DEVICE_POWER_STATE que identifica o estado de energia do dispositivo baixo que o dispositivo inserirá após o término do período de tempo limite ocioso. DEVICE_POWER_STATE valores são definidos em wdm.h.
[in] IdleTimeout
A quantidade de tempo, em milissegundos, de que o dispositivo permanecerá ocioso antes que a estrutura o coloque no estado de baixa energia fornecido por DxState. Para usar o valor de tempo limite ocioso padrão da estrutura, especifique IdleTimeoutDefaultValue Para obter mais informações, consulte a seção Comentários.
[in] UserControlOfIdleSettings
Um enumerador de tipo WDF_POWER_POLICY_S0_IDLE_USER_CONTROL que indica se os usuários têm a capacidade de modificar as configurações ociosas do dispositivo.
[in] Enabled
Um enumerador de tipo WDF_TRI_STATE que indica se o dispositivo será desligado se permanecer ocioso e enquanto a energia do sistema estiver em S0. Esse membro pode ter um dos seguintes valores:
WdfTrue – a energia está habilitada.
WdfFalse – a desligar está desabilitada.
WdfUseDefault – a ativação para desligar é inicialmente habilitada por padrão; mas se o parâmetro UserControlOfIdleSettings estiver definido como IdleAllowUserControl, a configuração do usuário ou o arquivo INF do driver substituirá o valor inicial.
Se a ativação estiver habilitada, o dispositivo terá uma funcionalidade de ativação e o valor de tempo limite ocioso expirará, a estrutura chamará a função de retorno de chamada IPowerPolicyCallbackWakeFromS0::OnArmWakeFromS0 do driver antes que o dispositivo entre em um estado de baixa potência.
Retornar valor
AssignS0IdleSettings retornará S_OK se a operação for bem-sucedida. Caso contrário, o método poderá retornar um dos seguintes valores:
| Código de retorno | Descrição |
|---|---|
|
O chamador especificou um valor inválido para um parâmetro de entrada. |
|
O driver de chamada não é o proprietário da política de energia do dispositivo. |
|
O parâmetro DxState especifica um estado de energia de dispositivo inválido ou o parâmetro IdleCaps indica que o dispositivo pode ser ativado, mas o driver de barramento indica que o dispositivo não pode se ativar. |
Esse método pode retornar um dos outros valores que Winerror.h contém.
Comentários
Na primeira vez que um driver chama AssignS0IdleSettings, as seguintes ações ocorrem:
- A estrutura armazena os valores de todos os parâmetros.
- Se o parâmetro UserControlOfIdleSettings estiver definido como IdleAllowUserControl e se o parâmetro Enabled estiver definido como WdfUseDefault, a estrutura lerá o Registro para descobrir se o usuário habilitou a desligar o dispositivo quando ele estiver ocioso.
- Se o driver tiver especificado IdleCanWakeFromS0 para o valor do parâmetro IdleCaps em uma chamada anterior para AssignS0IdleSettings, ele não poderá alterar posteriormente esse valor para IdleUsbSelectiveSuspend.
- Se o driver tiver especificado IdleUsbSelectiveSuspend para o valor do parâmetro IdleCaps em uma chamada anterior para AssignS0IdleSettings, ele não poderá alterar posteriormente esse valor para IdleCanWakeFromS0.
As regras a seguir se aplicam ao valor especificado para o parâmetro DxState :
- O valor não pode ser PowerDeviceD0.
- Para dispositivos USB, o valor não pode ser PowerDeviceD0 ou PowerDeviceD3.
- Se você especificar DevicePowerMaximum, a estrutura usará o valor que o driver do modo kernel para o barramento do dispositivo fornecido no membro DeviceWake de sua estrutura WDF_DEVICE_POWER_CAPABILITIES .
- Se o valor do parâmetro IdleCaps for IdleCanWakeFromS0 ou IdleUsbSelectiveSuspend, você não poderá especificar um estado de energia do dispositivo inferior ao estado de energia do dispositivo no membro DeviceWake da estrutura WDF_DEVICE_POWER_CAPABILITIES do driver de barramento no modo kernel. (Em outras palavras, se o valor DeviceWake do driver de barramento for PowerDeviceD2, o valor DxState do driver de função não poderá ser PowerDeviceD3.)
Para obter informações sobre entradas do Registro que controlam os recursos ociosos de um dispositivo, consulte Controle de usuário do dispositivo ocioso e comportamento de ativação no UMDF.
Para obter mais informações sobre como dar suporte aos recursos ociosos de um dispositivo, consulte Suporte a Power-Down ociosas em drivers baseados em UMDF.
Exemplos
O exemplo de código a seguir baseia-se na versão UMDF do exemplo de torradeira. O exemplo obtém a interface IWDFDevice2 e chama AssignS0IdleSettings.
IWDFDevice2 *pIWDFDevice2 = NULL;
HRESULT hr;
//
// Get a pointer to the IWDFDevice2 interface.
//
hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
(void**) &pIWDFDevice2);
if (SUCCEEDED(hr))
{
//
// The toaster device is virtual, so we tell the framework that the
// device cannot wake if it sleeps while the system is in S0. The device
// can return to D0 only when the driver stack receives an I/O request.
//
hr = pIWDFDevice2->AssignS0IdleSettings(IdleCannotWakeFromS0,
PowerDeviceD3,
IDLEWAKE_TIMEOUT_MSEC,
IdleAllowUserControl,
WdfTrue);
}
...
SAFE_RELEASE(pIWDFDevice2);
Requisitos
| Requisito | Valor |
|---|---|
| Fim do suporte | Indisponível no UMDF 2.0 e posterior. |
| Plataforma de Destino | Área de Trabalho |
| Versão mínima do UMDF | 1,9 |
| Cabeçalho | wudfddi.h (include Wudfddi.h) |
| DLL | WUDFx.dll |