WaveOutGetVolume

MMRESULT waveOutGetVolume( HWAVEOUT hwo, LPDWORD pdwVolume );

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

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

• MMSYSERR_INVALHANDLE — указан недопустимый дескриптор устройства.

• MMSYSERR_NODRIVER — отсутствует драйвер устройства.

• MMSYSERR_NOMEM — невозможно выделить или заблокировать память.

• MMSYSERR_NOTSUPPORTED — указанное устройство не позволяет регулировать уровень воспроизведения.

Аргументы

0. hwo — дескриптор открытого устройства вывода аудио информации. В данном аргументе может передаваться идентификатор устройства.

1. pdwVolume — указатель на переменную, в которую будет записано текущее значение уровня воспроизведения. Младшее слово этой переменной содержит уровень воспроизведения по левому каналу, а старшее слово — по правому каналу. Значение 0xFFFF соответствует максимальному уровню воспроизведения, а значение 0x0000 — тишине.

2. Если устройство не допускает раздельной регулировки по левому и правому каналам, уровень воспроизведения монофонического сигнала будет содержаться в младшем слове данной переменной.

3. Информация возвращается в полном 16-битовом формате, используемом в функции waveOutSetVolume независимо от того, какой формат уровня воспроизведения используется в устройстве.

Примечание

Функция waveOutGetVolume позволяет получить текущий уровень воспроизведения, установленный на указанном устройстве вывода аудио информации.

Если в качестве аргумента данной функции используется идентификатор устройства, то информация, возвращаемая в аргументе pdwVolume, относится ко всем реализациям данного устройства. При использовании дескриптора устройства информация возвращается только по той реализации устройства, которая связана с данным дескриптором

Не все устройства позволяют регулировать уровень воспроизведения. Для определения того, позволяет ли данное устройство регулировать уровень воспроизведения, следует вызвать функцию waveOutGetDevCaps и проверить состояние флага WAVECAPS_VOLUME в переменной dwSupport возвращаемого ей объекта структуры WAVEOUTCAPS.

Для определения того, позволяет ли данное устройство раздельно регулировать уровень воспроизведения по левому и правому каналам следует вызвать функцию waveOutGetDevCaps и проверить состояние флага WAVECAPS_LRVOLUME в переменной dwSupport возвращаемого ей объекта структуры WAVEOUTCAPS.

Значения уровней воспроизведения задаются в логарифмической шкале. Этому субъективный уровень повышения громкости будет одинаковым при повышении уровня воспроизведения с 0x5000 до 0x6000 и с 0x4000 до 0x5000.

Описание данной функции содержится в файле заголовка mmsystem.h. При работе с данной функцией следует включить в проект библиотеку winmm.lib.

WaveOutOpen

MMRESULT waveOutOpen( LPHWAVEOUT phwo, UINT uDeviceID, LPWAVEFORMATEX pwfx, DWORD dwCallback, DWORD dwCallbackInstance, DWORD fdwOpen );

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

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

• MMSYSERR_ALLOCATED — указанный ресурс уже распределён.

• MMSYSERR_BADDEVICEID — указанный идентификатор устройства находится за пределами допустимого диапазона значений.

• MMSYSERR_NODRIVER — отсутствуют драйверы устройств.

• MMSYSERR_NOMEM — невозможно выделить или заблокировать память.

• WAVERR_BADFORMAT — указанный аудио формат не поддерживается.

• WAVERR_SYNC — указано синхронное устройство, но в функции waveOutOpen не установлен флаг WAVE_ALLOWSYNC.

Аргументы

0. phwo — указатель на область памяти, в которую будет записан дескриптор открываемого аудио устройство. Этот дескриптор будет использоваться для идентификации аудио устройства при вызове функций. Если в аргументе fdwOpen установлен флаг WAVE_FORMAT_QUERY данный аргумент должен иметь нулевое значение.

1. uDeviceID — идентификатор открываемого аудио устройства. В данном аргументе может передаваться как идентификатор устройства, так и дескриптор открытого аудио устройства ввода. В данном аргументе может указываться константа WAVE_MAPPER, указывающая на то, что функция сама выберет аудио устройство, способное выводить аудио информацию в указанном формате.

2. pwfx — указатель на объект структуры WAVEFORMATEX, содержащей описание формата выводимой аудио информации. Этот объект структуры может быть уничтожен сразу после завершения работы функции waveOutOpen.

3. dwCallback — адрес функции обратного вызова, дескриптора события, дескриптора окна или идентификатор потока, используемых для обработки сообщений, посылаемых в процессе воспроизведения аудио информации. Если эти сообщения не нуждаются в обработке, то данный аргумент должен иметь нулевое значение. Формат функции обратного вызова должен соответствовать формату функции waveOutProc.

4. dwCallbackInstance — пользовательские данные, используемые в механизме обратного вызова. Этот аргумент не используется при обработке сообщений обратного вызова функцией окна.

5. fdwOpen — флаги, определяющие режим открытия устройства. Определены следующие значения:

• CALLBACK_EVENT — в аргументе dwCallback передаётся дескриптор события.

• CALLBACK_FUNCTION — в аргументе dwCallback передаётся указатель на функцию обратного вызова.

• CALLBACK_NULL — механизм обратного вызова не используется.

• CALLBACK_THREAD — в аргументе dwCallback передаётся идентификатор потока.

• CALLBACK_WINDOW — в аргументе dwCallback передаётся дескриптор окна.

• WAVE_ALLOWSYNC — открывается синхронное устройство вывода аудио информации. Если этот флаг не установлен, открытие синхронного драйвера завершится с ошибкой.

• WAVE_FORMAT_DIRECT — при выводе аудио информации не производится её преобразование драйвером ACM.

• WAVE_FORMAT_QUERY — функция waveOutOpen используется для проверки возможности работы с указанным аудио форматом. При этом никакое аудио устройство не открывается.

• WAVE_MAPPED — аргумент uDeviceID определяет аудио устройство, выбираемое функцией.

Примечание

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

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

Объект структуры, на который указывает аргумент pwfx, может быть расширен для хранения информации, специфичной для данного формата аудио информации. Например, для формата ИКМ к данной структуре добавляется дополнительная переменная формата UINT для хранения числа бит на отсчёт. Для данной структуры существует собственное имя PCMWAVEFORMAT. Для всех остальных форматов используется структура WAVEFORMATEX, содержащая специальную переменную, указывающую на размер дополнительного блока памяти, размещаемого за объектом данной структуры.

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

При использовании функции обратного в процессе вывода аудио информации ей посылаются сообщения WOM_OPEN, WOM_CLOSE и WOM_DONE.

Описание данной функции содержится в файле заголовка mmsystem.h. При работе с данной функцией следует включить в проект библиотеку winmm.lib.