Функция waveOutOpen (mmeapi.h)

Статья
08/24/2023

Функция waveOutOpen открывает для воспроизведения заданное устройство вывода звуковой формы волны.

Синтаксис

MMRESULT waveOutOpen(
  LPHWAVEOUT      phwo,
  UINT            uDeviceID,
  LPCWAVEFORMATEX pwfx,
  DWORD_PTR       dwCallback,
  DWORD_PTR       dwInstance,
  DWORD           fdwOpen
);

Параметры

phwo

Указатель на буфер, который получает дескриптор, определяющий открытое устройство вывода звуковой формы волн. Используйте дескриптор для идентификации устройства при вызове других функций вывода волновой формы и звука. Этот параметр может иметь значение NULL , если флаг WAVE_FORMAT_QUERY указан для параметра fdwOpen.

uDeviceID

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

Значение	Значение
WAVE_MAPPER	Функция выбирает устройство вывода звукового сигнального формата, которое может воспроизводиться в заданном формате.

pwfx

Указатель на структуру WAVEFORMATEX , которая определяет формат звуковых данных, отправляемых на устройство. Эту структуру можно освободить сразу после передачи в waveOutOpen.

dwCallback

Задает механизм обратного вызова. Это должно быть одно из следующих значений.

Указатель на функцию обратного вызова. Сигнатуру функции см. в разделе waveOutProc.
Дескриптор окна.
Идентификатор потока.
Дескриптор события.
Значение NULL.

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

dwInstance

Данные экземпляра пользователя, передаваемые механизму обратного вызова. Этот параметр не используется с механизмом обратного вызова окна.

fdwOpen

Флаги для открытия устройства. Определены следующие значения.

Значение	Значение
CALLBACK_EVENT	Параметр dwCallback является дескриптором события.
CALLBACK_FUNCTION	Параметр dwCallback является адресом процедуры обратного вызова.
CALLBACK_NULL	Нет механизма обратного вызова. Это параметр по умолчанию.
CALLBACK_THREAD	Параметр dwCallback является идентификатором потока.
CALLBACK_WINDOW	Параметр dwCallback является дескриптором окна.
WAVE_ALLOWSYNC	Если этот флаг указан, можно открыть синхронное устройство waveform-audio. Если этот флаг не указан при открытии синхронного драйвера, устройство не откроется.
WAVE_MAPPED_DEFAULT_COMMUNICATION_DEVICE	Если этот флаг указан и параметр uDeviceIDWAVE_MAPPER, функция открывает устройство связи по умолчанию. Этот флаг применяется, только если uDeviceID равно WAVE_MAPPER. Примечание Требуется Windows 7
WAVE_FORMAT_DIRECT	Если этот флаг указан, драйвер ACM не выполняет преобразования звуковых данных.
WAVE_FORMAT_QUERY	Если этот флаг указан, waveOutOpen запрашивает устройство, чтобы определить, поддерживает ли оно заданный формат, но устройство фактически не открыто.
WAVE_MAPPED	Если этот флаг указан, параметр uDeviceID указывает устройство waveform-audio для сопоставления волн.

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

Возвращает MMSYSERR_NOERROR в случае успешного выполнения или ошибки в противном случае. Возможные значения ошибок:

Код возврата	Описание
MMSYSERR_ALLOCATED	Указанный ресурс уже выделен.
MMSYSERR_BADDEVICEID	Указанный идентификатор устройства выходит за пределы диапазона.
MMSYSERR_NODRIVER	Отсутствует драйвер устройства.
MMSYSERR_NOMEM	Не удается выделить или заблокировать память.
WAVERR_BADFORMAT	Предпринята попытка открыть с неподдерживаемым форматом waveform-audio.
WAVERR_SYNC	Устройство является синхронным, но метод waveOutOpen был вызван без использования флага WAVE_ALLOWSYNC .

Используйте функцию waveOutGetNumDevs , чтобы определить количество устройств вывода сигналов и аудио, присутствующих в системе. Если значение, указанное параметром uDeviceID , является идентификатором устройства, оно может варьироваться от нуля до одного меньше, чем количество присутствующих устройств. Константу WAVE_MAPPER также можно использовать в качестве идентификатора устройства.

Структура, на которую указывает pwfx , может быть расширена для включения сведений о типе для определенных форматов данных. Например, для данных PCM добавляется дополнительный UINT для указания количества битов на выборку. В этом случае используйте структуру PCMWAVEFORMAT . Для всех остальных форматов waveform-audio используйте структуру WAVEFORMATEX , чтобы указать длину дополнительных данных.

Если вы решили, чтобы окно или поток получали сведения о обратном вызове, в функцию процедуры window отправляются следующие сообщения, указывающие на ход выполнения вывода звуковой формы волн: MM_WOM_OPEN, MM_WOM_CLOSE и MM_WOM_DONE.

Механизм обратного вызова

Параметры dwCallback и fdwOpen указывают, как приложение получает уведомления о ходе вывода waveform-audio.

Если параметр fdwOpen содержит флаг CALLBACK_FUNCTION , dwCallback является указателем на функцию обратного вызова. Сигнатуру функции см. в разделе waveOutProc. Параметр uMsg обратного вызова указывает ход выполнения вывода звука:

Если параметр fdwOpen содержит флаг CALLBACK_WINDOW , dwCallback является дескриптором для окна. Окно получает следующие сообщения, указывающие на ход выполнения:

Если параметр fdwOpen содержит флаг CALLBACK_THREAD , dwCallback является идентификатором потока. Поток получает сообщения, перечисленные ранее для CALLBACK_WINDOW.

Если параметр fdwOpen содержит флаг CALLBACK_EVENT , dwCallback является дескриптором события. Событие получает сигнал при каждом изменении состояния буфера формы волн. Приложение может использовать WaitForSingleObject или WaitForMultipleObjects для ожидания события. При сигнале о событии можно получить текущее состояние буфера формы волн, проверив член dwFlags структуры WAVEHDR . (См . waveOutPrepareHeader.)

Если параметр fdwOpen содержит флаг CALLBACK_NULL , параметр dwCallback должен иметь значение NULL. В этом случае механизм обратного вызова не используется.

Требования


Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	mmeapi.h (включая Windows.h)
Библиотека	Winmm.lib
DLL	Winmm.dll