EVT_ACX_CIRCUIT_POWER_DOWN funzione di callback (acxcircuit.h)

Articolo
02/06/2025

Il callback EVT_ACX_CIRCUIT_POWER_DOWN viene usato dal driver per aggiungere funzionalità nel percorso di spegnimento di un oggetto ACXCIRCUIT.

Sintassi

EVT_ACX_CIRCUIT_POWER_DOWN EvtAcxCircuitPowerDown;

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

Parametri

Device

Oggetto WDFDEVICE (descritto in WDF - Riepilogo degli oggetti framework) associato all'oggetto ACXCIRCUIT specificato.

Circuit

Oggetto ACXCIRCUIT (descritto in Riepilogo degli oggetti ACX) spento.

TargetState

Enumeratore tipizzato WDF_POWER_DEVICE_STATE che identifica lo stato di alimentazione del dispositivo che il dispositivo sta per entrare.

Valore restituito

Restituisce STATUS_SUCCESS se la chiamata ha avuto esito positivo. In caso contrario, restituisce un codice di errore appropriato. Per altre informazioni, vedere Uso di valori NTSTATUS.

Osservazioni

Per registrare una funzione di callback EvtAcxCircuitPrepareHardware, un driver deve chiamare AcxCircuitInitSetAcxCircuitPnpPowerCallbacks.

Se il driver ha registrato una funzione di callback EvtCircuitPowerDown, il framework ACX chiama la funzione ogni volta che uno dei dispositivi del driver lascia lo stato di lavoro (D0). Un dispositivo lascia lo stato D0 quando si verifica uno dei seguenti:

Il sistema e tutti i suoi dispositivi stanno per lasciare i loro stati di lavoro e entrare in uno stato di basso consumo.
Il dispositivo sta per entrare in uno stato a basso consumo perché è inattiva, se il dispositivo supporta l'inattività a basso consumo.
Il gestore Plug and Play sta tentando di ridistribuire le risorse hardware del sistema.
Un utente ha indicato, in genere tramite l'interfaccia utente di un'applicazione, che vuole rimuovere il dispositivo.
Il framework chiama anche la funzione di callback EvtCircuitPowerDown dopo che un dispositivo è stato rimosso in modo imprevisto (rimosso a sorpresa).

Per altre informazioni sui casi in cui il framework chiama questa funzione di callback, vedere Scenari di risparmio energia e PnP.

A meno che il dispositivo non sia stato rimosso a sorpresa, il framework ACX chiama questa funzione di callback immediatamente dopo che disabilita gli interrupt del dispositivo, ma prima che la potenza del dispositivo venga ridotta da D0 e prima che WDF richiami il callback EvtDeviceD0Exit del driver nei dispositivi associati. Il parametro TargetState identifica lo stato di alimentazione del dispositivo che il dispositivo sta per entrare.

La funzione di callback EvtCircuitPowerDown deve eseguire tutte le operazioni necessarie prima che l'hardware di ACXCIRCUT entri nello stato di alimentazione a basso consumo specificato, ad esempio salvando eventuali informazioni che il driver dovrà successivamente ripristinare l'hardware di ACXCIRCUIT sullo stato di alimentazione D0.

Se TargetState è WdfPowerDeviceD3Final, devi presupporre che il sistema sia disattivato, il dispositivo associato sta per essere rimosso o che sia in corso un ribilanciamento delle risorse. Se il driver deve salvare le informazioni, deve scriverlo su disco o su un altro supporto di archiviazione permanente.

Per altre informazioni sui driver che forniscono questa funzione di callback, vedere Supporto di PnP e risparmio energia in Driver di funzione.

Esempio

Di seguito è riportato un esempio di utilizzo. Questo esempio mostra l'arresto di alcune istanze timer nel codice di test quando il circuito è spento.

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;
}

Requisiti ACX

versione minima di ACX: 1.0

Per altre informazioni sulle versioni di ACX, vedere panoramica della versione ACX.

Fabbisogno

Requisito	Valore
intestazione	acxcircuit.h
IRQL	PASSIVE_LEVEL

Condividi tramite