#include <mme/mme_api.h> MMRESULT waveOutGetFormatInfo (UINT uClassDeviceID, LPWAVEFORMATINFO lpWaveformatInfo);

Arguments UINT uClassDeviceID
Identifies the waveform audio output device.

LPWAVEFORMATINFO lpWaveformatInfo
Specifies a pointer to a WAVEFORMATINFO data structure. The waveOutGetFormatInfo function returns high-level information common to all formats supported by the device in this data structure.

The WAVEFORMATINFO data structure must be allocated with the mmeAllocMem function before being passed to the waveOutGetFormatInfo function. See Chapter 2 for more information about the memory allocation functions.

Description

The waveOutGetFormatInfo function queries the specified waveform audio input device to determine its capabilities. Information is returned relating to all formats supported by the device, not just standard formats. (See the dwFormats description in Section 3.6.6 for a list of standard formats.) The information returned includes the number of formats supported, the maximum size of a WAVEFORMATEX data structure needed to describe any supported format, and the maximum size of an ASCII string needed to provide a text description of any supported format.

The device ID specified by the uClassDeviceID argument varies from zero to one less than the number of audio devices present.

Return Values

Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:

#include <mme/mme_api.h> MMRESULT waveOutGetID(HWAVEOUT hWaveOut, PUINT lpuDeviceID);

Arguments HWAVEOUT hWaveOut
Specifies a handle to a waveform audio output device.

PUINT lpuDeviceID
Specifies a pointer to the UINT-sized memory location to be filled with the device ID.

Description

The waveOutGetID function gets the device ID for the specified waveform audio output device.

Return Values

Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:

#include <mme/mme_api.h> UINT waveOutGetNumDevs()

Arguments None.

Description

The waveOutGetNumDevs function retrieves the number of waveform audio output devices present in the system.

Return Values

Returns the number of waveform output devices present in the system.

#include <mme/mme_api.h> MMRESULT waveOutGetPorts(UINT uClassDeviceID, LPDWORD lpdwPortMask, PUINT lpuNumPorts, LPSTR lpText, UINT uSize);

Arguments UINT uClassDeviceID
Identifies the waveform audio output device.

LPDWORD lpdwPortMask
Specifies a memory location in which the current port selection mask is returned. If this parameter is non-NULL, the memory location must be allocated by the mmeAllocMem function. If this parameter is NULL, this value is not returned.

PUINT lpuNumPorts
Specifies a memory location in which the number of ports for this device are returned. If this parameter is non-NULL, the memory location must be allocated by the mmeAllocMem function. If this parameter is NULL, this value is not returned.

LPSTR lpText
Specifies a memory location in which the text descriptions of the ports for this device are returned. If this parameter is non-NULL, the memory location must be allocated by the mmeAllocMem function.

UINT uSize
Specifies the size of the memory area pointed to by the lpText parameter. If lpText is non-NULL, to prevent possible truncation, the uSize parameter must be large enough to accommodate up to MME_MAXWAVEPORTS*MME_MAXWAVEPORTDESCLEN characters.

Description

The waveOutGetPorts function queries the current port selection mask and maximum number of ports supported for the specified waveform audio output device. Not all audio devices support a port selection capability. The port selection capability provides the ability to enable output to one or more of the available ports (connections) for a device.

The waveOutGetPorts function also returns text descriptions of all ports supported for the specified waveform audio output device. Each description is a null-terminated text string that describes the port.

The *lpdwPortMask value is a bit mask; each bit set defines whether the corresponding port is currently selected. Mask values MME_PORTMASK_01 through MME_PORTMASK_32 are defined for use in analyzing the port mask value.

The *lpuNumPorts value identifies the maximum number of ports supported on the specified device.

The lpText value contains up to MME_MAXWAVEPORTS null-terminated strings, each of maximum length MME_MAXWAVEPORTDESCLEN. These strings are stored in double subscripted array format: CHAR lpText[MME_MAXWAVEPORTS][MME_MAXWAVEPORTDESCLEN]. If the uSize value is not large enough to store all strings, then the last string stored is truncated (and null-terminated) but the function still returns MMSYSERR_NOERROR. If the value of uSize is positive but the value of lpText is NULL, then the function returns MMSYSERR_INVALPARAM.

Note that if the device provides only one output port, or if it provides no selection capability among ports, then it may return MMSYSERR_UNSUPPORTED for this function.

Return Values

Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:

The Compaq Ensoniq AudioPCI device supports one output port. Port 1 (MME_PORTMASK1) corresponds to the AC97 Line Out signal. Both the headset jack and the lineout jacks are connected to this port. See Also waveInGetPorts

#include <mme/mme_api.h> MMRESULT waveOutGetPosition(HWAVEOUT hWaveOut, LPMMTIME lpInfo, UINT uSize);

Arguments HWAVEOUT hWaveOut
Specifies a handle to a waveform audio output device.

LPMMTIME lpInfo
Specifies a pointer to an MMTIME data structure. The MMTIME data structure must be allocated with the mmeAllocMem function before being passed to the waveOutGetPosition function. See Chapter 2 for more information about the memory allocation functions.

UINT uSize
Specifies the size in bytes of the MMTIME data structure.

Description

The waveOutGetPosition function queries the current playback position of the specified waveform audio output device. Before calling the waveOutGetPosition function, set the wType field of the MMTIME data structure to indicate the desired time format. After calling the waveOutGetPosition function, check the wType field to determine if the desired time format is supported. If the desired format is not supported, the wType field specifies an alternative format.

Return Values

Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:

#include <mme/mme_api.h> MMRESULT waveOutGetVolume(UINT uClassDeviceId, LPDWORD lpdwVolume);

Arguments UINT uClassDeviceId
Identifies the waveform audio output device.

LPDWORD lpdwVolume
Specifies a pointer to a location to be filled with the current volume setting. The low-order word of this location contains the left-channel volume setting, and the high-order word contains the right-channel setting. A value of 0xFFFF represents full volume and a value of 0x0000 represents full muting (silence).

If a device does not support both left and right volume control, the low-order word of the specified location contains the monovolume level. The full 16-bit settings that are set with the waveOutSetVolume function are returned, whether or not the device supports the full 16 bits of volume-level control.

The lpdwVolume argument must be allocated with the mmeAllocMem function before being passed to the waveOutGetVolume function. See Chapter 2 for more information about the memory allocation functions.

Description

The waveOutGetVolume function queries the current volume setting of the specified waveform audio output device. Not all devices support volume changes. To determine whether the device supports volume control, use the WAVECAPS_VOLUME flag to test the dwSupport field of the WAVEOUTCAPS data structure filled by the waveOutGetDevCaps function.

To determine whether the device supports volume control on both the left and right channels, use the WAVECAPS_LRVOLUME flag to test the dwSupport field of the WAVEOUTCAPS data structure filled by the waveOutGetDevCaps function.

Return Values

Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:

#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 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 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 Chapter 2 for more information about the memory allocation functions.

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 less than the number of devices present. The WAVE_MAPPER constant may also be used as a device ID.

Depending on the waveform format (as specified by the wFormatTag field) specified with the lpFormat argument, the WAVEFORMAT data structure referenced by the lpFormat argument may have to be extended. 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.

Note Multimedia Services for OpenVMS 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.

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.

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 as described in Section 3.2.5. This work must be done outside the callback function. The Multimedia Services for OpenVMS 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 Compaq extensions to the API specification.

Return Values

Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes: