waveOutOpen 函式 (mmeapi.h)

發行項
03/15/2023

waveOutOpen函式會開啟指定的電壓音訊輸出裝置以供播放。

語法

MMRESULT waveOutOpen(
  LPHWAVEOUT      phwo,
  UINT            uDeviceID,
  LPCWAVEFORMATEX pwfx,
  DWORD_PTR       dwCallback,
  DWORD_PTR       dwInstance,
  DWORD           fdwOpen
);

參數

phwo

緩衝區的指標，這個緩衝區會識別開啟的電壓輸出裝置。呼叫其他電壓音訊輸出函式時，請使用控制碼來識別裝置。如果為fdwOpen指定了 WAVE_FORMAT_QUERY旗標，此參數可能是Null。

uDeviceID

要開啟之電壓音訊輸出裝置的識別碼。它可以是裝置識別碼或開啟的電壓輸入裝置的控制碼。您也可以使用下列旗標，而不是裝置識別碼：

值	意義
WAVE_MAPPER	函式會選取能夠播放指定格式的電壓音訊輸出裝置。

pwfx

針對要傳送至裝置的電壓音訊資料格式，識別要傳送至裝置之波形音訊資料之格式的 WAVEFORMATEX 結構的指標。您可以將它傳遞至 waveOutOpen之後立即釋放此結構。

dwCallback

指定回呼機制。此值必須是下列其中之一：

回呼函式的指標。如需函式簽章，請參閱 waveOutProc。
視窗的控點。
執行緒識別碼。
事件的控制碼。
Null值。

fdwOpen參數會指定如何解譯dwCallback參數。如需詳細資訊，請參閱＜備註＞。

dwInstance

傳遞至回呼機制的使用者實例資料。此參數不會與視窗回呼機制搭配使用。

fdwOpen

用來開啟裝置的旗標。定義下列值。

值	意義
CALLBACK_EVENT	dwCallback參數是事件控制碼。
CALLBACK_FUNCTION	dwCallback參數是回呼程式位址。
CALLBACK_Null	沒有回呼機制。這是預設值。
CALLBACK_THREAD	dwCallback參數是執行緒識別碼。
CALLBACK_WINDOW	dwCallback參數是視窗控制碼。
WAVE_ALLOWSYNC	如果指定此旗標，可以開啟同步的電壓音訊裝置。如果在開啟同步驅動程式時未指定此旗標，裝置將無法開啟。
WAVE_MAPPED_DEFAULT_COMMUNICATION_DEVICE	如果指定此旗標，且 uDeviceID 參數 WAVE_MAPPER，則函式會開啟預設通訊裝置。只有當 uDeviceID 等於 WAVE_MAPPER時，才會套用此旗標。注意需要 Windows 7
WAVE_FORMAT_DIRECT	如果指定此旗標，ACM 驅動程式不會對音訊資料執行轉換。
WAVE_FORMAT_QUERY	如果指定此旗標， waveOutOpen 會查詢裝置，以判斷它是否支援指定的格式，但實際上不會開啟裝置。
WAVE_MAPPED	如果指定此旗標， uDeviceID 參數會指定要由波浪對應器所對應的波浪音訊裝置。

傳回值

如果成功或發生錯誤，則傳回 MMSYSERR_NOERROR 。可能的錯誤值包括下列專案。

傳回碼	描述
MMSYSERR_ALLOCATED	已配置指定的資源。
MMSYSERR_BADDEVICEID	指定的裝置識別碼超出範圍。
MMSYSERR_NODRIVER	沒有設備磁碟機存在。
MMSYSERR_NOMEM	無法配置或鎖定記憶體。
WAVERR_BADFORMAT	嘗試以不支援的電壓音訊格式開啟。
WAVERR_SYNC	裝置是同步的，但未使用WAVE_ALLOWSYNC旗標呼叫waveOutOpen。

備註

使用 waveOutGetNumDevs 函式來判斷系統中存在的電壓音訊輸出裝置數目。如果 uDeviceID 參數指定的值是裝置識別碼，它可能會從零到一個小於存在的裝置數目。 WAVE_MAPPER常數也可以當做裝置識別碼使用。

pwfx所指向的結構可以擴充，以包含特定資料格式的類型特定資訊。例如，針對 PCM 資料，會新增額外的 UINT 來指定每個樣本的位數。在此情況下，請使用 PCMWAVEFORMAT 結構。針對所有其他的電壓音訊格式，請使用「其」結構來指定其他資料的長度。

如果您選擇有視窗或執行緒接收回呼資訊，則會將下列訊息傳送至視窗程式函式，以指出MM_WOM_OPEN、MM_WOM_CLOSE和MM_WOM_DONE的進度。

回呼機制

dwCallback和fdwOpen參數會指定應用程式如何收到有關電壓音訊輸出進度的通知。

如果 fdwOpen 包含 CALLBACK_FUNCTION 旗標， dwCallback 是回呼函式的指標。如需函式簽章，請參閱 waveOutProc。回呼的 uMsg 參數表示音訊輸出的進度：

如果 fdwOpen 包含 CALLBACK_WINDOW 旗標， dwCallback 是視窗的控制碼。視窗會接收下列訊息，指出進度：

如果 fdwOpen 包含 CALLBACK_THREAD 旗標， dwCallback 是執行緒識別碼。執行緒會接收先前針對 CALLBACK_WINDOW列出的訊息。

如果 fdwOpen 包含 CALLBACK_EVENT 旗標， dwCallback 是事件的控制碼。每當電壓緩衝區的狀態變更時，就會發出事件訊號。應用程式可以使用 WaitForSingleObject 或 WaitForMultipleObjects 等候事件。當事件發出訊號時，您可以藉由檢查WAVEHDR結構的dwFlags成員來取得電壓緩衝區的目前狀態。 (請參閱 waveOutPrepareHeader.)

如果 fdwOpen 包含 CALLBACK_Null 旗標， dwCallback 必須是 Null。在此情況下，不會使用回呼機制。

需求


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