DRVM_MAPPER_PREFERRED_GET 函式

發行項
02/03/2024

DRVM_MAPPER_PREFERRED_GET訊息會擷取慣用音訊裝置的裝置標識碼。

語法

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

參數

uDeviceID
指定目標裝置的識別碼。如需如何轉換此值以搭配適當函式使用的詳細資訊，請參閱下列一節。
uMsg
呼叫者會在呼叫 xxxMessage 來處理此裝置訊息時，將此參數設定為 DRVM_MAPPER_PREFERRED_GET。
dwParam1
裝置標識碼的指標。此參數指向 DWORD 變數，函式會將目前慣用裝置的裝置識別碼寫入其中。函式會將值寫入 (-1) ，如果沒有符合慣用裝置資格的裝置。
dwParam2
狀態旗標的指標。此參數指向函式寫入裝置狀態旗標的 DWORD 變數。目前只有一個旗標位是針對 waveInMessage 和 waveOutMessage 呼叫定義 () ：DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY。如需詳細資訊，請參閱接下來的＜備註＞一節。

傳回值

如果已成功處理訊息， 則 xxxMessage 函式會傳回MMSYSERR_NOERROR。否則，它會傳回適當的錯誤碼。

備註

此訊息僅適用於 waveInMessage、 waveOutMessage 和 midiOutMessage 函式。當呼叫端使用DRVM_MAPPER_PREFERRED_GET訊息呼叫這些函式時，呼叫端必須先將裝置標識元指定為 waveInMessage 或 waveOutMessage) WAVE_MAPPER (或 midiOutMessage) MIDI_MAPPER (，然後將此值轉換成適當的句柄類型。針對 waveInMessage、 waveOutMessage 或 midiOutMessage 函式，呼叫端必須將裝置標識符分別轉換成句柄類型 HWAVEIN、HWAVEOUT 或 HMIDIOUT。請注意，如果呼叫端提供有效的句柄，而不是此參數的裝置標識碼，函式會失敗並傳回錯誤碼MMSYSERR_NOSUPPORT。

系統會攔截此訊息，並傳回適當的值，而不會將訊息傳送至設備驅動器。如需系統攔截 xxxMessage 函式的一般資訊，請參閱系統攔截的裝置訊息。

相較於 DRVM_MAPPER_CONSOLEVOICECOM_GET 訊息，此訊息提供一種方式來判斷一般音訊功能偏好哪一個裝置，這可決定哪些裝置特別適合用於語音通訊。

當 DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY 旗標位設定在 dwParam2 指向的 DWORD 位置時， waveIn 和 waveOut API 只會使用目前的慣用裝置，而且如果慣用裝置無法使用，則不會搜尋其他可用的裝置。請注意， midiOutMessage 函式不會輸出此旗標-- midiOut API 一律只會使用慣用的裝置。 waveInMessage 或 waveOutMessage 呼叫所輸出的旗標適用於 waveIn 和 waveOut API 的慣用裝置，不論呼叫 waveInMessage 還是 waveOutMessage。