PSET_DMA_ENGINE_STATE Rückruffunktion (hdaudio.h)

Artikel
07/27/2023

Die SetDmaEngineState-Routine legt den Status einer oder mehrerer DMA-Engines auf den Status "Running", "Stopped", "Paused" oder "Reset" fest.

Der Funktionszeigertyp für eine SetDmaEngineState-Routine ist wie folgt definiert.

Syntax

PSET_DMA_ENGINE_STATE PsetDmaEngineState;

NTSTATUS PsetDmaEngineState(
  [in] PVOID _context,
  [in] HDAUDIO_STREAM_STATE StreamState,
  [in] ULONG NumberOfHandles,
  [in] PHANDLE Handles
)
{...}

Parameter

[in] _context

Gibt den Kontextwert aus dem Kontextelement der HDAUDIO_BUS_INTERFACE-, HDAUDIO_BUS_INTERFACE_V2- oder HDAUDIO_BUS_INTERFACE_BDL-Struktur an.

[in] StreamState

Gibt den neuen Streamstatus an. Legen Sie diesen Parameter auf einen der folgenden HDAUDIO_STREAM_STATE Enumerationswerte fest:

PauseState (angehalten)
ResetState (zurücksetzen)
RunState (ausgeführt)
StopState (beendet)

In der aktuellen Implementierung stellen PauseState und StopState den gleichen Hardwarezustand dar.

[in] NumberOfHandles

Gibt die Anzahl der Handles im Handles-Array an . Legen Sie diesen Parameter auf einen Wert ohne Zero fest.

[in] Handles

Zeiger auf ein Array von Handles auf DMA-Engines. Geben Sie einen Wert ohne NULL für diesen Parameter an.

Rückgabewert

SetDmaEngineState gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich die Zustände der DMA-Engines ändert. Andernfalls gibt die Routine einen entsprechenden Fehlercode zurück. In der folgenden Tabelle sind einige der möglichen Rückgabecodes status aufgeführt.

Rückgabecode	Beschreibung
STATUS_INVALID_HANDLE	Gibt an, dass einer der Handles ungültig ist.
STATUS_INVALID_PARAMETER	Gibt an, dass einer der Parameterwerte falsch ist (ungültiger Parameterwert oder fehlerhafter Zeiger).
STATUS_INVALID_DEVICE_REQUEST	Gibt an, dass derzeit kein Puffer für eine der DMA-Engines zugewiesen ist.

Hinweise

Diese Routine ändert den Zustand einer oder mehrerer DMA-Engines in den Zustand, den der streamState-Parameter angibt. Die Routine synchronisiert die Zustandsübergänge aller DMA-Engines, die die Handles im Handles-Array identifizieren. Weitere Informationen finden Sie unter Synchronisieren von zwei oder mehr Streams.

Richten Sie vor dem Aufrufen dieser Routine jede DMA-Engine im Handles-Array ein:

Wenn Sie die HDAUDIO_BUS_INTERFACE Version des HD Audio DDI verwenden, rufen Sie AllocateDmaBuffer auf, um die DMA-Engine einzurichten.
Wenn Sie die HDAUDIO_BUS_INTERFACE_BDL Version des DDI verwenden, rufen Sie SetupDmaEngineWithBdl auf, um die DMA-Engine einzurichten.

Wenn derzeit kein DMA-Puffer für eine DMA-Engine im Handles-Array zugewiesen ist, führt ein Versuch, den Stream in einen anderen Zustand als Reset zu ändern, dazu, dass der SetDmaEngineState-Aufruf fehlschlägt und Fehlercode STATUS_INVALID_DEVICE_REQUEST zurückgibt.

Der Streamstatus kann nicht direkt zwischen Ausführen und Zurücksetzen wechseln. Stattdessen muss der Stream zunächst den Zwischenzustand Angehalten oder Beendet durchlaufen:

Vom Status "Ausführen" oder "Zurücksetzen" kann sich der Streamstatus direkt in Angehalten oder beendet ändern.
Von einem angehaltenen oder beendeten Zustand kann sich der Streamstatus direkt in Ausführen oder Zurücksetzen ändern.

Ein WDM-Audiotreiber ruft diese Routine während eines Aufrufs seiner SetState-Methode auf. Beispiel: IMiniportWaveCyclicStream::SetState.