PTRANSFER_CODEC_VERBS funzione di callback (hdaudio.h)

Articolo
07/27/2023

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

Il tipo di puntatore a funzione per una routine TransferCodecVerbs è 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_V2oHDAUDIO_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 sia per un comando di output del chiamante che per 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 ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in] Context

Valore di contesto per la routine di callback. Il chiamante esegue il cast del valore di 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.

Commenti

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 l'archiviazione sia per un comando che per la risposta del codec a tale comando. Prima di chiamare TransferCodecVerbs, il chiamante compila 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 callback del parametro di input, il driver del bus audio HD completa i comandi nella matrice codecTransfer 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 valore non NULL per il parametro di callback , la routine opera in modo asincrono. In altre parole, la routine restituisce immediatamente dopo l'aggiunta dei comandi alla coda interna senza attendere che i codec elaborino 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 della matrice codecTransfer 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 TransferCodecVerbs.

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 sovraccarico FIFO.
Nel caso asincrono (il callback è diverso da NULL), STATUS_SUCCESS significa solo che la routine ha aggiunto correttamente i comandi alla coda interna del driver audio HD. Il chiamante non deve tentare di leggere le risposte a tali comandi finché il driver 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 circolare di input della risposta di dimensioni insufficienti (RIRB). Se un sovraccarico FIFO non è la causa della risposta non valida, l'errore probabilmente si è verificato 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 IRQL PASSIVE_LEVEL. Se il callback è diverso da 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.