DRVM_MAPPER_CONSOLEVOICECOM_GET function

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

Syntax

DWORD  xxxMessage(
   UINT      uDeviceID,
   UINT      uMsg,
   DWORD_PTR dwParam1,
   DWORD_PTR dwParam2
);

Parameters

• uDeviceID
  Specifies the ID of the target device. See the following Remarks section for more information about how to cast this value for use with the appropriate function.

• uMsg
  Caller sets this parameter to DRVM_MAPPER_CONSOLEVOICECOM_GET when it calls xxxMessage to process this device message.

• dwParam1
  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.

• dwParam2
  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. For more information, see the following Remarks section.

Return value

The xxxMessage function returns MMSYSERR_NOERROR if the message is handled successfully. Otherwise, it returns an appropriate error code.

Remarks

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.

Requirements

See also

DRVM_MAPPER_PREFERRED_GET

midiInMessage

midiOutMessage

mixerMessage

Preferred Voice-Communications Device ID

System-Intercepted Device Messages

waveInMessage

waveOutMessage