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

Статья
08/24/2023

Функция midiOutMessage отправляет сообщение драйверам устройств MIDI. Эта функция используется только для сообщений, относящихся к драйверу, которые не поддерживаются API MIDI.

Синтаксис

MMRESULT midiOutMessage(
  HMIDIOUT  hmo,
  UINT      uMsg,
  DWORD_PTR dw1,
  DWORD_PTR dw2
);

Параметры

hmo

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

uMsg

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

dw1

Параметр message.

dw2

Параметр message.

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

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

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

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

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

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

DRV_QUERYDEVICEINTERFACESIZE
DRV_QUERYDEVICEINTERFACE

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Когда программа приложения открывает средство сопоставления вместо определенного звукового устройства, система вставляет средство сопоставления между приложением и доступными устройствами. Сопоставителя выбирает соответствующее устройство, сопоставляя требования приложения с одним из доступных устройств. Дополнительные сведения о модулях сопоставления см. в документации по 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 , перехваченных системой, см. в разделе System-Intercepted Device Messages.

Это сообщение позволяет определить, какое устройство предпочтительнее для голосовой связи, в отличие от 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 и waveOut , независимо от того, выполняется ли вызов waveInMessage или waveOutMessage.

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

Требования

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

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

Функции MIDI

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

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

Синтаксис

Параметры

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

Комментарии

Требования

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

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

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