PTRANSFER_CODEC_VERBS funzione di callback (hdaudio.h)

Articolo
07/27/2023

Il TransferCodecVerbs routine trasferisce uno o più comandi a un codec o codec e recupera le risposte a tali comandi.

Il tipo di puntatore di funzione per un TransferCodecVerbs routine viene definito come segue.

Sintassi

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
)
{...}

Parametri

[in] _context

Specifica il valore di contesto del membro context della struttura HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2, o HDAUDIO_BUS_INTERFACE_BDL.

[in] Count

Specifica il numero di elementi nella matrice codecTransfer.

[in, out] CodecTransfer

Puntatore a una matrice di strutture HDAUDIO_CODEC_TRANSFER. Ogni elemento della matrice è una struttura che contiene l'archiviazione per un comando di output del chiamante e la risposta di input corrispondente dal codec.

[in] Callback

Puntatore di funzione a una routine di callback. Questo parametro è un puntatore a funzione di tipo HDAUDIO_TRANSFER_COMPLETE_CALLBACK. Il parametro può essere specificato come NULL. Per altre informazioni, vedere la sezione Osservazioni seguente.

[in] Context

Valore di contesto per la routine di callback. Il chiamante esegue il cast del valore del contesto al tipo PVOID. Dopo aver completato i comandi in modo asincrono, il driver del bus audio HD passa il valore di contesto alla routine di callback come parametro di chiamata.

Valore restituito

TransferCodecVerbs restituisce STATUS_SUCCESS se la chiamata ha esito positivo. In caso contrario, la routine restituisce un codice di errore appropriato. Nella tabella seguente viene illustrato un possibile codice di stato restituito.

Codice restituito	Descrizione
STATUS_NO_MEMORY	Indica che la richiesta non è stata aggiunta alla coda dei comandi a causa di una carenza di memoria non di paging.

Osservazioni

Questa routine invia uno o più comandi codec al driver del bus audio HD. Il driver del bus invia i comandi ai codec, recupera le risposte dei codec ai comandi e restituisce le risposte al chiamante.

Il chiamante specifica i comandi in una matrice di strutture HDAUDIO_CODEC_TRANSFER. Ogni struttura contiene spazio di archiviazione sia per un comando che per la risposta del codec a tale comando. Prima di chiamare TransferCodecVerbs, il chiamante riempie i comandi in ognuna delle strutture della matrice. Al termine di ogni comando, il driver del bus audio HD recupera la risposta del codec e lo scrive nella struttura. Al termine dell'ultimo comando, il chiamante può leggere le risposte dalla matrice.

La routine può operare in modo sincrono o asincrono:

Se il chiamante specifica NULL per il valore del parametro di input callback, il driver del bus audio HD completa i comandi nel codec codecTransfer matrice in modo sincrono. In altre parole, la routine restituisce solo dopo che i codec hanno elaborato tutti i comandi e le risposte a tali comandi sono disponibili.
Se il chiamante specifica un valoreNULL non per il parametro di callback, la routine viene eseguita in modo asincrono. In altre parole, la routine viene restituita immediatamente dopo l'aggiunta dei comandi alla coda interna senza attendere che i codec eselaborino tutti i comandi. Dopo che i codec elaborano i comandi, il driver del bus audio HD chiama la routine di callback. Nel caso asincrono, il chiamante non deve tentare di leggere le risposte ai comandi prima che il driver del bus chiami la routine di callback.

Il tipo di puntatore di funzione per il parametro di callback è definito come:

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

Il primo parametro di chiamata è un puntatore all'elemento codecTransfer matrice che contiene il comando codec e la risposta che ha attivato il callback. Il secondo parametro di chiamata è lo stesso valore di contesto specificato in precedenza nel parametro callbackContext della routine TransferCodecVer bs.

In caso di esito positivo, TransferCodecVerbs restituisce STATUS_SUCCESS. Il significato di questo codice di stato dipende dal fatto che la routine funzioni in modo sincrono o asincrono:

Nel caso sincrono (callback è NULL), STATUS_SUCCESS significa che il driver del bus ha tutti i comandi nella matrice codecTransfer ai codec e che la routine ha scritto tutte le risposte a tali comandi nella matrice. Tuttavia, il chiamante deve controllare le singole risposte per determinare se sono valide. Le singole risposte potrebbero non essere valide a causa di timeout del codec o di sovraccarico FIFO.
Nel caso asincrono (callback non èNULL), STATUS_SUCCESS significa solo che la routine ha aggiunto correttamente i comandi alla coda interna del driver del bus audio HD. Il chiamante non deve tentare di leggere le risposte a tali comandi finché il conducente del bus non chiama la routine di callback.

Se una risposta non è valida a causa di un sovraccarico FIFO, la causa probabile è che il codec ha risposto al comando, ma la risposta è stata persa a causa di un buffer riRB (Response Input Ring Buffer) con dimensioni insufficienti. Se un sovraccarico FIFO non è la causa della risposta non valida, probabilmente si è verificato l'errore perché il codec non ha risposto nel tempo (timeout). In questo caso, il chiamante può presupporre che il comando non abbia raggiunto il codec.

Se il parametro di callback è NULL, il chiamante deve essere in esecuzione in PASSIVE_LEVEL IRQL. Se di callback non èNULL, il chiamante può chiamare TransferCodecVerbs in IRQL <= DISPATCH_LEVEL, nel qual caso la chiamata viene restituita immediatamente senza attendere che i codec elaborino tutti i comandi; al termine dei comandi, il driver del bus audio HD chiama la routine di callback in IRQL DISPATCH_LEVEL.

Il chiamante deve allocare la matrice codecTransfer dal pool non di paging.