Método IWDFDevice2::AssignS0IdleSettings (wudfddi.h)
[Aviso: UMDF 2 é a versão mais recente do UMDF e substitui o UMDF 1. Todos os novos drivers UMDF devem ser gravados usando UMDF 2. Nenhum recurso novo está sendo adicionado ao UMDF 1 e há suporte limitado para UMDF 1 em versões mais recentes do Windows 10. Os drivers universais do Windows devem usar o UMDF 2. Para obter mais informações, consulte Introdução aoda 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 tipo WDF_POWER_POLICY_S0_IDLE_CAPABILITIESque 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 tipo DEVICE_POWER_STATEque identifica o estado de energia do dispositivo de baixa que o dispositivo entrará 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 DxStateestado de baixa energia fornecido. 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 tipo WDF_POWER_POLICY_S0_IDLE_USER_CONTROLque indica se os usuários têm a capacidade de modificar as configurações ociosas do dispositivo.
[in] Enabled
Um enumerador tipo WDF_TRI_STATEque indica se o dispositivo será desligado se ele permanecer ocioso e enquanto a energia do sistema estiver em S0. Esse membro pode ter um dos seguintes valores:
WdfTrue – a ativação da energia está habilitada.
WdfFalse – a alimentação para baixo está desabilitada.
WdfUseDefault – a ativação para baixo é inicialmente habilitada por padrão; mas se o parâmetro UserControlOfIdleSettings for definido como IdleAllowUserControl, a configuração do usuário ou o arquivo INF do driver substituirá o valor inicial.
Se a ativação for 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 função de retorno de chamada antes que o dispositivo insira um estado de baixa potência.
Valor de retorno
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 se ativar, 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.
Observações
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 habilitado para estiver definido como WdfUseDefault, a estrutura lerá o registro para descobrir se o usuário habilitou a ativação do dispositivo quando ele estiver ocioso.
- Se o driver tiver especificado IdleCanWakeFromS0 para o IdleCaps valor do parâmetro em uma chamada anterior para AssignS0IdleSettings, ele não poderá alterar posteriormente esse valor para IdleUsbSelectiveSuspend.
- Se o driver tiver especificado IdleUsbSelectiveSuspend para o IdleCaps valor do parâmetro 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 do barramento do dispositivo forneceu no DeviceWake membro 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 deviceWake membro da estrutura de 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 de registro que controlam os recursos ociosos de um dispositivo, consulte controle de usuário do comportamento ocioso e de ativação do dispositivo noUMDF.
Para obter mais informações sobre como dar suporte aos recursos ociosos de um dispositivo, consulte suporte a Power-Down ociosos em drivers baseados em UMDF.
Exemplos
O exemplo de código a seguir baseia-se na versão UMDF do exemplo da torradeira. O exemplo obtém a interface de IWDFDevice2 e, em seguida, 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. |
| da Plataforma de Destino | Área de trabalho |
| versão mínima do UMDF | 1.9 |
| cabeçalho | wudfddi.h (inclua Wudfddi.h) |
| de DLL | WUDFx.dll |