midiInMessage 函式 (mmeapi.h)

  • 發行項

midiInMessage 函式會將訊息傳送至MIDI裝置驅動程式。

語法

MMRESULT midiInMessage(
  HMIDIIN   hmi,
  UINT      uMsg,
  DWORD_PTR dw1,
  DWORD_PTR dw2
);

參數

hmi

接收訊息之MIDI裝置的標識碼。 您必須將裝置識別碼轉換成 HMIDIIN 句柄類型。 如果您提供句柄而非裝置標識碼，函式會失敗並傳回MMSYSERR_NOSUPPORT錯誤碼。

uMsg

要傳送的訊息。

dw1

訊息參數。

dw2

訊息參數。

傳回值

傳回音訊設備驅動器所傳回的值。

備註

此函式僅用於 MIDI API 不支援的驅動程式特定訊息。

訊息會DRV_QUERYDEVICEINTERFACE查詢 waveIn、waveOut、midiIn、midiOut 或混合器裝置的裝置介面名稱。

針對 DRV_QUERYDEVICEINTERFACE， dwParam1 是呼叫端配置的緩衝區指標，函式會寫入包含裝置介面名稱的 Null 終止 Unicode 字串。 如果裝置沒有裝置介面，則字串長度為零。

針對 DRV_QUERYDEVICEINTERFACE， dwParam2 會以位元組為單位指定緩衝區大小。 這是函式的輸入參數。 呼叫端應該指定大於或等於 DRV_QUERYDEVICEINTERFACESIZE 訊息所擷取的緩衝區大小。

Windows Me 和 Windows 2000 和更新版本支援DRV_QUERYDEVICEINTERFACE訊息。 此訊息僅適用於 waveInMessage、waveOutMessage、midiInMessage、midiOutMessage 和混合器Message 函式。 系統會攔截此訊息，並傳回適當的值，而不會將訊息傳送至設備驅動器。 如需系統攔截 xxxMessage 函式的一般資訊，請參閱 系統攔截的裝置訊息。

下列兩個訊息常數會一起使用，以取得裝置介面名稱：

  • DRV_QUERYDEVICEINTERFACESIZE
  • DRV_QUERYDEVICEINTERFACE
第一則訊息會取得包含裝置介面名稱之字串所需的緩衝區位元組大小。 第二則訊息會擷取所需大小的緩衝區中的名稱字串。

如需詳細資訊，請參閱 取得裝置介面名稱。

訊息 DRV_QUERYDEVICEINTERFACESIZE 會查詢保存裝置介面名稱所需的緩衝區大小。

針對 DRV_QUERYDEVICEINTERFACESIZE， dwParam1 是緩衝區大小的指標。 此參數指向 ULONG 變數，函式會以位元組為單位寫入所需的緩衝區大小。 此大小包含名稱字串終止 Null 的儲存空間。 如果裝置標識碼識別沒有裝置介面的裝置，則大小為零。

針對 DRV_QUERYDEVICEINTERFACESIZE， 未使用 dwParam2 。 將此參數設定為零。

此訊息僅適用於 waveInMessage、waveOutMessage、midiInMessage、midiOutMessage 和混合器Message 函式。 系統會攔截此訊息，並傳回適當的值，而不會將訊息傳送至設備驅動器。 如需系統攔截 xxxMessage 函式的一般資訊，請參閱 系統攔截的裝置訊息。

此訊息所擷取的緩衝區大小會以位元組計數表示。 它會指定包含裝置介面名稱之 Null 終止 Unicode 字串所需的緩衝區大小。 呼叫端會配置指定大小的緩衝區，並使用 DRV_QUERYDEVICEINTERFACE 訊息來擷取裝置介面名稱字串。

如需詳細資訊，請參閱 取得裝置介面名稱。

訊息會DRV_QUERYDEVNODE查詢由 隨插即用 管理員指派給裝置的 devnode 號碼。

針對 DRV_QUERYDEVNODE， dwParam1 是呼叫端配置的 DWORD 變數指標，函式會將 devnode 編號寫入其中。 如果未將 devnode 指派給裝置，函式會將此變數設定為零。

針對 DRV_QUERYDEVNODE， 未使用 dwParam2 。 將此參數設定為零。

在 Windows 2000 和更新版本中，訊息一律會傳回MMSYSERR_NOTSUPPORTED。 此訊息僅適用於 waveInMessage、waveOutMessage、midiInMessage、midiOutMessage 和混合器Message 函式。 系統會攔截此訊息，並傳回適當的值，而不會將訊息傳送至設備驅動器。 如需系統攔截 xxxMessage 函式的一般資訊，請參閱 系統攔截的裝置訊息。

訊息 DRV_QUERYMAPPABLE 會查詢對應器是否可以使用指定的裝置。

針對 DRV_QUERYMAPPABLE， 未使用 dwParam1 。 將此參數設定為零。

針對 DRV_QUERYMAPPABLE， 未使用 dwParam2 。 將此參數設定為零。

此訊息僅適用於 waveInMessage、waveOutMessage、midiInMessage、midiOutMessage、mixerMessage 和 auxOutMessage 函式。 系統會攔截此訊息，並傳回適當的值，而不會將訊息傳送至設備驅動器。 如需系統攔截 xxxMessage 函式的一般資訊，請參閱 系統攔截的裝置訊息。

當應用程式程序開啟 mapper 而非特定音訊裝置時，系統會在應用程式和可用的裝置之間插入對應器。 對應器會藉由將應用程式的需求對應至其中一個可用的裝置，以選取適當的裝置。 如需對應器的詳細資訊，請參閱 Microsoft Windows SDK 檔。

訊息 DRVM_MAPPER_CONSOLEVOICECOM_GET 會擷取慣用語音通訊裝置的裝置標識碼。

針對 DRVM_MAPPER_CONSOLEVOICECOM_GET， dwParam1 是裝置標識碼的指標。 此參數指向 DWORD 變數，函式會將目前慣用語音通訊裝置的裝置識別碼寫入其中。 如果沒有任何裝置可限定為慣用語音通訊裝置，函式會寫入值 (-1) 。

針對 DRVM_MAPPER_CONSOLEVOICECOM_GET， dwParam2 是狀態旗標的指標。 此參數指向函式寫入裝置狀態旗標的 DWORD 變數。 目前只有一個旗標位已定義：DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY。

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

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

此訊息提供一種方式來判斷哪個裝置特別適合用於語音通訊，相對於 DRVM_MAPPER_PREFERRED_GET 訊息，這會決定所有其他音訊功能偏好哪一個裝置。

例如，語音通訊的慣用 waveOut 裝置可能是頭戴式裝置中的耳機，但所有其他音訊功能的慣用 waveOut 裝置可能是一組立體喇叭。

當 dwParam2 指向的 DWORD 位置中設定DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY旗標位時， waveIn 和 waveOut API 只會使用目前的慣用語音通訊裝置，而且如果慣用的裝置無法使用，則不會搜尋其他可用的裝置。 waveInMessage 或 waveOutMessage 呼叫所輸出的旗標會同時套用至 waveIn 和 waveOut API 的慣用語音通訊裝置，不論呼叫是否為 waveInMessage 或 waveOutMessage。 如需詳細資訊，請參閱 慣用 Voice-Communications 裝置標識符。

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

針對 DRVM_MAPPER_PREFERRED_GET， dwParam1 是裝置標識碼的指標。 此參數指向函式寫入目前慣用裝置的裝置識別碼的 DWORD 變數。 如果沒有任何裝置可限定為慣用裝置，函式會寫入值 (-1) 。

針對 DRVM_MAPPER_PREFERRED_GET， dwParam2 是狀態旗標的指標。 此參數指向函式寫入裝置狀態旗標的 DWORD 變數。 waveInMessage 和 waveOutMessage) 呼叫目前只有一個旗標位定義 (：DRVM_MAPPER_PREFERRED_FLAGS_PREFERREDONLY。

此訊息僅適用於 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。

xxx訊息函式會接受此值來取代有效的裝置句柄，以便讓應用程式判斷預設裝置識別碼，而不需要先開啟裝置。 如需詳細資訊，請參閱 存取慣用裝置標識符。

規格需求

需求 值
最低支援的用戶端 Windows 2000 Professional [僅限傳統型應用程式]
最低支援的伺服器 Windows 2000 Server [僅限桌面應用程式]
目標平台 Windows
標頭 mmeapi.h (包含 Windows.h)
程式庫 Winmm.lib
Dll Winmm.dll

另請參閱

MIDI 函式