EVT_ACX_CIRCUIT_POWER_DOWN funzione di callback (acxcircuit.h)

Articolo
02/22/2024

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 dei valori NTSTATUS.

Commenti

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 il proprio stato di lavoro (D0). Un dispositivo lascia lo stato D0 quando si verifica una delle condizioni seguenti:

Il sistema e tutti i suoi dispositivi stanno per lasciare i loro stati di lavoro e entrare in uno stato di bassa potenza.
Il dispositivo sta per entrare in uno stato di bassa potenza perché è inattiva, se il dispositivo supporta l'inattività a basso consumo.
Il manager 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 la disabilitazione degli interrupt del dispositivo, ma prima che l'alimentazione 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 bassa specificato, ad esempio il salvataggio di tutte le informazioni necessarie al driver in un secondo momento per ripristinare l'hardware di ACXCIRCUIT allo 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 della risorsa. 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 nel 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 di ACX

Versione minima di ACX: 1.0

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

Requisiti

Requisito	Valore
Intestazione	acxcircuit.h
IRQL	PASSIVE_LEVEL

Condividi tramite