Compaq Multimedia Services
for OpenVMS Alpha
Programmer's Guide
Previous Contents Index

3.8 Waveform Audio Function Descriptions

This section contains an alphabetical listing of the functions an application uses to manage audio recording and playback. These functions are prefixed with wave.

waveInAddBuffer

 Name waveInAddBuffer --- Send an input buffer to a waveform audio input device and return the filled buffer Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveInAddBuffer (HWAVEIN hWaveIn, 
                          LPWAVEHDR lpWaveInHdr, 
                          UINT wSize);
Arguments HWAVEIN hWaveIn
Specifies a handle to a waveform audio input device.

LPWAVEHDR lpWaveInHdr
Specifies a pointer to a WAVEHDR data structure that identifies the input buffer ( lpWaveInHdr->lpData ).

The WAVEHDR data structure must be allocated with the mmeAllocMem function and the input buffer must be allocated with the mmeAllocBuffer function before being passed to the waveInAddBuffer function. See Chapter 2 for more information about the memory allocation functions.

UINT wSize
Specifies the size, in bytes, of the WAVEHDR data structure.

Description

The waveInAddBuffer function sends an input buffer to the specified waveform audio input device. When the buffer is filled, the function returns it to the calling program. This buffer is returned to the application via the callback defined in the waveInOpen function.
Extensions None.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
MMSYSERR_HANDLEBUSY The handle hWaveIn is in use on another thread.
MMSYSERR_INVALHANDLE The specified device handle is invalid.
WAVERR_UNPREPARED The lpWaveInHdr argument is not prepared.
See Also None.

waveInClose

 Name waveInClose --- Close the specified waveform audio input device Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveInClose (HWAVEIN hWaveIn)
Arguments HWAVEIN hWaveIn
Specifies a handle to a waveform audio input device. If the function is successful, the handle is no longer valid after this call.

Description

The waveInClose function closes the specified waveform audio input device. If input buffers sent to the device with the waveInAddBuffer function have not been returned to the application, the close operation fails.

To ensure a successful close operation, call the waveInReset function to mark all pending buffers as done. Then, call the waveInClose function to close the device.

Extensions None.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
MMSYSERR_INVALHANDLE The specified device handle is invalid.
WAVERR_STILLPLAYING There are buffers still in the queue.
See Also waveInOpen , waveInReset

waveInFormatDetails

 Name waveInFormatDetails --- Query the specified waveform audio input device to determine detailed information relating to a specific supported format Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveInFormatDetails (UINT uClassDeviceID, 
                              LPACMFORMATDETAILS pafd, 
                              DWORD fdwDetails);
Arguments UINT uClassDeviceID
Identifies the waveform audio input device.

LPACMFORMATDETAILS pafd
Specifies a pointer to a ACMFORMATDETAILS data structure. Certain fields in the data structure may be used to pass selection information to the function; most fields are then entered by the function and returned to the caller. See Section 3.6.7 for more information about the ACMFORMATDETAILS data structure.

The ACMFORMATDETAILS and WAVEFORMATEX data structures must be allocated with the mmeAllocMem function before being passed to the waveInFormatDetails function. See Chapter 2 for more information about the memory allocation functions.

DWORD fdwDetails
Flags for querying the audio input device for detailed format information. The following flags are defined:

ACM_FORMATDETAILSF_FORMAT
Specifies that a format is selected by index.

ACM_FORMATDETAILSF_WAVEINDEX
Specifies that a format is selected by the information in the WAVEFORMATEX data structure.

Description

The waveInFormatDetails function queries the specified waveform audio input device to determine specific information relating to a format specified by the caller.

The application must set the cbStruct, pwfx, and cbwfx fields in the ACMFORMATDETAILS structure before calling this function. The fdwDetails argument is used to specify how the format is specified. If querying by index, the dwFormatIndex field must be set to the desired format, and the dwFormatTag field must be set to zero. If querying by wave format, the WAVEFORMATEX data structure pointed to by the pwfx field must be initialized with information about the desired format.

On successful return from the function, pafd is returned as follows:
Flag Description
dwFormatIndex Index from 0 to one less than the number of formats supported by this device.
dwFormatTag Format tag value for the format as defined in the mmsystem.h file.
*pwfx A WAVEFORMATEX data structure containing the format.
szFormat An ASCII null-terminated description of the format.
fdwSupport See Section 3.6.7 for supported flags.

Extensions The waveInFormatDetails function is a Compaq extension to the Microsoft multimedia API specification.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
MMSYSERR_BADDEVICEID The specified device is invalid.
MMSYSERR_INVALPARAM The parameter pafd is NULL.
The value of the pafd-> cbStruct,
pafd-> pwfx-> cbSize, or
pafd-> cbwfx field is invalid.
The value of fdwDetails is invalid.
The parameter pafd or pafd-> pwfx
is not allocated from shared memory.
MMSYSERR_NODRIVER A waveIn driver is not installed.
See Also waveInGetFormatInfo , waveInGetNumDevs

waveInGetDevCaps

 Name waveInGetDevCaps --- Query the specified waveform audio input device to determine its capabilities Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveInGetDevCaps (UINT uClassDeviceID, 
                           LPWAVEINCAPS lpCaps, 
                           UINT wSize);
Arguments UINT uClassDeviceID
Identifies the waveform audio input device.

LPWAVEINCAPS lpCaps
Specifies a pointer to a WAVEINCAPS data structure. This data structure is filled with information about the capabilities of the device.

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

UINT wSize
Specifies the size, in bytes, of the WAVEINCAPS data structure.

Description

The waveInGetDevCaps function queries the specified waveform audio input device to determine its capabilities. The device ID specified by the uClassDeviceID argument varies from zero to one less than the number of devices present. The WAVE_MAPPER constant can also be used as a device ID. (Use the waveInGetNumDevs function to determine the number of waveform audio input devices present in the system.)

Only wSize bytes (or less) of information are copied to the location pointed to by the lpCaps argument. If the value of the wSize argument is zero, nothing is copied and the function returns MMSYSERR_NOERROR.

Extensions The WAVEINCAPS data structure has been extended to support 8-bit mono MULAW at 8 kHz waveform audio format. The
WAVE_FORMAT_08M08_MULAW format identifier is a Compaq extension to the API specification to support the built-in audio capabilities of Alpha workstations. See Section 3.6.5 for more information about specifying this waveform audio format.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
MMSYSERR_BADDEVICEID The specified device ID is out of range.
MMSYSERR_NODRIVER No waveIn driver is installed.
MMSYSERR_INVALPARAM The size of the WAVEINCAPS data structure is invalid.
See Also waveInGetFormatInfo waveInGetNumDevs

waveInGetDevCapsEx

 Name waveInGetDevCapsEx --- Query the specified waveform audio input device to determine its capabilities and its supported standard formats Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveInGetDevCapsEx (UINT uClassDeviceID, 
                             LPWAVEINCAPS lpCaps, 
                             UINT wSize);
Arguments UINT uClassDeviceID
Identifies the waveform audio input device.

LPWAVEINCAPS lpCaps
Specifies a pointer to a WAVEINCAPS data structure. This data structure is filled with information about the capabilities of the device.

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

UINT wSize
Specifies the size, in bytes, of the WAVEINCAPS data structure.

Description

The waveInGetDevCapsEx function queries the specified waveform audio input device to determine its capabilities. The device ID specified by the uClassDeviceID argument varies from zero to one less than the number of devices present. The WAVE_MAPPER constant can also be used as a device ID. (Use the waveInGetNumDevs function to determine the number of waveform audio input devices present in the system.)

Only wSize bytes (or less) of information are copied to the location pointed to by the lpCaps argument. If the value of the wSize argument is zero, nothing is copied and the function returns MMSYSERR_NOERROR.

The dwFormat field of the WAVEINCAPS data structure will return all the standard formats supported by the device. See Section 3.6.5 for more information about specifying this waveform audio format.

Extensions The waveInGetDevCapsEx function is a Compaq extension to the Microsoft multimedia API specification.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
MMSYSERR_BADDEVICEID The specified device ID is out of range.
MMSYSERR_NODRIVER No waveIn driver is installed.
MMSYSERR_INVALPARAM The size of the WAVEINCAPS data structure is invalid.
See Also waveInGetDevCaps , waveInGetNumDevs

waveInGetErrorText

 Name waveInGetErrorText --- Retrieve a text description of the error identified by the specified error number Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveInGetErrorText (UINT uError, 
                             LPSTR lpText, 
                             UINT uSize);
Arguments UINT uError
Specifies the error number.

LPSTR lpText
Specifies a pointer to a buffer to be filled with the text error description.

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

UINT uSize
Specifies the size, in bytes, of the buffer pointed to by the lpText argument.

Description

The waveInGetErrorText function retrieves a text description of the error identified by the specified error number. If the text error description is longer than the buffer, the description is truncated. The returned string is always null terminated. If the value of the uSize argument is zero, nothing is copied and the function returns MMSYSERR_NOERROR. All error descriptions are less than MAXERRORLENGTH characters long.
Extensions None.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns the following error code:
Error Code Description
MMSYSERR_BADERRNUM The specified error number is out of range.
See Also None.

waveInGetID

 Name waveInGetID --- Get device ID for the specified waveform audio input device Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveInGetID (HWAVEIN hWaveIn, 
                      PUINT lpuDeviceID);
Arguments HWAVEIN hWaveIn
Specifies a handle to a waveform audio input device.

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

Description

The waveInGetID function gets the device ID for the specified waveform audio input device.
Extensions None.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
MMSYSERR_HANDLEBUSY The handle hWaveIn is in use on another thread.
MMSYSERR_INVALHANDLE The specified device handle is invalid.
See Also None.

waveInGetFormatInfo

 Name waveInGetFormatInfo --- Query the specified waveform audio input device to determine high-level information relating to all supported formats Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveInGetFormatInfo (UINT uClassDeviceID, 
                              LPWAVEFORMATINFO lpWaveformatInfo);
Arguments UINT uClassDeviceID
Identifies the waveform audio input device.

LPWAVEFORMATINFO lpWaveformatInfo
Specifies a pointer to a WAVEFORMATINFO data structure. The waveInGetFormatInfo 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 waveInGetFormatInfo function. See Chapter 2 for more information about the memory allocation functions.

Description

The waveInGetFormatInfo 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.5 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.

Extensions The waveInGetFormatInfo function is a Compaq extension to the Microsoft multimedia API specification.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
MMSYSERR_BADDEVICEID The specified device is invalid.
MMSYSERR_INVALPARAM The parameter lpWaveformatInfo is NULL.
The value of the cbStruct field within the
parameter lpWaveformatInfo is invalid.
The parameter lpWaveformatInfo is not
allocated from shared memory.
MMSYSERR_NODRIVER A waveIn driver is not installed.
See Also waveInFormatDetails , waveInGetNumDevs

waveInGetNumDevs

 Name waveInGetNumDevs --- Return the number of waveform audio input devices Syntax 


#include <mme/mme_api.h> 
 
UINT waveInGetNumDevs()
Arguments None.

Description

The waveInGetNumDevs function returns the number of waveform audio input devices present in the system.
Extensions None.

Return Values

1
Returns the number of waveform input devices present in the system.

See Also waveInGetDevCaps

waveInGetPorts

 Name waveInGetPorts --- Determine the ports through which input of audio data is enabled and determine information about all input ports supported by this device. This function is meaningful only for a wave input device with multiple ports. Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveInGetPorts(UINT uClassDeviceID, 
                        LPDWORD lpdwPortMask, 
                        PUINT lpuNumPorts, 
                        LPSTR lpText, 
                        UINT uSize);
Arguments UINT uClassDeviceID
Identifies the waveform audio input 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 waveInGetPorts function queries the current port selection mask and maximum number of ports supported for the specified waveform audio input device. Not all audio devices support a port selection capability. The port selection capability provides the ability to select one or more or the available ports (connections) for a device.

The waveInGetPorts function also returns text descriptions of all ports supported for the specified waveform audio input 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 input port, or if it provides no selection capability among ports, then it may return MMSYSERR_UNSUPPORTED for this function.

Extensions The waveInGetPorts function is a Compaq extension to the Microsoft multimedia API specification.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
MMSYSERR_BADDEVICEID The specified device ID is out of range.
MMSYSERR_NOTSUPPORTED This function is not supported for this device.
MMSYSERR_INVALPARAM The value of uSize is positive, but the value of lpText is NULL.
Device-Specific Notes

MSB Sound Board

The MSB (Microsoft Sound Board) or equivalent input device supports multiple ports. For the MSB:

Previous Next Contents Index