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

Статья
08/24/2023

Функция waveInMessage отправляет сообщения драйверам устройств ввода waveform-audio.

Синтаксис

MMRESULT waveInMessage(
  HWAVEIN   hwi,
  UINT      uMsg,
  DWORD_PTR dw1,
  DWORD_PTR dw2
);

Параметры

hwi

Идентификатор устройства с формой волны, которое получает сообщение. Необходимо привести идентификатор устройства к типу дескриптора HWAVEIN . Если вместо идентификатора устройства указать дескриптор, функция завершается ошибкой и возвращает код ошибки MMSYSERR_NOSUPPORT.

uMsg

Сообщение для отправки.

dw1

Параметр сообщения.

dw2

Параметр сообщения.

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

Возвращает значение, возвращенное драйвером.

Для DRV_QUERYDEVICEINTERFACEdwParam1 — это указатель на буфер, выделенный вызывающим объектом, в который функция записывает строку Юникода, завершающуюся null, содержащую имя интерфейса устройства. Если у устройства нет интерфейса устройства, длина строки равна нулю.

Для DRV_QUERYDEVICEINTERFACEdwParam2 указывает размер буфера в байтах. Это входной параметр функции. Вызывающий объект должен указать размер, который больше или равен размеру буфера, полученному сообщением DRV_QUERYDEVICEINTERFACESIZE .

Сообщение DRV_QUERYDEVICEINTERFACE поддерживается в Windows Me, Windows 2000 и более поздних версиях. Это сообщение допустимо только для функций waveInMessage, waveOutMessage, midiInMessage, midiOutMessage и mixerMessage . Система перехватывает это сообщение и возвращает соответствующее значение, не отправляя сообщение драйверу устройства. Общие сведения о функциях xxxMessage , перехваченных системой, см. в разделе Сообщения устройства, перехваченные системой.

Следующие две константы сообщений используются вместе для получения имен интерфейсов устройств:

DRV_QUERYDEVICEINTERFACESIZE
DRV_QUERYDEVICEINTERFACE

Первое сообщение получает размер буфера, необходимого для хранения строки, содержащей имя интерфейса устройства, в байтах. Второе сообщение извлекает строку имени в буфере требуемого размера.

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

Сообщение DRV_QUERYDEVICEINTERFACESIZE запрашивает размер буфера, необходимый для хранения имени интерфейса устройства.

Для DRV_QUERYDEVICEINTERFACESIZEdwParam1 является указателем на размер буфера. Этот параметр указывает на переменную ULONG, в которую функция записывает требуемый размер буфера в байтах. Размер включает дисковое пространство для завершающего значения NULL строки имени. Размер равен нулю, если идентификатор устройства идентифицирует устройство без интерфейса устройства.

Для DRV_QUERYDEVICEINTERFACESIZEdwParam2 не используется. Задайте для этого параметра нулевое значение.

Это сообщение допустимо только для функций waveInMessage, waveOutMessage, midiInMessage, midiOutMessage и mixerMessage . Система перехватывает это сообщение и возвращает соответствующее значение, не отправляя сообщение драйверу устройства. Общие сведения о функциях xxxMessage , перехваченных системой, см. в разделе Сообщения устройства, перехваченные системой.

Размер буфера, полученный этим сообщением, выражается в виде количества байтов. Он указывает размер буфера, необходимого для хранения строки Юникода, завершающейся null, которая содержит имя интерфейса устройства. Вызывающий объект выделяет буфер указанного размера и использует сообщение DRV_QUERYDEVICEINTERFACE для получения строки имени интерфейса устройства.

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

Сообщение DRV_QUERYDEVNODE запрашивает номер devnode, назначенный устройству диспетчером Plug and Play.

Для DRV_QUERYDEVNODEdwParam1 — это указатель на выделенную вызывающим объектом переменную DWORD, в которую функция записывает номер devnode. Если устройству не назначено devnode, функция устанавливает для этой переменной нулевое значение.

Для DRV_QUERYDEVNODEdwParam2 не используется. Задайте для этого параметра нулевое значение.

В Windows 2000 и более поздних версиях сообщение всегда возвращает MMSYSERR_NOTSUPPORTED. Это сообщение допустимо только для функций waveInMessage, waveOutMessage, midiInMessage, midiOutMessage и mixerMessage . Система перехватывает это сообщение и возвращает соответствующее значение, не отправляя сообщение драйверу устройства. Общие сведения о функциях xxxMessage , перехваченных системой, см. в разделе Сообщения устройства, перехваченные системой.

Сообщение DRV_QUERYMAPPABLE запрашивает, может ли указанное устройство использоваться сопоставителями.

Для DRV_QUERYMAPPABLEdwParam1 не используется. Задайте для этого параметра нулевое значение.

Для DRV_QUERYMAPPABLEdwParam2 не используется. Задайте для этого параметра нулевое значение.

Это сообщение допустимо только для функций waveInMessage, waveOutMessage, midiInMessage, midiOutMessage, mixerMessage и auxOutMessage . Система перехватывает это сообщение и возвращает соответствующее значение, не отправляя сообщение драйверу устройства. Общие сведения о функциях xxxMessage , перехваченных системой, см. в разделе Сообщения устройства, перехваченные системой.

Когда приложение открывает средство сопоставления вместо определенного звукового устройства, система вставляет средство сопоставления между приложением и доступными устройствами. Сопоставителя выбирает соответствующее устройство, сопоставляя требования приложения с одним из доступных устройств. Дополнительные сведения о модулях сопоставления см. в документации по Microsoft Windows SDK.

Сообщение DRVM_MAPPER_CONSOLEVOICECOM_GET получает идентификатор предпочтительного устройства голосовой связи.

Для DRVM_MAPPER_CONSOLEVOICECOM_GETdwParam1 является указателем на идентификатор устройства. Этот параметр указывает на переменную DWORD, в которую функция записывает идентификатор текущего предпочтительного устройства голосовой связи. Функция записывает значение (-1), если нет устройства, которое считается предпочтительным устройством голосовой связи.

Для DRVM_MAPPER_CONSOLEVOICECOM_GETdwParam2 является указателем на флаги состояния. Этот параметр указывает на переменную DWORD, в которую функция записывает флаги состояния устройства. В настоящее время определен только один бит флага: DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY.

Это сообщение допустимо только для функций waveInMessage и waveOutMessage . Когда вызывающий объект вызывает эти две функции с сообщением DRVM_MAPPER_CONSOLEVOICECOM_GET, вызывающий объект должен указать идентификатор устройства в качестве WAVE_MAPPER, а затем привести это значение к соответствующему типу дескриптора. Для функций waveInMessage, waveOutMessage, midiInMessage, midiOutMessage или mixerMessage вызывающий объект должен привести идентификатор устройства к дескриптору типа HWAVEIN, HWAVEOUT, HMIDIIN, HMIDIOUT или HMIXER соответственно. Обратите внимание, что если вызывающий объект предоставляет допустимый дескриптор вместо идентификатора устройства для этого параметра, функция завершается ошибкой и возвращает код ошибки MMSYSERR_NOSUPPORT.

Система перехватывает это сообщение и возвращает соответствующее значение, не отправляя сообщение драйверу устройства. Общие сведения о функциях xxxMessage , перехваченных системой, см. в разделе Сообщения устройства, перехваченные системой.

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

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

Если бит флага DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY задан в расположении DWORD, на которое указывает dwParam2, API waveIn и waveOut используют только текущее предпочтительное устройство голосовой связи и не выполняют поиск других доступных устройств, если предпочитаемое устройство недоступно. Флаг, который выводится вызовом waveInMessage или waveOutMessage , применяется к предпочтительному устройству голосовой связи для API waveIn и waveOut , независимо от того, выполняется ли вызов waveInMessage или waveOutMessage. Дополнительные сведения см. в разделе Предпочитаемый идентификатор устройства Voice-Communications.

Сообщение DRVM_MAPPER_PREFERRED_GET получает идентификатор предпочитаемого звукового устройства.

Для DRVM_MAPPER_PREFERRED_GETdwParam1 является указателем на идентификатор устройства. Этот параметр указывает на переменную DWORD, в которую функция записывает идентификатор текущего предпочтительного устройства. Функция записывает значение (-1), если нет устройства, которое считается предпочтительным.

Для DRVM_MAPPER_PREFERRED_GETdwParam2 является указателем на флаги состояния. Этот параметр указывает на переменную DWORD, в которую функция записывает флаги состояния устройства. В настоящее время определен только один бит флага (только для вызовов waveInMessage и waveOutMessage ): DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY.

Это сообщение допустимо только для функций waveInMessage, waveOutMessage и midiOutMessage . Когда вызывающий объект вызывает эти функции с сообщением DRVM_MAPPER_PREFERRED_GET, вызывающий объект должен сначала указать идентификатор устройства как WAVE_MAPPER (для waveInMessage или waveOutMessage) или MIDI_MAPPER (для midiOutMessage), а затем привести это значение к соответствующему типу дескриптора. Для функций waveInMessage, waveOutMessage или midiOutMessage вызывающий объект должен привести идентификатор устройства к типу дескриптора HWAVEIN, HWAVEOUT или HMIDIOUT соответственно. Обратите внимание, что если вызывающий объект предоставляет допустимый дескриптор вместо идентификатора устройства для этого параметра, функция завершается ошибкой и возвращает код ошибки MMSYSERR_NOSUPPORT.

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

Если бит флага DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY задан в расположении DWORD, на которое указывает dwParam2, API waveIn и waveOut используют только текущее предпочтительное устройство и не выполняют поиск других доступных устройств, если предпочитаемое устройство недоступно. Обратите внимание, что функция midiOutMessage не выводит этот флаг . API midiOut всегда использует только предпочтительное устройство. Флаг, который выводится вызовом waveInMessage или waveOutMessage , применяется к предпочтительному устройству для API waveIn и waveOutOut, независимо от того, выполняется ли вызов для waveInMessage или waveOutMessage.

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

Требования

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

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

Звуковой сигнал

Функции волнообразной формы

Поделиться через

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

Синтаксис

Параметры

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

Комментарии

Требования

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

Обратная связь

Дополнительные ресурсы