This function opens a specified waveform output device for playback.
At a Glance
| Header file: | Mmsystem.h |
| Windows CE versions: | 2.0 and later |
Syntax
MMRESULT waveOutOpen(LPHWAVEOUT phwo, UINT uDeviceID, LPWAVEFORMATEX pwfx, DWORD dwCallback, DWORD dwInstance, DWORD fdwOpen);
Parameters
phwo
Address filled with 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.
uDeviceID
Identifier of the waveform-audio output device to open. It can be either a device identifier or a Handle to an open waveform-audio input device. You can use the following flag instead of a device identifier:
| Value | Description |
| WAVE_MAPPER | The function selects a waveform-audio output device capable of playing the specified format. |
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.
dwCallback
Specifies the address of a fixed callback function, an event handle, a handle to a window, or the identifier of a thread to be called during waveform-audio playback to process messages related to the progress of the playback. If no callback function is required, this value can be zero.
dwInstance
Specifies 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:
| Value | Description |
| 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_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 specified 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. |
Return Values
One of the values described in the following table is returned.
| Value | Description |
| MMSYSERR_NOERROR | Success. |
| MMSYSERR_INVALHANDLE | Specified device handle is invalid. |
| MMSYSERR_BADDEVICEID | Specified device identifier is out of range. |
| MMSYSERR_NODRIVER | No device driver is present. |
| MMSYSERR_NOMEM | Unable to allocate or lock memory. |
| WAVERR_BADFORMAT | Attempted to open with an unsupported waveform-audio format. |
| WAVERR_SYNC | Device is synchronous but waveOutOpen was called without using the WAVE_ALLOWSYNC flag. |
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.
The structure pointed to by pwfx can be extended to include type-specific information for certain data formats by using the WAVEFORMATEX structure to specify the length of the additional data.
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.
If you choose to have a function receive callback information, the following messages are sent to the function to indicate the progress of waveform-audio output: WOM_OPEN, WOM_CLOSE, and WOM_DONE.