функция обратного вызова PTRANSFER_CODEC_VERBS (hdaudio.h)

  • Статья

Подпрограмма 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

Задает значение контекста из элемента Contextструктуры HDAUDIO_BUS_INTERFACE, HDAUDIO_BUS_INTERFACE_V2илиHDAUDIO_BUS_INTERFACE_BDL.

[in] Count

Указывает количество элементов в массиве codecTransfer .

[in, out] CodecTransfer

Указатель на массив HDAUDIO_CODEC_TRANSFER структур. Каждый элемент массива представляет собой структуру, содержащую хранилище как для выходной команды вызывающего объекта, так и для соответствующего входного ответа от кодека.

[in] Callback

Указатель функции на подпрограмму обратного вызова. Этот параметр является указателем функции типа HDAUDIO_TRANSFER_COMPLETE_CALLBACK. Параметр может быть указан как NULL. Дополнительные сведения см. в разделе "Примечания".

[in] Context

Значение контекста для подпрограммы обратного вызова. Вызывающий объект приводит значение контекста к типу PVOID. После асинхронного выполнения команд драйвер шины HD Audio передает значение контекста в подпрограмму обратного вызова в качестве параметра вызова.

Возвращаемое значение

TransferCodecVerbs возвращает STATUS_SUCCESS, если вызов выполнен успешно. В противном случае подпрограмма возвращает соответствующий код ошибки. В следующей таблице показан возможный код состояния возврата.

Код возврата Описание
STATUS_NO_MEMORY
 Указывает, что запрос не удалось добавить в очередь команд из-за нехватки памяти без памяти.

Комментарии

Эта подпрограмма отправляет одну или несколько команд кодека в драйвер шины HD Audio. Драйвер шины выдает команды кодекам, получает ответы кодеков на команды и выводит ответы вызывающей программе.

Вызывающий объект задает команды в массиве структур HDAUDIO_CODEC_TRANSFER. Каждая структура содержит хранилище для команды и ответа кодека на нее. Перед вызовом TransferCodecVerbs вызывающий объект заполняет команды в каждой из структур в массиве. По завершении каждой команды драйвер шины HD Audio извлекает ответ кодека и записывает его в структуру. После завершения последней команды вызывающий объект может считывать ответы из массива.

Подпрограмма может работать синхронно или асинхронно:

  • Если вызывающий объект задает значение NULL для значения обратного вызова входного параметра, драйвер шины HD Audio выполняет команды в массиве codecTransfer синхронно. (Другими словами, подпрограмма возвращается только после того, как кодеки обработали все команды и ответы на них будут доступны.)
  • Если вызывающий объект задает для параметра обратного вызова значение, отличное от NULL, подпрограмма работает асинхронно. (Другими словами, подпрограмма возвращается сразу после добавления команд во внутреннюю очередь, не дожидаясь, пока кодеки обработают все команды.) После того как кодеки обработают команды, драйвер шины HD Audio вызывает подпрограмму обратного вызова. В асинхронном случае вызывающий объект не должен пытаться считывать ответы на команды до того, как водитель шины вызовет подпрограмму обратного вызова.
Тип указателя функции для параметра обратного вызова определяется следующим образом:
typedef VOID
  (*PHDAUDIO_TRANSFER_COMPLETE_CALLBACK)
    (HDAUDIO_CODEC_TRANSFER *, PVOID);

Первый параметр вызова — это указатель на элемент массива codecTransfer , содержащий команду кодека и ответ, который активировал обратный вызов. Второй параметр вызова — это то же значение контекста, которое было указано ранее в параметре callbackContextподпрограммы TransferCodecVerbs.

В случае успешного выполнения TransferCodecVerbs возвращает STATUS_SUCCESS. Значение этого кода состояния зависит от того, работает ли подпрограмма синхронно или асинхронно:

  • В синхронном случае (обратный вызов имеет значение NULL), STATUS_SUCCESS означает, что драйвер шины имеет все команды в массиве codecTransfer в кодеки, а подпрограмма записала все ответы на эти команды в массив. Однако вызывающий объект должен проверка отдельные ответы, чтобы определить, являются ли они допустимыми. Отдельные ответы могут быть недопустимыми из-за превышения времени ожидания кодека или переполнения FIFO.
  • В асинхронном случае (обратный вызов не равен NULL), STATUS_SUCCESS означает только то, что подпрограмма успешно добавила команды во внутреннюю очередь драйвера шины HD Audio. Вызывающий объект не должен пытаться прочитать ответы на эти команды, пока водитель автобуса не вызовет подпрограмму обратного вызова.
Если ответ является недопустимым из-за переполнения FIFO, вероятной причиной является то, что кодек ответил на команду, но ответ был потерян из-за недостаточного размера кольцевого буфера ответа (RIRB). Если переполнение FIFO не является причиной недопустимого ответа, сбой, вероятно, произошел из-за того, что кодек не ответил вовремя (истекло время ожидания). В этом случае вызывающий объект может предположить, что команда не достигла кодека.

Если параметр обратного вызова имеет значение NULL, вызывающий объект должен выполняться на PASSIVE_LEVEL IRQL. Если обратный вызов не равен NULL, вызывающий объект может вызвать Метод TransferCodecVerbs по адресу IRQL <= DISPATCH_LEVEL. В этом случае вызов возвращается немедленно, не дожидаясь, пока кодеки обработают все команды. После выполнения команд драйвер шины HD Audio вызывает подпрограмму обратного вызова в IRQL DISPATCH_LEVEL.

Вызывающий объект должен выделить массив codecTransfer из непагрегированного пула.

Требования

Требование Значение
Целевая платформа Персональный компьютер
Верхняя часть hdaudio.h (включая Hdaudio.h)
IRQL См. раздел "Примечания".

См. также раздел

HDAUDIO_BUS_INTERFACE

HDAUDIO_BUS_INTERFACE_BDL

HDAUDIO_BUS_INTERFACE_V2

HDAUDIO_CODEC_TRANSFER