Método IWDFDevice2::AssignSxWakeSettings (wudfddi.h)

Artigo
02/07/2025

[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 AssignSxWakeSettings fornece informações fornecidas pelo driver sobre a capacidade de um dispositivo de disparar um sinal de ativação enquanto o dispositivo e o sistema estão em um estado de baixa potência.

Sintaxe

HRESULT AssignSxWakeSettings(
  [in] DEVICE_POWER_STATE                    DxState,
  [in] WDF_POWER_POLICY_SX_WAKE_USER_CONTROL UserControlOfWakeSettings,
  [in] WDF_TRI_STATE                         Enabled
);

Parâmetros

[in] DxState

Um enumerador tipo DEVICE_POWER_STATEque identifica o estado de energia do dispositivo de baixa que o dispositivo entrará quando o estado de energia do sistema for removido para um estado de baixa potência acionável. O valor de DxState não pode ser powerDeviceD0. DEVICE_POWER_STATE valores são definidos em wdm.h.

[in] UserControlOfWakeSettings

Um enumerador tipo WDF_POWER_POLICY_SX_WAKE_USER_CONTROLque indica se os usuários têm a capacidade de modificar as configurações de ativação do dispositivo.

[in] Enabled

Um enumerador tipo WDF_TRI_STATEque indica se o dispositivo pode ativar o sistema (ou seja, restaurar o sistema para S0) quando o sistema estiver em um estado de baixa potência. Esse membro pode ter um dos seguintes valores:

WdfTrue – Acordar o sistema está habilitado.

WdfFalse – Acordar o sistema está desabilitado.

WdfUseDefault – Acordar o sistema é inicialmente habilitado por padrão; mas se o membro UserControlOfWakeSettings estiver definido como WakeAllowUserControl, a configuração do usuário ou o arquivo INF do driver substituirá o valor inicial.

Se o sistema estiver habilitado e o sistema estiver prestes a entrar em um estado de baixa potência, a estrutura chamará o do driver IPowerPolicyCallbackWakeFromSx::OnArmWakeFromSx função de retorno de chamada antes que o dispositivo insira um estado de baixa potência.

Valor de retorno

AssignSxWakeSettings 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
E_INVALIDARG	O chamador especificou um valor inválido para um parâmetro de entrada.
HRESULT_FROM_NT(STATUS_INVALID_DEVICE_REQUEST)	O driver de chamada não é o proprietário da política de energia do dispositivo.
HRESULT_FROM_NT(STATUS_POWER_STATE_INVALID)	O parâmetro DxState especifica um estado de energia de dispositivo inválido ou o motorista do barramento indica que o dispositivo não pode disparar um sinal de ativação,

Esse método pode retornar um dos outros valores que Winerror.h contém.

Observações

Na primeira vez que um driver chama AssignSxWakeSettings, as seguintes ações ocorrem:

A estrutura armazena os valores de parâmetro.
Se o parâmetro UserControlOfWakeSettings estiver definido como WakeAllowUserControl e se o parâmetro Enabled estiver definido como WdfUseDefault, a estrutura lerá o registro para descobrir se o usuário habilitou a ativação do sistema.

Durante as chamadas subsequentes para AssignSxWakeSettings, a estrutura não armazena o valor do parâmetro UserControlOfWakeSettings. Em outras palavras, a estrutura executa as seguintes etapas na primeira vez que o driver chama AssignSxWakeSettings mas não durante chamadas posteriores:

Armazena o valor do parâmetro UserControlOfWakeSettings.
Procura uma configuração de usuário no registro, se o valor do parâmetro Enabled for WdfUseDefault.

As regras a seguir se aplicam ao valor especificado para o parâmetro DxState:

O valor não pode ser PowerDeviceD0.
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.
Não é possível 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 do Registro que controlam os recursos de ativação 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 de ativação de um dispositivo, consulte suporte a Wake-Up de sistema em drivers baseados em UMDF.

O exemplo de código a seguir obtém a interface de IWDFDevice2 e, em seguida, chama AssignSxWakeSettings.

    IWDFDevice2 *pIWDFDevice2 = NULL;
    HRESULT hr;

    //
    // Get a pointer to the IWDFDevice2 interface.
    //
    hr = pIWDFDevice->QueryInterface(__uuidof(IWDFDevice2),
                                     (void**) &pIWDFDevice2);
    if (SUCCEEDED(hr)) 
    {
        hr = pIWDFDevice2->AssignSxWakeSettings(PowerDeviceMaximum,
                                                WakeAllowUserControl,
                                                WdfUseDefault);
    }
...
    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

Consulte também

IWDFDevice2

IWDFDevice2::AssignS0IdleSettings

Compartilhar via