Use waveOutOpen to open a waveform output device for playback. This function opens the device associated with the specified device ID and returns a handle to the open device by writing the handle to a specified memory location. The syntax of the waveOutOpen function is as follows:
WORD waveOutOpen(lphWaveOut, wDeviceID, lpFormat, dwCallback, dwInstance, dwFlags)
The lphWaveOut parameter is an LPHWAVEOUT and specifies a far pointer to a memory location the function fills with a handle to the open waveform output device. Use this handle to identify the waveform device when calling other wave-form-output functions.
The wDeviceID parameter is a WORD and identifies the waveform output device to open. See “Getting the Number of Devices,” earlier in this chapter, for details on device IDs. If you specify the WAVE_MAPPER constant, the function finds a waveform output device capable of playing the given format and attempts to open it.
The lpFormat parameter is an LPWAVEFORMAT and specifies a far pointer to a WAVEFORMAT data structure. This data structure contains information on the format of the waveform data that will be sent to the waveform device. The following section explains how to use this data structure. You can free the WAVEFORMAT data structure immediately after passing it to the waveOutOpen function.
The dwCallback parameter is a DWORD and specifies either a window handle or the address of a low-level callback function. The callback can be used to monitor the progress of the playback of waveform data so an application can determine when to send additional data blocks or when to free data blocks that have been sent. You must specify the appropriate flag in the dwFlags parameter to indicate which type of callback you want. If no callback is desired, this parameter is NULL.
The dwInstance parameter is a DWORD and specifies instance data sent to the callback function each time it is called.
The dwFlags parameter is a DWORD and specifies one or more flags for opening a waveform device. Use the WAVE_FORMAT_QUERY flag to specify that you don't want to actually open a device, but just query whether the device supports the specified format. For information on using WAVE_FORMAT_QUERY, see “Determining Non-Standard Format Support,” earlier in this chapter. If you specify a window or low-level callback in the dwCallback parameter, you must specify either the CALLBACK_WINDOW or the CALLBACK_FUNCTION flag to indicate the type of callback you are using.
Some multimedia computers have multiple waveform output devices. Unless you know you want to open a specific waveform output device in a system, you should use the WAVE_MAPPER constant for the device ID when you open a device. The waveOutOpen function chooses the device in the system best capable of playing the given data format.