waveOutOpen 函数 (mmeapi.h)

项目
08/24/2023

waveOutOpen 函数打开给定的波形音频输出设备进行播放。

语法

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

parameters

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	设备是同步的，但调用 waveOutOpen 时未使用 WAVE_ALLOWSYNC 标志。

注解

使用 waveOutGetNumDevs 函数确定系统中存在的波形音频输出设备的数量。如果 uDeviceID 参数指定的值是设备标识符，则该值可能从零变化到 1 个，而不是存在的设备数。 WAVE_MAPPER常量也可用作设备标识符。

pwfx 指向的结构可以扩展为包含特定数据格式的类型特定信息。例如，对于 PCM 数据，将添加额外的 UINT 来指定每个样本的位数。在这种情况下，请使用 PCMWAVEFORMAT 结构。对于所有其他波形音频格式，请使用 WAVEFORMATEX 结构指定附加数据的长度。

如果选择窗口或线程接收回调信息，则会将以下消息发送到窗口过程函数，以指示波形音频输出的进度： 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 或 WaitForMultipleObject 来等待事件。发出事件信号后，可以通过检查 WAVEHDR 结构的 dwFlags 成员来获取波形缓冲区的当前状态。 (请参阅 waveOutPrepareHeader.)

如果 fdwOpen 包含 CALLBACK_NULL 标志， 则 dwCallback 必须为 NULL。在这种情况下，不使用任何回调机制。

要求


最低受支持的客户端	Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器	Windows 2000 Server [仅限桌面应用]
目标平台	Windows
标头	mmeapi.h (包括 Windows.h)
Library	Winmm.lib
DLL	Winmm.dll