PSET_DMA_ENGINE_STATE Rückruffunktion (hdaudio.h)

Artikel
02/07/2025

Die SetDmaEngineState Routine legt den Zustand eines oder mehrerer DMA-Module auf den Zustand "Running", "Stopped", "Paused" oder "Reset" fest.

Der Funktionszeigertyp für eine SetDmaEngineState Routine wird 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 Context Member der HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2oder HDAUDIO_BUS_INTERFACE_BDL Struktur an.

[in] StreamState

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

PauseState- (angehalten)
ResetState- (Zurücksetzen)
RunState- (wird ausgeführt)
StopState- (beendet)

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

[in] NumberOfHandles

Gibt die Anzahl der Ziehpunkte im Handles Array an. Legen Sie diesen Parameter auf einen Wert ungleich Null fest.

[in] Handles

Zeigen Sie auf ein Array von Ziehpunkten auf DMA-Engines. Geben Sie einen Wert ohneNULL- für diesen Parameter an.

Rückgabewert

SetDmaEngineState gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist, die Zustände der DMA-Engines zu ändern. Andernfalls gibt die Routine einen geeigneten Fehlercode zurück. In der folgenden Tabelle sind einige der möglichen Rückgabestatuscodes aufgeführt.

Rückgabecode	Beschreibung
STATUS_INVALID_HANDLE	Gibt an, dass eines der Ziehpunkte ungültig ist.
STATUS_INVALID_PARAMETER	Gibt an, dass einer der Parameterwerte falsch ist (ungültiger Parameterwert oder ungültiger Zeiger).
STATUS_INVALID_DEVICE_REQUEST	Gibt an, dass derzeit kein Puffer für eines der DMA-Module zugeordnet ist.

Bemerkungen

Diese Routine ändert den Zustand eines oder mehrerer DMA-Module in den Zustand, den der streamState-parameter angibt. Die Routine synchronisiert die Zustandsübergänge aller DMA-Module, die die Ziehpunkte in der behandeln, Array identifizieren. Weitere Informationen finden Sie unter Synchronisieren von zwei oder mehr Streams.

Richten Sie vor dem Aufrufen dieser Routine jedes DMA-Moduls in der Arrays ein:

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

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

Der Datenstromstatus kann nicht direkt zwischen "Ausführen" und "Zurücksetzen" übertragen werden. Stattdessen muss der Datenstrom zuerst einen Zwischenzustand von "Angehalten" oder "Beendet" durchlaufen:

Aus einem Zustand "Ausführen" oder "Zurücksetzen" kann sich der Datenstromstatus direkt in "Angehalten" oder "Beendet" ändern.
Aus einem angehaltenen oder angehaltenen Zustand kann sich der Datenstromstatus direkt in "Ausführen" oder "Zurücksetzen" ändern.

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