本篇翻译自以下地址:
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。这种情况下,没有使用回调机制。