Метод IMMDeviceEnumerator::GetDefaultAudioEndpoint (mmdeviceapi.h)

Статья
08/24/2023

Метод GetDefaultAudioEndpoint извлекает конечную точку звука по умолчанию для указанного направления и роли потока данных.

Синтаксис

HRESULT GetDefaultAudioEndpoint(
  [in]  EDataFlow dataFlow,
  [in]  ERole     role,
  [out] IMMDevice **ppEndpoint
);

Параметры

[in] dataFlow

Направление потока данных для устройства конечной точки. Вызывающий объект должен задать для этого параметра одно из следующих двух значений перечисления EDataFlow :

eRender

eCapture

Направление потока данных для устройства отрисовки — eRender. Направление потока данных для устройства захвата — eCapture.

[in] role

Роль устройства конечной точки. Вызывающий объект должен задать для этого параметра одно из следующих значений перечисления ERole :

eConsole

eMultimedia

ECommunications

Дополнительные сведения см. в подразделе "Примечания".

[out] ppEndpoint

Указатель на переменную указателя, в которую метод записывает адрес интерфейса IMMDevice объекта конечной точки для устройства конечной точки аудио по умолчанию. С помощью этого метода вызывающий объект получает подсчитываемую ссылку на интерфейс . Вызывающий объект отвечает за освобождение интерфейса, когда он больше не нужен, путем вызова метода Release интерфейса. Если вызов GetDefaultAudioEndpoint завершается сбоем, *ppDevice имеет значение NULL.

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

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

Код возврата	Описание
E_POINTER	Параметр ppDevice имеет значение NULL.
E_INVALIDARG	Параметр dataflow или role находится вне диапазона.
E_NOTFOUND	Устройство недоступно.
E_OUTOFMEMORY	Недостаточно памяти.

В Windows Vista API MMDevice поддерживает роли устройств , но предоставляемые системой программы пользовательского интерфейса — нет. Пользовательский интерфейс в Windows Vista позволяет пользователю выбрать звуковое устройство по умолчанию для отрисовки и звуковое устройство по умолчанию для захвата. Когда пользователь изменяет устройство отрисовки или записи по умолчанию, система назначает ему все три роли устройства (eConsole, eMultimedia и eCommunications). Таким образом, GetDefaultAudioEndpoint всегда выбирает устройство отрисовки или записи по умолчанию, независимо от того, какая роль указана параметром role . В будущей версии Windows пользовательский интерфейс может позволить пользователю назначать отдельные роли разным устройствам. В этом случае выбор устройства отрисовки или захвата с помощью GetDefaultAudioEndpoint может зависеть от параметра роли . Таким образом, поведение звукового приложения, разработанного для работы в Windows Vista, может измениться при запуске в будущей версии Windows. Дополнительные сведения см . в статье Роли устройств в Windows Vista.

Этот метод извлекает устройство конечной точки по умолчанию для указанного направления потока данных (отрисовка или запись) и роли. Например, клиент может получить устройство воспроизведения консоли по умолчанию, выполнив следующий вызов:


  hr = pDevEnum->GetDefaultAudioEndpoint(
                   eRender, eConsole, &pDeviceOut);

В предыдущем фрагменте кода переменная hr имеет тип HRESULT, pDevEnum — указатель на интерфейс IMMDeviceEnumerator , а pDeviceOut — указатель на интерфейс IMMDevice .

Система Windows может содержать некоторое сочетание конечных звуковых устройств, таких как настольные динамики, высококачественные наушники, настольные микрофоны, гарнитуры с динамиками и микрофонами, а также высокотоковые многоканальные динамики. Пользователь может назначать соответствующие роли устройствам. Например, приложение, управляющее потоками голосовой связи, может вызвать GetDefaultAudioEndpoint , чтобы определить назначенные устройства отрисовки и записи для этой роли.

Если доступно только одно устройство отрисовки или захвата, система всегда назначает все три роли отрисовки или записи для этого устройства. Если методу не удается найти устройство отрисовки или захвата для указанной роли, это означает, что устройство отрисовки или захвата не доступно вообще. Если устройство недоступно, метод задает *ppEndpoint = NULL и возвращает ERROR_NOT_FOUND.

Примеры кода, вызывающие метод GetDefaultAudioEndpoint , см. в следующих разделах:

Требования

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

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

Интерфейс IMMDevice

Интерфейс IMMDeviceEnumerator

Share via