PTRANSFER_CODEC_VERBS fonction de rappel (hdaudio.h)

Article
02/07/2025

Les TransferCodecVerbs routine transfèrent une ou plusieurs commandes vers un codec ou un codec et récupère les réponses à ces commandes.

Le type de pointeur de fonction d’un TransferCodecVerbs routine est défini comme suit.

Syntaxe

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

Paramètres

[in] _context

Spécifie la valeur de contexte du membre Context de la structure HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2, ou HDAUDIO_BUS_INTERFACE_BDL.

[in] Count

Spécifie le nombre d’éléments dans le tableau codecTransfer.

[in, out] CodecTransfer

Pointeur vers un tableau de structures HDAUDIO_CODEC_TRANSFER. Chaque élément de tableau est une structure qui contient le stockage pour une commande de sortie à partir de l’appelant et la réponse d’entrée correspondante du codec.

[in] Callback

Pointeur de fonction vers une routine de rappel. Ce paramètre est un pointeur de fonction de type HDAUDIO_TRANSFER_COMPLETE_CALLBACK. Le paramètre peut être spécifié comme NULL . Pour plus d’informations, consultez la section Remarques suivante.

[in] Context

Valeur de contexte pour la routine de rappel. L’appelant convertit la valeur de contexte en type PVOID. Une fois les commandes terminées de façon asynchrone, le pilote de bus AUDIO HD transmet la valeur de contexte à la routine de rappel en tant que paramètre d’appel.

Valeur de retour

TransferCodecVerbs retourne STATUS_SUCCESS si l’appel réussit. Sinon, la routine retourne un code d’erreur approprié. Le tableau suivant montre un code d’état de retour possible.

Retourner le code	Description
STATUS_NO_MEMORY	Indique que la requête n’a pas pu être ajoutée à la file d’attente de commandes en raison d’une pénurie de mémoire non paginée.

Remarques

Cette routine envoie une ou plusieurs commandes de codec au pilote de bus HD Audio. Le pilote bus émet les commandes aux codecs, récupère les réponses des codecs aux commandes et génère les réponses à l’appelant.

L’appelant spécifie les commandes dans un tableau de structures HDAUDIO_CODEC_TRANSFER. Chaque structure contient le stockage d’une commande et de la réponse du codec à cette commande. Avant d’appeler TransferCodecVerbs, l’appelant remplit les commandes de chacune des structures du tableau. À mesure que chaque commande se termine, le pilote de bus AUDIO HD récupère la réponse du codec et l’écrit dans la structure. Une fois la dernière commande terminée, l’appelant peut lire les réponses à partir du tableau.

La routine peut fonctionner de manière synchrone ou asynchrone :

Si l’appelant spécifie NULL pour la valeur du paramètre d’entrée de rappel, le pilote de bus AUDIO HD termine les commandes dans le tableau codecTransfer synchrone. (En d’autres termes, la routine retourne uniquement une fois que les codecs ont traité toutes les commandes et les réponses à ces commandes sont disponibles.)
Si l’appelant spécifie une valeur deNULL non pour le paramètre de rappel , la routine fonctionne de façon asynchrone. (En d’autres termes, la routine retourne immédiatement après l’ajout des commandes à sa file d’attente interne sans attendre que les codecs traitent toutes les commandes.) Une fois que les codecs traitent les commandes, le pilote de bus AUDIO HD appelle la routine de rappel. Dans le cas asynchrone, l’appelant ne doit pas tenter de lire les réponses aux commandes avant que le pilote bus appelle la routine de rappel.

Le type de pointeur de fonction pour le paramètre de rappel est défini comme suit :

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

Le premier paramètre d’appel est un pointeur vers l’élément de tableau codecTransfer qui contient la commande codec et la réponse qui a déclenché le rappel. Le deuxième paramètre d’appel est la même valeur de contexte que celle spécifiée précédemment dans les TransferCodecVerbs paramètre callbackContext de routine.

Si elle réussit, TransferCodecVerbs retourne STATUS_SUCCESS. La signification de ce code d’état dépend du fonctionnement synchrone ou asynchrone de la routine :

Dans le cas synchrone (rappel est NULL), STATUS_SUCCESS signifie que le pilote de bus a toutes les commandes du tableau codecTransfer dans les codecs et que la routine a écrit toutes les réponses à ces commandes dans le tableau. Toutefois, l’appelant doit vérifier les réponses individuelles pour déterminer si elles sont valides. Les réponses individuelles peuvent ne pas être valides en raison de dépassements de délai d’expiration de codec ou de FIFO.
Dans le cas asynchrone (rappel n’est pasnull), STATUS_SUCCESS signifie que la routine a correctement ajouté les commandes à la file d’attente interne du pilote de bus Audio HD. L’appelant ne doit pas tenter de lire les réponses à ces commandes tant que le pilote bus n’appelle pas la routine de rappel.

Si une réponse n’est pas valide en raison d’un dépassement fiFO, la cause probable est que le codec a répondu à la commande, mais que la réponse a été perdue en raison d’une mémoire tampon d’anneau d’entrée de réponse insuffisante (RIRB). Si un dépassement FIFO n’est pas la cause de la réponse non valide, l’échec s’est probablement produit parce que le codec n’a pas répondu dans le temps (expiré). Dans ce cas, l’appelant peut supposer que la commande n’a pas atteint le codec.

Si le paramètre de rappel est NULL, l’appelant doit s’exécuter au PASSIVE_LEVEL IRQL. Si de rappel n’est pasNULL, l’appelant peut appeler TransferCodecVerbs au <IRQL = DISPATCH_LEVEL, auquel cas l’appel retourne immédiatement sans attendre que les codecs traitent toutes les commandes ; une fois les commandes terminées, le pilote de bus AUDIO HD appelle la routine de rappel au DISPATCH_LEVEL IRQL.

L’appelant doit allouer le tableau codecTransfer à partir du pool non paginé.