Метод IAudioClient::IsFormatSupported (audioclient.h)

Статья
07/20/2023

Метод IsFormatSupported указывает, поддерживает ли устройство конечной точки звука определенный формат потока.

Синтаксис

HRESULT IsFormatSupported(
  [in]  AUDCLNT_SHAREMODE  ShareMode,
  [in]  const WAVEFORMATEX *pFormat,
  [out] WAVEFORMATEX       **ppClosestMatch
);

Параметры

[in] ShareMode

Режим общего доступа для формата потока. С помощью этого параметра клиент указывает, хочет ли он использовать указанный формат в монопольном или общем режиме. Клиент должен задать этому параметру одно из следующих значений перечисления AUDCLNT_SHAREMODE :

AUDCLNT_SHAREMODE_EXCLUSIVE

AUDCLNT_SHAREMODE_SHARED

[in] pFormat

Указатель на указанный формат потока. Этот параметр указывает на дескриптор формата, выделенный вызывающим объектом, типа WAVEFORMATEX или WAVEFORMATEXTENSIBLE. Клиент записывает описание формата в эту структуру перед вызовом этого метода. Сведения о WAVEFORMATEX и WAVEFORMATEXTENSIBLE см. в документации по Windows DDK.

[out] ppClosestMatch

Указатель на переменную указателя, в которую метод записывает адрес структуры WAVEFORMATEX или WAVEFORMATEXTENSIBLE . Эта структура задает поддерживаемый формат, который ближе всего к формату, указанному клиентом с помощью параметра pFormat . Для общего режима (то есть, если параметр ShareMode имеет значение AUDCLNT_SHAREMODE_SHARED) задайте ppClosestMatch так, чтобы он указывал на допустимую переменную указателя, отличной от NULL . Для монопольного режима задайте для параметра ppClosestMatchзначение NULL. Метод выделяет хранилище для структуры. Вызывающий объект отвечает за освобождение хранилища, когда оно больше не требуется, путем вызова функции CoTaskMemFree . Если вызов IsFormatSupported завершается сбоем и параметр ppClosestMatch не равен NULL, метод присваивает *ppClosestMatchзначение NULL. Сведения о CoTaskMemFree см. в документации по Windows SDK.

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

Код возврата	Описание
S_OK	Выполнено успешно, и устройство конечной точки звука поддерживает указанный формат потока.
S_FALSE	Выполнено с ближайшим соответствием указанному формату.
AUDCLNT_E_UNSUPPORTED_FORMAT	Выполнено успешно, но указанный формат не поддерживается в монопольном режиме.

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

Код возврата	Описание
E_POINTER	Параметр pFormat имеет значение NULL, или ppClosestMatch имеет значение NULL , а ShareMode — AUDCLNT_SHAREMODE_SHARED.
E_INVALIDARG	Параметр ShareMode — это значение, отличное от AUDCLNT_SHAREMODE_SHARED или AUDCLNT_SHAREMODE_EXCLUSIVE.
AUDCLNT_E_DEVICE_INVALIDATED	Устройство конечной точки звука было отключено, или звуковое оборудование или связанные аппаратные ресурсы были перенастроены, отключены, удалены или иным образом стали недоступными для использования.
AUDCLNT_E_SERVICE_NOT_RUNNING	Аудиослужба Windows не запущена.

Для монопольного режима IsFormatSupported возвращает S_OK, если устройство конечной точки звука поддерживает формат, указанный вызывающей стороны, или возвращает AUDCLNT_E_UNSUPPORTED_FORMAT, если устройство не поддерживает формат. Параметр ppClosestMatch может иметь значение NULL. Если значение не равно NULL, метод записывает значение NULL в *ppClosestMatch.

Для общего режима, если звуковой модуль поддерживает формат, заданный вызывающим объектом, IsFormatSupported устанавливает для *ppClosestMatchзначение NULL и возвращает S_OK. Если звуковой модуль не поддерживает формат, указанный вызывающим объектом, но поддерживает аналогичный формат, метод получает аналогичный формат с помощью параметра ppClosestMatch и возвращает S_FALSE. Если звуковой модуль не поддерживает формат, указанный вызывающим объектом, или любой другой аналогичный формат, метод присваивает *ppClosestMatchзначение NULL и возвращает AUDCLNT_E_UNSUPPORTED_FORMAT.

В общем режиме обработчик звука всегда поддерживает формат mix, который клиент может получить, вызвав метод IAudioClient::GetMixFormat . Кроме того, звуковой модуль может поддерживать аналогичные форматы, которые имеют ту же частоту выборки и количество каналов, что и формат mix, но отличающиеся по представлению значений выборки звука. Подсистема аудио представляет выборки значений внутри в виде чисел с плавающей запятой, но если формат, заданный вызывающим объектом, представляет выборку значений в виде целых чисел, звуковой механизм обычно может выполнять преобразование между целыми значениями выборки и внутренним представлением с плавающей запятой.

Звуковой модуль может поддерживать еще более широкий диапазон форматов общего режима, если пакет установки для звукового устройства включает объект обработки звука (APO) локальных эффектов (LFX), который может обрабатывать преобразования форматов. APO LFX — это программный модуль, который выполняет обработку аудиопотока для конкретного устройства. Построитель аудио графов в аудиослужбе Windows вставляет APO LFX в поток между каждым клиентом и обработчиком звука. Когда клиент вызывает метод IsFormatSupported и метод определяет, что APO LFX установлен для использования с устройством, метод направляет запрос к APO LFX, который указывает, поддерживает ли он формат, заданный вызывающим объектом.

Например, конкретный объект APO LFX может принимать 6-канальный поток объемного звука от клиента и преобразовывать поток в стереоформат, который можно воспроизводить через наушники. Как правило, APO LFX поддерживает только клиентские форматы с частотой выборки, которая соответствует частоте выборки в формате mix.

Дополнительные сведения об API см. в разделе Объекты обработки звука Windows. Дополнительные сведения о методе IsFormatSupported см. в разделе Форматы устройств.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	audioclient.h

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

Интерфейс IAudioClient

IAudioClient::GetMixFormat

IAudioClient::Initialize