PTRANSFER_CODEC_VERBS Rückruffunktion (hdaudio.h)

Artikel
07/27/2023

Die TransferCodecVerbs-Routine überträgt einen oder mehrere Befehle an einen Codec oder codecs und ruft die Antworten auf diese Befehle ab.

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

Syntax

PTRANSFER_CODEC_VERBS PtransferCodecVerbs;

NTSTATUS PtransferCodecVerbs(
  [in]      PVOID _context,
  [in]      ULONG Count,
  [in, out] PHDAUDIO_CODEC_TRANSFER CodecTransfer,
  [in]      PHDAUDIO_TRANSFER_COMPLETE_CALLBACK Callback,
  [in]      PVOID Context
)
{...}

Parameter

[in] _context

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

[in] Count

Gibt die Anzahl der Elemente im CodecTransfer-Array an.

[in, out] CodecTransfer

Zeiger auf ein Array von HDAUDIO_CODEC_TRANSFER Strukturen. Jedes Arrayelement ist eine Struktur, die sowohl Speicher für einen Ausgabebefehl des Aufrufers als auch die entsprechende Eingabeantwort des Codecs enthält.

[in] Callback

Funktionszeiger auf eine Rückrufroutine. Dieser Parameter ist ein Funktionszeiger vom Typ HDAUDIO_TRANSFER_COMPLETE_CALLBACK. Der Parameter kann als NULL angegeben werden. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".

[in] Context

Ein Kontextwert für die Rückrufroutine. Der Aufrufer wandelt den Kontextwert in den Typ PVOID um. Nachdem die Befehle asynchron abgeschlossen wurden, übergibt der HD Audio-Bustreiber den Kontextwert als Aufrufparameter an die Rückrufroutine.

Rückgabewert

TransferCodecVerbs gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Andernfalls gibt die Routine einen entsprechenden Fehlercode zurück. Die folgende Tabelle zeigt eine mögliche Rückgabe status Code.

Rückgabecode	Beschreibung
STATUS_NO_MEMORY	Gibt an, dass die Anforderung der Befehlswarteschlange aufgrund eines Mangels an nicht auslagerten Arbeitsspeicher nicht hinzugefügt werden konnte.

Hinweise

Diese Routine übermittelt mindestens einen Codecbefehl an den HD Audio Bus-Treiber. Der Bustreiber gibt die Befehle an die Codecs aus, ruft die Antworten der Codecs auf die Befehle ab und gibt die Antworten an den Aufrufer aus.

Der Aufrufer gibt die Befehle in einem Array von HDAUDIO_CODEC_TRANSFER Strukturen an. Jede Struktur enthält Speicher sowohl für einen Befehl als auch für die Antwort des Codecs auf diesen Befehl. Vor dem Aufrufen von TransferCodecVerbs füllt der Aufrufer die Befehle in jeder Struktur im Array aus. Nach Abschluss jedes Befehls ruft der HD Audio-Bustreiber die Antwort des Codecs ab und schreibt sie in die Struktur. Nach Abschluss des letzten Befehls kann der Aufrufer die Antworten aus dem Array lesen.

Die Routine kann synchron oder asynchron ausgeführt werden:

Wenn der Aufrufer NULL für den Wert des Eingabeparameterrückrufs angibt, schließt der HD Audio-Bustreiber die Befehle im CodecTransfer-Array synchron ab. (Mit anderen Worten, die Routine wird erst zurückgegeben, nachdem die Codecs alle Befehle verarbeitet haben und die Antworten auf diese Befehle verfügbar sind.)
Wenn der Aufrufer einen Wert ohne NULL für den Rückrufparameter angibt, wird die Routine asynchron ausgeführt. (Mit anderen Worten, die Routine kehrt sofort nach dem Hinzufügen der Befehle zur internen Warteschlange zurück, ohne darauf zu warten, dass die Codecs alle Befehle verarbeiten.) Nachdem die Codecs die Befehle verarbeitet haben, ruft der HD Audio-Bustreiber die Rückrufroutine auf. Im asynchronen Fall sollte der Aufrufer nicht versuchen, die Antworten auf die Befehle zu lesen, bevor der Bustreiber die Rückrufroutine aufruft.

Der Funktionszeigertyp für den Rückrufparameter ist definiert wie folgt:

typedef VOID
  (*PHDAUDIO_TRANSFER_COMPLETE_CALLBACK)
    (HDAUDIO_CODEC_TRANSFER *, PVOID);

Der erste Aufrufparameter ist ein Zeiger auf das codecTransfer-Arrayelement , das den Codec-Befehl und die Antwort enthält, die den Rückruf ausgelöst hat. Der zweite Aufrufparameter ist derselbe Kontextwert, der zuvor im callbackContext-Parameter der TransferCodecVerbs-Routine angegeben wurde.

Bei erfolgreicher Ausführung gibt TransferCodecVerbs STATUS_SUCCESS zurück. Die Bedeutung dieses status Codes hängt davon ab, ob die Routine synchron oder asynchron ausgeführt wird:

Im synchronen Fall (Rückruf ist NULL) bedeutet STATUS_SUCCESS, dass der Bustreiber über alle Befehle im CodecTransferarray an die Codecs verfügt und dass die Routine alle Antworten auf diese Befehle in das Array geschrieben hat. Der Aufrufer muss jedoch die einzelnen Antworten überprüfen, um festzustellen, ob sie gültig sind. Einzelne Antworten können aufgrund von Codectimeouts oder FIFO-Überschreitungen ungültig sein.
Im asynchronen Fall (Rückruf ist nicht NULL) bedeutet STATUS_SUCCESS nur, dass die Routine die Befehle erfolgreich der internen Warteschlange des HD Audio-Bustreibers hinzugefügt hat. Der Aufrufer darf erst versuchen, die Antworten auf diese Befehle zu lesen, bis der Bustreiber die Rückrufroutine aufruft.

Wenn eine Antwort aufgrund eines FIFO-Überlaufs ungültig ist, ist die ursache wahrscheinlich, dass der Codec auf den Befehl reagiert hat, die Antwort jedoch aufgrund eines nicht ausreichend großen Antworteingaberingpuffers (RIRB) verloren ging. Wenn ein FIFO-Überlauf nicht die Ursache für die ungültige Antwort ist, ist der Fehler wahrscheinlich aufgetreten, weil der Codec nicht rechtzeitig reagiert hat (Timeout). In diesem Fall kann der Aufrufer davon ausgehen, dass der Befehl den Codec nicht erreicht hat.

Wenn der RückrufparameterNULL ist, muss der Aufrufer bei IRQL PASSIVE_LEVEL ausgeführt werden. Wenn der Rückruf nicht NULL ist, kann der Aufrufer TransferCodecVerbs unter IRQL <= DISPATCH_LEVEL aufrufen. In diesem Fall wird der Aufruf sofort zurückgegeben, ohne darauf zu warten, dass die Codecs alle Befehle verarbeiten. Nach Abschluss der Befehle ruft der HD Audio-Bustreiber die Rückrufroutine bei IRQL DISPATCH_LEVEL auf.

Der Aufrufer muss das codecTransfer-Array aus dem nicht auslagerten Pool zuordnen.