Função WdfDeviceGetSystemPowerAction (wdfdevice.h)

  • Artigo

[Aplica-se a KMDF e UMDF]

O método WdfDeviceGetSystemPowerAction retorna a ação de energia do sistema, se houver, que está ocorrendo no momento para o computador.

Sintaxe

POWER_ACTION WdfDeviceGetSystemPowerAction(
  [in] WDFDEVICE Device
);

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de estrutura.

Retornar valor

WdfDeviceGetSystemPowerAction retorna um valor de enumerador tipo POWER_ACTION. O valor indica a ação de energia do sistema que está ocorrendo no momento para o computador. Para obter mais informações, consulte a seção Comentários a seguir. A enumeração POWER_ACTION é definida em wdm.h.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

A partir do WDF versão 1.31/2.31 (conhecido como "v31"), wdfDeviceGetSystemPowerAction foi atualizado para relatar com mais precisão a ação de energia do sistema quando o dispositivo é o proprietário da política de energia. Os drivers precisam ser recompilados com a v31 ou posterior para obter o seguinte novo comportamento:

  • Se o dispositivo entrar ou sair de D0 devido a S0 Ocioso (consulte WdfDeviceAssignS0IdleSettings) enquanto uma transição de energia do sistema não relacionada estiver em andamento, WdfDeviceGetSystemPowerAction poderá retornar PowerActionSleep. Isso foi corrigido na v31 e agora retorna PowerActionNone.

  • Quando o sistema é ativado do Suspensão Híbrida (suspensão com um arquivo de hibernação), antes da v31, WdfDeviceGetSystemPowerAction sempre retornava PowerActionHibernate. Isso foi corrigido na v31 e agora ele retorna:

    • PowerActionSleep se ele acordar sem perda de energia, o que significa que o sistema permaneceu no S3
    • PowerActionHibernate se ele é ativado após a perda de energia, o que significa que o sistema foi retomado do arquivo de hibernação

O método WdfDeviceGetSystemPowerAction permite que um driver determine se a transição de energia de um dispositivo está ocorrendo porque o dispositivo está ocioso (ou acordando) ou porque todo o computador está entrando (ou saindo) de um estado de baixa potência.

O driver deve chamar WdfDeviceGetSystemPowerAction somente das funções de retorno de chamada de evento que a estrutura chama quando o dispositivo está entrando em um estado de baixa potência ou retornando ao seu estado de trabalho.

O valor retornado por WdfDeviceGetSystemPowerAction depende das seguintes situações:

  • Se o computador estiver entrando em um estado de baixa potência quando o driver chamar WdfDeviceGetSystemPowerAction, o método retornará o motivo pelo qual o computador está entrando no estado de baixa potência. Por exemplo, o método retornará PowerActionSleep se o computador estiver inserindo seu estado de baixa potência S1, S2 ou S3.
  • Se o computador estiver retornando ao estado de trabalho (S0) de um estado de baixa potência quando o driver chamar WdfDeviceGetSystemPowerAction, o método retornará o motivo pelo qual o computador entrou no estado de baixa potência. Por exemplo, o método retornará PowerActionSleep se o computador estiver deixando seu estado de baixa potência S1, S2 ou S3.
  • Se o computador estiver ligando (depois de ter sido desativado) quando o driver chamar WdfDeviceGetSystemPowerAction, o método retornará PowerActionNone.
  • Se o dispositivo estiver entrando em um estado ocioso de baixa potência ou retornando ao estado de trabalho (D0) quando o driver chama WdfDeviceGetSystemPowerAction, enquanto o restante do sistema permanece em seu estado de trabalho (S0), o método retorna PowerActionNone.
  • Se o computador e o dispositivo estiverem em seus estados de trabalho quando o driver chamar WdfDeviceGetSystemPowerAction, o método retornará PowerActionNone.
Para obter mais informações sobre estados de baixa energia, consulte Um dispositivo entra em um estado de Low-Power.

Exemplos

O exemplo de código a seguir obtém a atividade de transição de energia que está ocorrendo no momento para o computador.

POWER_ACTION SysPowerAction;

SysPowerAction = WdfDeviceGetSystemPowerAction(device);

Requisitos

Requisito Valor
Plataforma de Destino Universal
Versão mínima do KMDF 1,9
Versão mínima do UMDF 2,0
Cabeçalho wdfdevice.h (inclua Wdf.h)
Biblioteca Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL <= DISPATCH_LEVEL
Regras de conformidade da DDI DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)