EVT_ACX_CIRCUIT_POWER_DOWN Rückruffunktion (acxcircuit.h)

Der EVT_ACX_CIRCUIT_POWER_DOWN Rückruf wird vom Treiber verwendet, um Funktionen im Power-Down-Pfad eines ACXCIRCUIT-Objekts hinzuzufügen.

Syntax

EVT_ACX_CIRCUIT_POWER_DOWN EvtAcxCircuitPowerDown;

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

Parameter

Device

Ein WDFDEVICE-Objekt (beschrieben in WDF – Zusammenfassung von Frameworkobjekten), das dem angegebenen ACXCIRCUIT zugeordnet ist.

Circuit

Das ACXCIRCUIT-Objekt (beschrieben in Zusammenfassung von ACX-Objekten) ist heruntergefahren.

TargetState

Ein WDF_POWER_DEVICE_STATE typisierten Enumerator, der den Geräteleistungszustand identifiziert, in den das Gerät gerade eintritt.

Rückgabewert

Gibt zurück STATUS_SUCCESS , wenn der Aufruf erfolgreich war. Andernfalls wird ein geeigneter Fehlercode zurückgegeben. Weitere Informationen finden Sie unter Verwenden von NTSTATUS-Werten.

Hinweise

Um eine EvtAcxCircuitPrepareHardware-Rückruffunktion zu registrieren, muss ein Treiber AcxCircuitInitSetAcxCircuitPnpPowerCallbacks aufrufen.

Wenn der Treiber eine EvtCircuitPowerDown-Rückruffunktion registriert hat, ruft das ACX-Framework die Funktion jedes Mal auf, wenn eines der Treibergeräte seinen Arbeitszustand (D0) verlässt. Ein Gerät verlässt den D0-Zustand, wenn eine der folgenden Aktionen auftritt:

  • Das System und alle seine Geräte sind dabei, ihren Arbeitszustand zu verlassen und in einen Low-Power-Zustand zu wechseln.
  • Das Gerät wird in einen Energiesparzustand versetzt, da es sich im Leerlauf befindet, wenn das Gerät den Leerlauf mit geringem Stromverbrauch unterstützt.
  • Der Plug & Play-Manager versucht, die Hardwareressourcen des Systems neu zu verteilen.
  • Ein Benutzer hat in der Regel über die Benutzeroberfläche einer Anwendung angegeben, dass er das Gerät entfernen möchte.
  • Das Framework ruft auch die Rückruffunktion EvtCircuitPowerDown auf, nachdem ein Gerät unerwartet entfernt wurde (überraschend entfernt).

Weitere Informationen dazu, wann das Framework diese Rückruffunktion aufruft, finden Sie unter PnP- und Energieverwaltungsszenarien.

Sofern das Gerät nicht überraschend entfernt wurde, ruft das ACX-Framework diese Rückruffunktion sofort nach der Deaktivierung der Unterbrechungen des Geräts auf, aber bevor die Leistung des Geräts von D0 verringert wird und bevor WDF den EvtDeviceD0Exit-Rückruf des Treibers auf den zugehörigen Geräten aufruft. Der Parameter TargetState gibt den Geräteleistungszustand an, den das Gerät im Begriff ist, zu wechseln.

Die EvtCircuitPowerDown-Rückruffunktion muss alle Erforderlichen Vorgänge ausführen, bevor die Hardware des ACXCIRCUT in den angegebenen Energiesparzustand wechselt, z. B. das Speichern von Informationen, die der Treiber später benötigt, um die Hardware des ACXCIRCUIT in ihren D0-Energiezustand wiederherzustellen.

Wenn TargetState den Wert WdfPowerDeviceD3Final aufweist, sollten Sie davon ausgehen, dass das System ausgeschaltet wird, das zugeordnete Gerät entfernt wird oder dass ein Ressourcenausgleich ausgeführt wird. Wenn Ihr Treiber Informationen speichern muss, sollte er sie auf den Datenträger oder ein anderes permanentes Speichermedium schreiben.

Weitere Informationen zu Treibern, die diese Rückruffunktion bereitstellen, finden Sie unter Unterstützen der PnP- und Energieverwaltung im Funktionstreiber.

Beispiel

Das Beispiel für die Verwendung ist unten dargestellt. Dieses Beispiel zeigt das Beenden einiger Timerinstanzen im Testcode, wenn die Verbindung ausgeschaltet wurde.

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

ACX-Anforderungen

ACX-Mindestversion: 1.0

Weitere Informationen zu ACX-Versionen finden Sie unter ACX-Versionsübersicht.

Anforderungen

Anforderung Wert
Header acxcircuit.h
IRQL PASSIVE_LEVEL

Weitere Informationen