PTRANSFER_CODEC_VERBS回调函数 (hdaudio.h)

项目
02/26/2024

TransferCodecVerbs 例程将一个或多个命令传输到编解码器或编解码器，并检索对这些命令的响应。

TransferCodecVerbs 例程的函数指针类型定义如下。

语法

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

参数

[in] _context

指定HDAUDIO_BUS_INTERFACE、HDAUDIO_BUS_INTERFACE_V2或HDAUDIO_BUS_INTERFACE_BDL结构的 Context 成员中的上下文值。

[in] Count

指定 codecTransfer 数组中的元素数。

[in, out] CodecTransfer

指向 HDAUDIO_CODEC_TRANSFER 结构的数组的指针。每个数组元素都是一个结构，其中包含调用方输出命令的存储以及来自编解码器的相应输入响应。

[in] Callback

指向回调例程的函数指针。此参数是 HDAUDIO_TRANSFER_COMPLETE_CALLBACK 类型的函数指针。参数可以指定为 NULL。有关更多信息，请参见下面的“备注”部分。

[in] Context

回调例程的上下文值。调用方将上下文值强制转换为 PVOID 类型。异步完成命令后，HD 音频总线驱动程序将上下文值作为调用参数传递给回调例程。

返回值

如果调用成功，TransferCodecVerbs 将返回STATUS_SUCCESS。否则，例程将返回相应的错误代码。下表显示了可能的返回状态代码。

返回代码	说明
STATUS_NO_MEMORY	指示由于非分页内存不足，无法将请求添加到命令队列。

注解

此例程将一个或多个编解码器命令提交到 HD 音频总线驱动程序。总线驱动程序向编解码器发出命令，检索编解码器对命令的响应，并将响应输出给调用方。

调用方指定HDAUDIO_CODEC_TRANSFER结构数组中的命令。每个结构都包含命令和编解码器对该命令的响应的存储。在调用 TransferCodecVerbs 之前，调用方将填充数组中每个结构中的命令。每个命令完成后，HD 音频总线驱动程序将检索编解码器的响应并将其写入结构。最后一个命令完成后，调用方可以从数组中读取响应。

例程可以同步或异步运行：

如果调用方为输入参数回调的值指定 NULL，则 HD 音频总线驱动程序将同步完成编解码器Transfer 数组中的命令。 (换句话说，只有在编解码器处理了所有命令并且这些命令的响应可用后，例程才会返回。)
如果调用方为回调参数指定非 NULL 值，则例程将异步运行。 (换句话说，例程在将命令添加到其内部队列后立即返回，而无需等待编解码器处理所有命令。) 编解码器处理命令后，HD 音频总线驱动程序调用回调例程。在异步情况下，调用方不应在总线驱动程序调用回调例程之前尝试读取对命令的响应。

回调参数的函数指针类型定义为：

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

第一个调用参数是指向 codecTransfer 数组元素的指针，该元素包含编解码器命令和触发回调的响应。第二个调用参数与之前在 TransferCodecVerbs 例程的 callbackContext 参数中指定的上下文值相同。

如果成功， TransferCodecVerbs 将返回STATUS_SUCCESS。此状态代码的含义取决于例程是同步运行还是异步运行：

在同步情况下， (回调为 NULL) ，STATUS_SUCCESS表示总线驱动程序具有编解码器Transfer 数组中的所有命令，并且例程已将这些命令的所有响应写入数组。但是，调用方必须检查单个响应，以确定它们是否有效。由于编解码器超时或 FIFO 溢出，单个响应可能无效。
在异步情况下， (回调为非 NULL) ，STATUS_SUCCESS仅表示例程已成功将命令添加到 HD 音频总线驱动程序的内部队列。在总线驱动程序调用回调例程之前，调用方不得尝试读取对这些命令的响应。

如果响应因 FIFO 溢出而无效，则可能是因为编解码器响应了命令，但由于 RIRB () 的响应输入通道缓冲区大小不足而丢失。如果 FIFO 溢出不是导致无效响应的原因，则可能是因为编解码器没有及时响应 (超时) 而发生故障。在这种情况下，调用方可以假定命令未到达编解码器。

如果回调参数为 NULL，则调用方必须在 IRQL PASSIVE_LEVEL运行。如果回调为非 NULL，则调用方可以在 IRQL <= DISPATCH_LEVEL 调用 TransferCodecVerbs，在这种情况下，调用将立即返回，而无需等待编解码器处理所有命令;命令完成后，HD 音频总线驱动程序会在 IRQL DISPATCH_LEVEL调用回调例程。

调用方必须分配非分页池中的 编解码器Transfer 数组。