DRVM_MAPPER_PREFERRED_GET 函数

项目
03/11/2024

DRVM_MAPPER_PREFERRED_GET 消息会检索首选音频设备的设备 ID。

语法

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

参数

uDeviceID
指定目标设备的 ID。有关如何强制转换此值以用于相应函数的详细信息，请参阅下面的备注部分。
uMsg
调用方在调用 xxxMessage 以处理此设备消息时，将此参数设置为 DRVM_MAPPER_PREFERRED_GET。
dwParam1
指向设备 ID 的指针。此参数指向一个 DWORD 变量，该函数会将当前首选设备的设备 ID 写入该变量中。如果没有任何设备符合首选设备的资格，该函数将写入值 (-1)。
dwParam2
指向状态标志的指针。此参数指向一个 DWORD 变量，该函数会向此变量中写入设备状态标志。目前仅定义了一个标志位（仅针对 waveInMessage 和 waveOutMessage 调用）：DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY。有关更多信息，请参见下面的“备注”部分。

返回值

如果已成功处理消息，则 xxxMessage 函数将返回 MMSYSERR_NOERROR。否则，将返回相应的错误代码。

注解

此消息仅适用于 waveInMessage、waveOutMessage 和 midiOutMessage 函数。当调用方使用 DRVM_MAPPER_PREFERRED_GET 消息调用这些函数时，调用方必须先将设备 ID 指定为 WAVE_MAPPER（对于 waveInMessage 或 waveOutMessage）或 MIDI_MAPPER（对于 midiOutMessage），然后将此值强制转换为适当的句柄类型。对于 waveInMessage、waveOutMessage 或 midiOutMessage 函数，调用方必须将设备 ID 分别转换为句柄类型 HWAVEIN、HWAVEOUT 或 HMIDIOUT。请注意，如果调用方提供有效的句柄而不是此参数的设备 ID，函数将失败并返回错误代码 MMSYSERR_NOSUPPORT。

系统会截获此消息并返回相应的值，而不将此消息发送到设备驱动程序。有关系统截获的 xxxMessage 函数的一般信息，请参阅系统截获的设备消息。

此消息提供了一种方法，用于确定哪个设备是常规音频函数的首选设备，这与 DRVM_MAPPER_CONSOLEVOICECOM_GET 消息形成对比，后者用于确定哪个设备特定于语音通信的设备。

在 dwParam2 指向的 DWORD 位置中设置 DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY 标志位时，waveIn 和 waveOut API 仅使用当前的首选设备，如果首选设备不可用，则不会搜索其他可用设备。请注意，midiOutMessage 函数不会输出此标志--midiOut API 始终仅使用首选设备。 waveInMessage 或 waveOutMessage 调用输出的标志适用于 waveIn 和 waveOut API 的首选设备，无论该调用是针对 waveInMessage 还是 waveOutMessage。