EVT_ACX_CIRCUIT_POWER_DOWN função de retorno de chamada (acxcircuit.h)

Artigo
02/06/2025

O retorno de chamada EVT_ACX_CIRCUIT_POWER_DOWN é usado pelo driver para adicionar funcionalidade no caminho de energia para baixo de um objeto ACXCIRCUIT.

Sintaxe

EVT_ACX_CIRCUIT_POWER_DOWN EvtAcxCircuitPowerDown;

NTSTATUS EvtAcxCircuitPowerDown(
  WDFDEVICE Device,
  ACXCIRCUIT Circuit,
  WDF_POWER_DEVICE_STATE TargetState
)
{...}

Parâmetros

Device

Um objeto WDFDEVICE (descrito em WDF – Resumo dos objetos da estrutura) associado ao ACXCIRCUIT especificado.

Circuit

O objeto ACXCIRCUIT (descrito em Resumo de objetos ACX) foi desligado.

TargetState

Um enumerador digitado WDF_POWER_DEVICE_STATE que identifica o estado de energia do dispositivo que o dispositivo está prestes a inserir.

Valor de retorno

Retorna STATUS_SUCCESS se a chamada foi bem-sucedida. Caso contrário, ele retornará um código de erro apropriado. Para obter mais informações, consulte Usando valores NTSTATUS.

Observações

Para registrar uma função de retorno de chamada EvtAcxCircuitPrepareHardware, um driver deve chamar AcxCircuitInitSetAcxCircuitPnpPowerCallbacks.

Se o driver tiver registrado uma função de retorno de chamada EvtCircuitPowerDown, a estrutura ACX chamará a função sempre que um dos dispositivos do driver deixar seu estado de trabalho (D0). Um dispositivo deixa o estado D0 quando ocorre um destes procedimentos:

O sistema e todos os seus dispositivos estão prestes a deixar seus estados de trabalho e entrar em um estado de baixa potência.
O dispositivo está prestes a entrar em um estado de baixa potência porque ele está ocioso, se o dispositivo dá suporte a ociosidade de baixa potência.
O Gerenciador de Plug and Play está tentando redistribuir os recursos de hardware do sistema.
Um usuário indicou, normalmente por meio da interface do usuário de um aplicativo, que deseja remover o dispositivo.
A estrutura também chama a função de retorno de chamada EvtCircuitPowerDown depois que um dispositivo foi removido inesperadamente (removido surpresa).

Para obter mais informações sobre quando a estrutura chama essa função de retorno de chamada, consulte Cenários de PnP e Gerenciamento de Energia.

A menos que o dispositivo tenha sido removido de surpresa, a estrutura ACX chama essa função de retorno de chamada imediatamente após desabilitar as interrupções do dispositivo, mas antes que a energia do dispositivo seja reduzida de D0 e antes que o WDF invoque o retorno de chamada EvtDeviceD0Exit do driver nos dispositivos associados. O parâmetro TargetState identifica o estado de energia do dispositivo que o dispositivo está prestes a inserir.

A função de retorno de chamada EvtCircuitPowerDown deve executar todas as operações necessárias antes que o hardware do ACXCIRCUT insira o estado de baixa potência especificado, como salvar qualquer informação de que o driver precisará mais tarde para restaurar o hardware do ACXCIRCUIT para seu estado de energia D0.

Se TargetState for WdfPowerDeviceD3Final, você deverá assumir que o sistema está sendo desativado, o dispositivo associado está prestes a ser removido ou um reequilíbrio de recursos está em andamento. Se o driver precisar salvar informações, ele deverá gravá-la no disco ou em algum outro meio de armazenamento permanente.

Para obter mais informações sobre drivers que fornecem essa função de retorno de chamada, consulte Suporte ao PnP e ao Gerenciamento de Energia nodo Driver de Funções.

Exemplo

O uso de exemplo é mostrado abaixo. Este exemplo mostra a interrupção de algumas instâncias de temporizador no código de teste quando o circuito foi desligado.

EVT_ACX_CIRCUIT_POWER_DOWN          CodecR_EvtCircuitPowerDown;

NTSTATUS
CreateCircuit()
{
    ...
    ACX_CIRCUIT_PNPPOWER_CALLBACKS_INIT(&powerCallbacks);
    powerCallbacks.EvtAcxCircuitPowerUp = CodecR_EvtCircuitPowerUp;
    powerCallbacks.EvtAcxCircuitPowerDown = CodecR_EvtCircuitPowerDown;
    AcxCircuitInitSetAcxCircuitPnpPowerCallbacks(circuitInit, &powerCallbacks);
    ...
}

NTSTATUS
CodecR_EvtCircuitPowerDown (
    _In_ WDFDEVICE  Device,
    _In_ ACXCIRCUIT Circuit,
    _In_ WDF_POWER_DEVICE_STATE TargetState
    )
{
    UNREFERENCED_PARAMETER(Device);
    UNREFERENCED_PARAMETER(TargetState);
    
    CODEC_RENDER_CIRCUIT_CONTEXT *  circuitCtx;
    CODEC_MUTE_ELEMENT_CONTEXT *    muteCtx;
    CODEC_VOLUME_ELEMENT_CONTEXT *  volumeCtx;

    PAGED_CODE();
    
    // for testing.
    circuitCtx = GetRenderCircuitContext(Circuit);
    ASSERT(circuitCtx);

    ASSERT(circuitCtx->MuteElement);
    muteCtx = GetCodecMuteElementContext(circuitCtx->MuteElement);
    ASSERT(muteCtx);
    
    ASSERT(muteCtx->Timer);
    WdfTimerStop(muteCtx->Timer, TRUE);

    ASSERT(circuitCtx->VolumeElement);
    volumeCtx = GetCodecVolumeElementContext(circuitCtx->VolumeElement);
    ASSERT(volumeCtx);

    ASSERT(volumeCtx->Timer);
    WdfTimerStop(volumeCtx->Timer, TRUE);

    return STATUS_SUCCESS;
}

Requisitos do ACX

versão mínima do ACX: 1.0

Para obter mais informações sobre versões do ACX, consulte visão geral da versão do ACX.

Requisitos

Requisito	Valor
cabeçalho	acxcircuit.h
IRQL	PASSIVE_LEVEL

Consulte também

cabeçalho acxcircuit.h
suporte a PnP e gerenciamento de energia no do Driver de Funções

Partilhar via