本篇翻譯自以下地址:
https://docs.microsoft.com/zh-cn/windows/win32/api/mmeapi/nf-mmeapi-waveoutopen
爲了便於大家批評指正,原文大部分並未刪除。爲了簡單理解,有些複雜的描述,並未翻譯,大部分情況下不影響使用。方框內的內容爲本人額外的補充說明。
The waveOutOpen function opens the given waveform-audio output device for playback.
waveOutOpen函數用來在播放時,打開給定的波形音頻輸出設備。
waveform-audio是一組函數以及相關的數據結構,聲音設備使用wavefor-audio來進行管理的一種虛擬設備,稱之爲waveform audio device(波形音頻設備)。波形音頻設備有兩種,waveform audio output device(輸出設備,播放)和waveform audioi input device(輸入設備,錄音)。
語法
語法(C++)
MMRESULT waveOutOpen(
LPHWAVEOUT phwo,
UINT uDeviceID,
LPCWAVEFORMATEX pwfx,
DWORD_PTR dwCallback,
DWORD_PTR dwInstance,
DWORD fdwOpen
);
參數
參數 | 說明 |
---|---|
howo | Pointer to a buffer that receives a handle identifying the open waveform-audio output device. Use the handle to identify the device when calling other waveform-audio output functions. This parameter might be NULL if the WAVE_FORMAT_QUERY flag is specified for fdwOpen. 指向一個緩衝,接收表示要打開的波形音頻設備的句柄。1 |
uDeviceID | Identifier of the waveform-audio output device to open. It can be either a device identifier or a handle of an open waveform-audio input device. You can also use the following flag instead of a device identifier: 設備ID參數用來表示要打開的波形音頻輸出設備,也可以是波形音頻輸入設備的設備標識符或者句柄。2 |
pwfx | Pointer to a WAVEFORMATEX structure that identifies the format of the waveform-audio data to be sent to the device. You can free this structure immediately after passing it to waveOutOpen. 指向WAVEFORMATEX結構,表示要發送到設備波形音頻數據的格式。 |
dwCallback | Specifies the callback mechanism. The value must be one of the following: 定義回調機制,取值如下:
|
取值代表的作用如下。
- 回調函數,數據塊播放完成時會調用一個函數
- 窗口句柄,數據塊播放完成時會發送一個窗口消息
- 線程標識符,數據塊播放完成時會發送一個線程消息
- 事件句柄,數據塊播放完成的時候會觸發一個事件
The fdwOpen parameter specifies how the dwCallback parameter is interpreted. For more information, see Remarks.
dwCallback參數到底如何解釋由最後一個參數fdwOpen指定。
參數 | 說明 |
---|---|
dwInstance | User-instance data passed to the callback mechanism. This parameter is not used with the window callback mechanism. 傳遞到回調機制的用戶實例數據,對窗口回調機制模式,本參數無效。 |
fdwOpen | Flags for opening the device. The following values are defined. 打開設備的方式,取值如下。 |
fdwOpen取值表
取值 | 含義 |
---|---|
CALLBACK_EVENT | The dwCallback parameter is an event handle. |
CALLBACK_FUNCTION | The dwCallback parameter is a callback procedure address. |
CALLBACK_NULL | No callback mechanism. This is the default setting. |
CALLBACK_THREAD | The dwCallback parameter is a thread identifier. |
CALLBACK_WINDOW | The dwCallback parameter is a window handle. |
WAVE_ALLOWSYNC | If this flag is specified, a synchronous waveform-audio device can be opened. If this flag is not specified while opening a synchronous driver, the device will fail to open. |
WAVE_MAPPED_DEFAULT_COMMUNICATION_DEVICE | If this flag is specified and the uDeviceID parameter is WAVE_MAPPER |
WAVE_FORMAT_DIRECT | If this flag is specified, the ACM driver does not perform conversions on the audio data. |
WAVE_FORMAT_QUERY | If this flag is specified, waveOutOpen queries the device to determine if it supports the given format, but the device is not actually opened. |
WAVE_MAPPED | If this flag is specified, the uDeviceID parameter specifies a waveform-audio device to be mapped to by the wave mapper. |
返回值的說明暫時略過,需要了解的讀者可以看其他資料,主要的幾個用法見下面的說明。
說明
Remarks
Use the waveOutGetNumDevs function to determine the number of waveform-audio output devices present in the system. If the value specified by the uDeviceID parameter is a device identifier, it can vary from zero to one less than the number of devices present. The WAVE_MAPPER constant can also be used as a device identifier.
說明:
使用waveOutGetNumDevs
函數可以確定波形音頻輸出設備的數量。如果用這個設備標識符值作爲uDeviceID
參數,值從0~小於設備數量的值。
If you choose to have a window or thread receive callback information, the following messages are sent to the window procedure function to indicate the progress of waveform-audio output: MM_WOM_OPEN, MM_WOM_CLOSE, and MM_WOM_DONE.
如果選擇窗體或者線程方式來接收回調信息,系統會想窗口過程函數發送下面的信息,以表示波形輸出設備的工作過程:MM_WOM_OPEN, MM_WOM_CLOSE, and MM_WOM_DONE.
回調機制
Callback Mechanism
The dwCallback and fdwOpen parameters specify how the application is notified about the progress of waveform-audio output.
dwCallback
和fdwOpen
參數規定了程序是如何通知波形音頻輸出的工作過程。
情況1
If fdwOpen contains the CALLBACK_FUNCTION flag, dwCallback is a pointer to a callback function. For the function signature, see waveOutProc. The uMsg parameter of the callback indicates the progress of the audio output:
WOM_OPEN
WOM_CLOSE
WOM_DONE
如果fdwOpen
包含CALLBACK_FUNCTION 標誌,dwCallback
指向回調函數,函數的定義參見waveOutProc
。那麼回調中的uMsg參數表示了音頻輸出過程:
- WOM_OPEN
- WOM_CLOSE
- WOM_DONE
情況2
If fdwOpen contains the CALLBACK_WINDOW flag, dwCallback is a handle to a window.The window receives the following messages, indicating the progress:
MM_WOM_OPEN
MM_WOM_CLOSE
MM_WOM_DONE
如果fdwOpen
包含CALLBACK_WINDOW
標誌,dwCallback
是一個窗口句柄。窗口收到下面的消息,表示音頻輸出過程。
- MM_WOM_OPEN
- MM_WOM_CLOSE
- MM_WOM_DONE
情況3
If fdwOpen contains the CALLBACK_THREAD flag, dwCallback is a thread identifier. The thread receives the messages listed previously for CALLBACK_WINDOW.
如果fdwOpen
包含CALLBACK_THREAD
標誌,dwCallback
是一個線程標識符。線程接收到的消息和CALLBACK_WINDOW
方式收到的消息相同。
情況4
If fdwOpen contains the CALLBACK_EVENT flag, dwCallback is a handle to an event. The event is signaled whenever the state of the waveform buffer changes. The application can use WaitForSingleObject or WaitForMultipleObjects to wait for the event. When the event is signaled, you can get the current state of the waveform buffer by checking the dwFlags member of the WAVEHDR structure. (See waveOutPrepareHeader.)
如果fdwOpen
包含CALLBACK_EVENT
標誌,dwCallback
是一個事件句柄。當波形緩衝的狀態發生改變,事件觸發,程序可以使用WaitForSingleObject
或WaitForMultipleObjects
來等待事件,當事件有信號,你可以獲得波形緩衝的當前狀態,查詢WAVEHDR
結構的dwFlags
參數即可。
情況5
If fdwOpen contains the CALLBACK_NULL flag, dwCallback must be NULL. In that case, no callback mechanism is used.
如果fdwOpen
包含CALLBACK_NULL
標誌,dwCallback
必須爲NULL。這種情況下,沒有使用回調機制。