waveOutOpen(3mms) — Subroutines
Name
waveOutOpen --- Open the specified waveform audio output device for playback
Syntax
#include <mme/mme_api.h>
MMRESULT waveOutOpen(LPHWAVEOUT lphWaveOut,
UINT uDeviceID,
LPWAVEFORMAT lpFormat,
VOID (∗dwCallback) (),
DWORD dwCallbackInstance,
DWORD dwFlags);
Arguments
LPHWAVEOUT lphWaveOut
Specifies a pointer to an HWAVEOUT handle. This location is filled with a handle identifying the waveform audio output device. Use the handle to identify the device when calling other waveform audio output functions. This argument may be NULL if the WAVE_FORMAT_QUERY flag is specified for the dwFlags argument.
UINT uDeviceID
Identifies the waveform audio output device to open. Use a valid waveform audio output device ID (see the Comments section) or the WAVE_MAPPER constant. The WAVE_MAPPER constant causes the system to select the waveform audio output device that is best capable of playing back audio data in the specified format and attempt to open it.
LPWAVEFORMAT lpFormat
Specifies a pointer to a WAVEFORMAT data structure that identifies the format of the waveform audio data to be sent to the waveform audio output device.
Note that for certain format types (as specified by the wFormatTag field) the WAVEFORMAT data structure must be extended. See the Description section of this function for more information.
The WAVEFORMAT data structure must be allocated with the mmeAllocMem function before being passed to the waveOutOpen function.
See the mmeAllocMem(3mms) reference page for more information about allocating memory for data structures.
VOID (∗dwCallback) ()
Specifies the address of a callback function to process messages related to the progress of the audio data playback. Specify NULL for this argument if no callback is desired. This argument may not be NULL unless the WAVE_FORMAT_QUERY flag is specified in the dwFlags argument.
DWORD dwCallbackInstance
Specifies user instance data passed to the callback function.
DWORD dwFlags
Specifies flags for opening the waveform audio output device. The following flags are defined:
CALLBACK_FUNCTION
If this flag is specified, the dwCallback argument is assumed to be a callback procedure address.
WAVE_ALLOWSYNC
If this flag is not specified, the device fails to open if it is synchronous.
WAVE_FORMAT_QUERY
If this flag is specified, the device is queried to determine if it supports the given format but is not actually opened.
WAVE_OPEN_SHAREABLE
If this flag is specified, the device is opened as a shareable device.
Description
The waveOutOpen function opens the specified waveform audio output device for playback. Use the waveOutGetNumDevs function to determine the number of waveform output devices present in the system. The device ID specified by the uDeviceId argument varies from zero to one fewer than the number of devices present. The WAVE_MAPPER constant may also be used as a device ID.
Depending upon the specific waveform format (as specified by the wFormatTag field) being specified with the lpFormat argument, it may be required to extend the WAVEFORMAT data structure referenced by the lpFormat argument. For example, for pulse code modulation (PCM) data, an extra word is added to specify the number of bits per sample. Use the PCMWAVEFORMAT data structure in this case.
Multimedia Services for DEC OSF/1 AXP does not support the use of a callback window. Only callback functions are supported. If an application specifies a callback window, the MMSYSERR_INVALPARAM error code is returned to the calling application.
Callback
void CALLBACK waveOutCallbackFunction(HWAVEOUT hWaveOut,
UINT uMsg,
DWORD dwInstance,
LPARAM lParam1,
LPARAM lParam2);
The waveOutCallbackFunction function name is a placeholder for the callback function name supplied by the application. If a waveOutOpen function is chosen to receive callback information, the messages listed under the uMsg argument are sent to the function to indicate the progress of waveform audio output.
Callback Arguments
HWAVEOUT hWaveOut
Specifies a handle to a waveform audio output device associated with the callback function.
UINT uMsg
Specifies a waveform audio output message. The following messages are defined:
WOM_CLOSE
Sent when the device is closed using the waveOutClose function.
WOM_OPEN
Sent when the device is opened using the waveOutOpen function.
WOM_DONE
Sent when the device driver is finished processing a data block that was sent using the waveOutWrite function.
DWORD dwInstance
Specifies the user instance data specified as dwCallbackInstance with the waveOutOpen function call.
LPARAM lParam1
Specifies an argument for the message. For the WOM_OPEN and WOM_CLOSE messages, this argument is not used.
For the WOM_DONE message, this argument specifies a pointer to a WAVEHDR data structure identifying the completed data block. The WAVEHDR data structure address is only valid while the callback function is executing; the address of the WAVEHDR data structure will not be the same as the address of the WAVEHDR data structure passed into the waveOutWrite function. The contents of the WAVEHDR data structure will be modified to reflect the result of the operation.
The WAVEHDR data structure is the same as the one passed into the waveOutWrite function.
LPARAM lParam2
Specifies an argument for the message. This argument is not used.
After the driver is finished processing a data block, clean up and free the data block. See the mmeFreeMem(3mms) and mmeFreeBuffer(3mms) reference pages for more information about freeing data structures and data blocks.
This work must be done outside the callback function. The Multimedia Services for DEC OSF/1 AXP API functions cannot be called from a callback function.
Extensions
The WAVE_OPEN_SHAREABLE flag, which allows a waveform audio output device to be opened as a shareable device, and the WAVERR_DEVICENOTSHAREABLE and WAVERR_DEVICESHAREABLE error codes are Digital extensions to the API specification
Return Values
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
MMSYSERR_ALLOCATED@T{ The specified resource is already allocated. T} MMSYSERR_INVALHANDLE@T{ The specified device handle is invalid or the system has no more device handles. T} MMSYSERR_NOMEM@T{ Unable to allocate or lock memory. T} WAVERR_BADFORMAT@T{ Attempted to open with an unsupported wave format. T} WAVERR_DEVICENOTSHAREABLE@T{ The specified device is already opened as an exclusive device. T} WAVERR_DEVICESHAREABLE@T{ The specified device is already opened as a shareable device. T}