mixerMessage function (mmeapi.h)

Article
04/02/2021

The mixerMessage function sends a custom mixer driver message directly to a mixer driver.

Syntax

DWORD mixerMessage(
  HMIXER    hmx,
  UINT      uMsg,
  DWORD_PTR dwParam1,
  DWORD_PTR dwParam2
);

Parameters

hmx

Identifier of the mixer that receives the message. You must cast the device ID to the HMIXER handle type. If you supply a handle instead of a device ID, the function fails and returns the MMSYSERR_NOSUPPORT error code.

uMsg

Custom mixer driver message to send to the mixer driver. This message must be above or equal to the MXDM_USER constant.

dwParam1

Parameter associated with the message being sent.

dwParam2

Parameter associated with the message being sent.

Return value

Returns a value that is specific to the custom mixer driver message. Possible error values include the following.

Return code	Description
MMSYSERR_INVALHANDLE	The specified device handle is invalid.
MMSYSERR_INVALPARAM	The uMsg parameter specified in the MXDM_USER message is invalid.
MMSYSERR_NOSUPPORT	The deviceID parameter must be a valid device ID.
MMSYSERR_NOTSUPPORTED	The mixer device did not process the message.

Remarks

User-defined messages must be sent only to a mixer driver that supports the messages. The application should verify that the mixer driver is the driver that supports the message by retrieving the mixer capabilities and checking the wMid, wPid, vDriverVersion, and szPname members of the MIXERCAPS structure.

The DRV_QUERYDEVICEINTERFACE message queries for the device-interface name of a waveIn, waveOut, midiIn, midiOut, or mixer device.

For DRV_QUERYDEVICEINTERFACE, dwParam1 is a pointer to a caller-allocated buffer into which the function writes a null-terminated Unicode string containing the device-interface name. If the device has no device interface, the string length is zero.

For DRV_QUERYDEVICEINTERFACE, dwParam2 specifies the buffer size in bytes. This is an input parameter to the function. The caller should specify a size that is greater than or equal to the buffer size retrieved by the DRV_QUERYDEVICEINTERFACESIZE message.

The DRV_QUERYDEVICEINTERFACE message is supported in Windows Me, and Windows 2000 and later. This message is valid only for the waveInMessage, waveOutMessage, midiInMessage, midiOutMessage, and mixerMessage functions. The system intercepts this message and returns the appropriate value without sending the message to the device driver. For general information about system-intercepted xxxMessage functions, see System-Intercepted Device Messages.

The following two message constants are used together for the purpose of obtaining device interface names:

DRV_QUERYDEVICEINTERFACESIZE
DRV_QUERYDEVICEINTERFACE

The first message obtains the size in bytes of the buffer needed to hold the string containing the device interface name. The second message retrieves the name string in a buffer of the required size.

For more information, see Obtaining a Device Interface Name.

The DRV_QUERYDEVICEINTERFACESIZE message queries for the size of the buffer required to hold the device-interface name.

For DRV_QUERYDEVICEINTERFACESIZE, dwParam1 is a pointer to buffer size. This parameter points to a ULONG variable into which the function writes the required buffer size in bytes. The size includes storage space for the name string's terminating null. The size is zero if the device ID identifies a device that has no device interface.

For DRV_QUERYDEVICEINTERFACESIZE, dwParam2 is unused. Set this parameter to zero.

This message is valid only for the waveInMessage, waveOutMessage, midiInMessage, midiOutMessage, and mixerMessage functions. The system intercepts this message and returns the appropriate value without sending the message to the device driver. For general information about system-intercepted xxxMessage functions, see System-Intercepted Device Messages.

The buffer size retrieved by this message is expressed as a byte count. It specifies the size of the buffer needed to hold the null-terminated Unicode string that contains the device-interface name. The caller allocates a buffer of the specified size and uses the DRV_QUERYDEVICEINTERFACE message to retrieve the device-interface name string.

For more information, see Obtaining a Device Interface Name.

The DRV_QUERYDEVNODE message queries for the devnode number assigned to the device by the Plug and Play manager.

For DRV_QUERYDEVNODE, dwParam1 is a pointer to a caller-allocated DWORD variable into which the function writes the devnode number. If no devnode is assigned to the device, the function sets this variable to zero.

For DRV_QUERYDEVNODE, dwParam2 is unused. Set this parameter to zero.

In Windows 2000 and later, the message always returns MMSYSERR_NOTSUPPORTED. This message is valid only for the waveInMessage, waveOutMessage, midiInMessage, midiOutMessage, and mixerMessage functions. The system intercepts this message and returns the appropriate value without sending the message to the device driver. For general information about system-intercepted xxxMessage functions, see System-Intercepted Device Messages.

The DRV_QUERYMAPPABLE message queries for whether the specified device can be used by a mapper.

For DRV_QUERYMAPPABLE, dwParam1 is unused. Set this parameter to zero.

For DRV_QUERYMAPPABLE, dwParam2 is unused. Set this parameter to zero.

This message is valid only for the waveInMessage, waveOutMessage, midiInMessage, midiOutMessage, mixerMessage and auxOutMessage functions. The system intercepts this message and returns the appropriate value without sending the message to the device driver. For general information about system-intercepted xxxMessage functions, see System-Intercepted Device Messages.

When an application program opens a mapper instead of a specific audio device, the system inserts a mapper between the application and the available devices. The mapper selects an appropriate device by mapping the application's requirements to one of the available devices. For more information about mappers, see the Microsoft Windows SDK documentation.

The DRVM_MAPPER_CONSOLEVOICECOM_GET message retrieves the device ID of the preferred voice-communications device.

For DRVM_MAPPER_CONSOLEVOICECOM_GET, dwParam1 is a pointer to device ID. This parameter points to a DWORD variable into which the function writes the device ID of the current preferred voice-communications device. The function writes the value (-1) if no device is available that qualifies as a preferred voice-communications device.

For DRVM_MAPPER_CONSOLEVOICECOM_GET, dwParam2 is a pointer to status flags. This parameter points to a DWORD variable into which the function writes the device-status flags. Only one flag bit is currently defined: DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY.

This message is valid only for the waveInMessage and waveOutMessage functions. When a caller calls these two functions with the DRVM_MAPPER_CONSOLEVOICECOM_GET message, the caller must specify the device ID as WAVE_MAPPER, and then cast this value to the appropriate handle type. For the waveInMessage, waveOutMessage, midiInMessage, midiOutMessage, or mixerMessage functions, the caller must cast the device ID to a handle of type HWAVEIN, HWAVEOUT, HMIDIIN, HMIDIOUT, or HMIXER, respectively. Note that if the caller supplies a valid handle instead of a device ID for this parameter, the function fails and returns error code MMSYSERR_NOSUPPORT.

The system intercepts this message and returns the appropriate value without sending the message to the device driver. For general information about system-intercepted xxxMessage functions, see System-Intercepted Device Messages.

This message provides a way to determine which device is preferred specifically for voice communications, in contrast to the DRVM_MAPPER_PREFERRED_GET message, which determines which device is preferred for all other audio functions.

For example, the preferred waveOut device for voice communications might be the earpiece in a headset, but the preferred waveOut device for all other audio functions might be a set of stereo speakers.

When the DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY flag bit is set in the DWORD location pointed to by dwParam2, the waveIn and waveOut APIs use only the current preferred voice-communications device and do not search for other available devices if the preferred device is unavailable. The flag that is output by either the waveInMessage or waveOutMessage call applies to the preferred voice-communications device for both the waveIn and waveOut APIs, regardless of whether the call is made to waveInMessage or waveOutMessage. For more information, see Preferred Voice-Communications Device ID.

The DRVM_MAPPER_PREFERRED_GET message retrieves the device ID of the preferred audio device.

For DRVM_MAPPER_PREFERRED_GET, dwParam1 is a pointer to device ID. This parameter points to a DWORD variable into which the function writes the device ID of the current preferred device. The function writes the value (-1) if no device is available that qualifies as a preferred device.

For DRVM_MAPPER_PREFERRED_GET, dwParam2 is a pointer to status flags. This parameter points to a DWORD variable into which the function writes the device-status flags. Only one flag bit is currently defined (for waveInMessage and waveOutMessage calls only): DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY.

This message is valid only for the waveInMessage, waveOutMessage and midiOutMessage functions. When the caller calls these functions with the DRVM_MAPPER_PREFERRED_GET message, the caller must first specify the device ID as WAVE_MAPPER (for waveInMessage or waveOutMessage) or MIDI_MAPPER (for midiOutMessage), and then cast this value to the appropriate handle type. For the waveInMessage, waveOutMessage, or midiOutMessage functions, the caller must cast the device ID to a handle type HWAVEIN, HWAVEOUT or HMIDIOUT, respectively. Note that if the caller supplies a valid handle instead of a device ID for this parameter, the function fails and returns error code MMSYSERR_NOSUPPORT.

This message provides a way to determine which device is preferred for audio functions in general, in contrast to the DRVM_MAPPER_CONSOLEVOICECOM_GET message, which determines which device is preferred specifically for voice communications.

When the DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY flag bit is set in the DWORD location pointed to by dwParam2, the waveIn and waveOut APIs use only the current preferred device and do not search for other available devices if the preferred device is unavailable. Note that the midiOutMessage function does not output this flag--the midiOut API always uses only the preferred device. The flag that is output by either the waveInMessage or waveOutMessage call applies to the preferred device for both the waveIn and waveOut APIs, regardless of whether the call is made to waveInMessage or waveOutMessage.

The xxxMessage functions accept this value in place of a valid device handle in order to allow an application to determine the default device ID without first having to open a device. For more information, see Accessing the Preferred Device ID.

Requirements

Requirement	Value
Minimum supported client	Windows 2000 Professional [desktop apps only]
Minimum supported server	Windows 2000 Server [desktop apps only]
Target Platform	Windows
Header	mmeapi.h (include Windows.h)
Library	Winmm.lib
DLL	Winmm.dll