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

waveInSetVolume

 Name waveInSetVolume --- Set the current volume of the specified waveform audio input device Syntax 


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

DWORD dwVolume
Specifies the new volume setting. The low-order word 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 dwVolume argument specifies the volume level and the high-order word is ignored.

Description

The waveInSetVolume function sets the current volume of the specified waveform audio input 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.

Most devices do not support the full 16 bits of volume-level control and do not use the high-order bits of the requested volume setting. For example, for a device supporting 4 bits of volume control, requested volume level values of 0x4000, 0x4fff, and 0x43be produce the same physical volume setting, 0x4000.

The waveInGetVolume function returns the full 16-bit setting that is set with the waveInSetVolume function. Volume settings are interpreted logarithmically. This means that the perceived increase in volume is the same when increasing the volume level from 0x5000 to 0x6000 as it is from 0x4000 to 0x5000.

Note
It is important that you do not set the input volume controls too high. If the volume is set too high, data can be clipped from your application. See Section 3.3.5 for more information about modifying volume.
Extensions The waveInSetVolume 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_INVALHANDLE The specified device handle is invalid.
MMSYSERR_NODRIVER The driver is not installed.
MMSYSERR_NOTSUPPORTED The function is not supported.
Device-Specific Notes See Appendix B for device-specific information regarding volume. See Also waveInGetVolume

waveInStart

 Name waveInStart --- Start audio recording Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveInStart(HWAVEIN hWaveIn)
Arguments HWAVEIN hWaveIn
Specifies a handle to a waveform audio input device.

Description

The waveInStart function starts recording on the specified waveform audio input device. Buffers are returned to the client when they are full or when the waveInReset function is called. (The dwBytesRecorded field in the header contains the actual length of data.) If no buffers are in the queue, the data is thrown away, the client is not notified, and input continues.

Calling the waveInStart function when input is already started has no effect, and the function returns the MMSYSERR_NOERROR error code.

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.
MMSYSERR_HANDLEBUSY The handle hWaveIn is in use on another thread.
See Also waveInReset , waveInStop

waveInStop

 Name waveInStop --- Stop audio recording Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveInStop(HWAVEIN hWaveIn)
Arguments HWAVEIN hWaveIn
Specifies a handle to a waveform audio input device.

Description

The waveInStop function stops recording on the specified waveform audio input device. If there are any buffers in the queue, the current buffer is marked as done. The dwBytesRecorded field in the header contains the actual length of data but any empty buffers in the queue remain there.

Calling the waveInStop function if input is not started has no effect, and the function returns the MMSYSERR_NOERROR error code.

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.
MMSYSERR_HANDLEBUSY The handle hWaveIn is in use on another thread.
See Also waveInReset , waveInStart

waveOutBreakLoop

 Name waveOutBreakLoop --- Break a loop Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveOutBreakLoop(HWAVEOUT hWaveOut)
Arguments HWAVEOUT hWaveOut
Specifies a handle to a waveform audio output device.

Description

The waveOutBreakLoop function breaks a loop on the specified waveform audio output device and allows playback to continue with the next block in the driver list. Waveform looping is controlled by the dwLoops and dwFlags fields in the WAVEHDR data structures passed to the device with the waveOutWrite function. Use the WHDR_BEGINLOOP and WHDR_ENDLOOP flags in the dwFlags field to specify the beginning and ending data blocks for looping.

To loop on a single block, specify both flags for the same block. To specify the number of loops, use the dwLoops field in the WAVEHDR data structure for the first block in the loop.

The blocks making up the loop are played to the end before the loop is terminated.

Calling the waveOutBreakLoop function when nothing is playing or looping has no effect, and the function returns the MMSYSERR_NOERROR error code.

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.
MMSYSERR_HANDLEBUSY The handle hWaveOut is in use on another thread.
See Also waveOutPause , waveOutRestart , waveOutWrite

waveOutClose

 Name waveOutClose --- Close the specified waveform audio output device Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveOutClose(HWAVEOUT hWaveOut)
Arguments HWAVEOUT hWaveOut

Specifies a handle to a waveform audio output device. If the function is successful, the handle is no longer valid after this call.

Description

The waveOutClose function closes the specified waveform audio output device. If the device is still playing a waveform, the close operation fails.

To ensure a successful close operation, call the waveOutReset function to mark all pending buffers as done. Then, call the waveOutClose 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.
MMSYSERR_HANDLEBUSY The handle hWaveOut is in use on another thread.
WAVERR_STILLPLAYING There are buffers still in the queue.
See Also waveOutOpen , waveOutReset

waveOutFormatDetails

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


#include <mme/mme_api.h> 
 
MMRESULT waveOutFormatDetails (UINT uClassDeviceID, 
                               LPACMFORMATDETAILS pafd, 
                               DWORD fdwDetails);
Arguments UINT uClassDeviceID
Identifies the waveform audio output 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 output 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 waveOutFormatDetails function queries the specified waveform audio output 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 waveOutFormatDetails 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 waveOutGetFormatInfo , waveOutGetNumDevs

waveOutGetDevCaps

 Name waveOutGetDevCaps --- Query the specified waveform audio output device to determine its capabilities Syntax 


#include <mme/mme_api.h> 
 
MMRESULT waveOutGetDevCaps(UINT uDeviceID, 
                           LPWAVEOUTCAPS lpCaps, 
                           UINT uSize);
Arguments UINT uDeviceID
Identifies the waveform audio output device to query. Use a valid waveform audio output device ID or the WAVE_MAPPER constant.

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

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

UINT uSize
Specifies the size, in bytes, of the WAVEOUTCAPS data structure.

Description

The waveOutGetDevCaps function queries the specified waveform audio output device to determine its capabilities. The device ID specified by the uDeviceID argument varies from zero to one less than the number of devices present. Use the waveOutGetNumDevs function to determine the number of waveform output devices present in the system.

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

Extensions The WAVEOUTCAPS data structure has been extended to support an 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 AlphaStations. See Section 3.6.6 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, or WAVE_MAPPER is specified and no device is installed.
MMSYSERR_NODRIVER No waveOut driver is installed.
MMSYSERR_INVALPARAM The size of the WAVEOUTCAPS data structure is invalid.
See Also waveOutGetDevCapsEx waveOutGetNumDevs

waveOutGetDevCapsEx

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


#include <mme/mme_api.h> 
 
MMRESULT waveOutGetDevCapsEx(UINT uDeviceID, 
                             LPWAVEOUTCAPS lpCaps, 
                             UINT uSize);
Arguments UINT uDeviceID
Identifies the waveform audio output device to query. Use a valid waveform audio output device ID or the WAVE_MAPPER constant.

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

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

UINT uSize
Specifies the size, in bytes, of the WAVEOUTCAPS data structure.

Description

The waveOutGetDevCapsEx function queries the specified waveform audio output device to determine its capabilities. The device ID specified by the uDeviceID argument varies from zero to one less than the number of devices present. Use the waveOutGetNumDevs function to determine the number of waveform output devices present in the system.

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

The waveOutGetDevCapsEx function will always return all standard formats supported by the device.

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

Extensions The waveOutGetDevCapsEx 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, or WAVE_MAPPER is specified and no device is installed.
MMSYSERR_NODRIVER No waveOut driver is installed.
MMSYSERR_INVALPARAM The size of the WAVEOUTCAPS data structure is invalid.
See Also waveOutGetDevCaps , waveOutGetNumDevs

waveOutGetErrorText

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


#include <mme/mme_api.h> 
 
MMRESULT waveOutGetErrorText(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 waveOutGetErrorText 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 waveOutGetErrorText function retrieves a text description of the error identified by the specified error number. If the text error description is longer than the specified buffer, the description is truncated. The returned error string is always null terminated. If uSize is zero, nothing is copied, and the function returns the MMSYSERR_NOERROR error code. 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.

Previous Next Contents Index