Compaq Multimedia Services
for OpenVMS Alpha
Programmer's Guide


Previous Contents Index

Internally, with reference to the audio chip signals, these ports correspond to the following:
Port Number External Name Internal Signal Name
1 Microphone MIC
2 Line Input AUX1
3 Not Available LINE_IN
4 Loopback LINE_OUT_LOOPBACK

Note

The following Compaq device-dependent names are defined in the file mmsystem.h :


#define MME_MSB_MICROPHONE_IN  MME_PORTMASK_01 
#define MME_MSB_LINE_IN   MME_PORTMASK_02 
#define MME_MSB_LINE_OUT_LOOPBACK_IN MME_PORTMASK_04 
 
#define MME_MAXWAVEPORTDESCLEN 32 /* Maximum port description length */ 
#define MME_MAXWAVEPORTS 32 /*Maximum number of ports for a wave device */ 

Ensoniq AudioPCI Board

The Ensoniq AudioPCI Board provides input and output port selection using the AC97 CODEC Version 2.1 chip. Not all of these may be available on a particular version of the Ensoniq AudioPCI Board. Note that the port numbers have been assigned to be compatible with the port numbers on the MSB. The AC97 input port assignments are:

Internally, with reference to the Audio Codec Version 2.1 specification, these ports correspond as follows:
Port Number External Name Internal Signal Name
1 Microphone MIC
2 Line Input LINE_IN
3 CD Input CD
4 Stereo Mix STEREO_MIX
5 Tuner Audio VIDEO
6 Aux AUX
7 Mono Mix MONO_MIX
8 Speaker Phone PHONE

Note

The following Compaq device-dependent names are defined in the file mmsystem.h :


#define MME_ENS_MIC_IN  MME_PORTMASK_01 
#define MME_ENS_LINE_IN  MME_PORTMASK_02 
#define MME_ENS_CD_IN  MME_PORTMASK_03 
#define MME_ENS_STEREO_MIX_IN MME_PORTMASK_04 
#define MME_ENS_VIDEO_IN MME_PORTMASK_05 
#define MME_ENS_AUX_IN  MME_PORTMASK_06 
#define MME_ENS_MONO_MIX_IN MME_PORTMASK_07 
#define MME_ENS_PHONE_IN  MME_PORTMASK_08 
#define MME_ENS_RECORD_SELECT_PORTS_IN 8 
 
#define MME_ENS_MIC_20DB MME_PORTMASK_09 
#define MME_ENS_MIX_MIC  MME_PORTMASK_10  
#define MME_ENS_MIX_LINE MME_PORTMASK_11 
#define MME_ENS_MIX_CD  MME_PORTMASK_12 
#define MME_ENS_MIX_PCM_OUT MME_PORTMASK_13 
#define MME_ENS_MIX_PC_BEEP MME_PORTMASK_14 
#define MME_ENS_MIX_PHONE MME_PORTMASK_15 
#define MME_ENS_MIX_VIDEO MME_PORTMASK_16 
#define MME_ENS_MIX_AUX  MME_PORTMASK_17 
 
#define MME_ENS_NUMBER_OF_PORTS_IN 17 

See Also waveOutGetPorts

waveInGetPosition

Name waveInGetPosition --- Retrieve the current position of the specified waveform audio input device Syntax


#include <mme/mme_api.h> 
 
MMRESULT waveInGetPosition(HWAVEIN hWaveIn, 
                           LPMMTIME lpInfo, 
                           UINT uSize); 
Arguments HWAVEIN hWaveIn
Specifies a handle to a waveform audio input 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 waveInGetPosition 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 waveInGetPosition function retrieves the current position of the specified waveform audio input device. The current position is defined as the number of samples in all buffers sent back to the application plus the number of samples in the buffer currently being filled (not the number of samples received by the hardware). The position is set to zero when the device is opened or reset.

Before calling the waveInGetPosition function, set the wType field of the MMTIME data structure to indicate the desired time format. After calling the waveInGetPosition 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. See Section 2.3 for more information about the MMTIME data structure.

Extensions None.

Return Values

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns the following error code:
Error Code Description
MMSYSERR_INVALHANDLE The specified device handle is invalid.
See Also None.

waveInGetVolume

Name waveInGetVolume --- Query the current audio input volume setting Syntax


#include <mme/mme_api.h> 
 
MMRESULT waveInGetVolume(UINT uClassDeviceID, 
                         LPDWORD lpdwVolume); 
Arguments UINT uClassDeviceID
Identifies the waveform audio input 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. 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 waveInSetVolume function are returned whether or not the device supports the full 16 bits of cvolume-level control.

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


Description

The waveInGetVolume function queries the current volume setting of the specified waveform audio input device. Not all audio 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.

Extensions The waveInGetVolume 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 The driver is not installed.
MMSYSERR_NOTSUPPORTED The function is not supported.
See Also waveInSetVolume

waveInOpen

Name waveInOpen --- Open the specified waveform audio input device for recording Syntax


#include <mme/mme_api.h> 
 
MMRESULT waveInOpen(LPHWAVEIN lphWaveIn, 
                    UINT uDeviceID, 
                    LPWAVEFORMAT lpFormat, 
                    VOID (*dwCallback) (), 
                    DWORD dwCallbackInstance, 
                    DWORD dwFlags); 
Arguments LPHWAVEIN lphWaveIn
Specifies a pointer to an HWAVEIN handle. This location is filled with a handle identifying the opened waveform audio input device. Use this handle to identify the device when calling other waveform audio input functions. This argument may be NULL if the WAVE_FORMAT_QUERY flag is specified for the dwFlags argument.

UINT uDeviceID
Identifies the waveform audio input device to open. Use a valid waveform audio input device ID or the WAVE_MAPPER flag. The WAVE_MAPPER flag causes the system to select the waveform audio input device that is best capable of recording audio data in the specified format and attempt to open it.

LPWAVEFORMAT lpFormat
Specifies a pointer to a WAVEFORMAT data structure that identifies the desired format for recording waveform audio data.

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 using the mmeAllocMem function before being passed to the waveInOpen function. See Chapter 2 for more information about the memory allocation functions.

VOID *(dwCallback) ()
Specifies the address of a callback function during waveform audio recording to process messages related to the progress of the audio recording. 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 device. The following flags are defined:

CALLBACK_FUNCTION
If this flag is specified, the value of the dwCallback argument is assumed to be a callback procedure address.

WAVE_ALLOWSYNC
If this flag is specified, it allows a synchronous (blocking) waveform driver to be opened. If this flag is not set while opening a synchronous driver, the open operation fails.

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 waveInOpen function opens the specified waveform audio input device for recording. The device ID specified by uDeviceID varies from zero to one less than the number of devices present. Use the waveInGetNumDevs function to determine the number of waveform input devices present in the system.

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.
Callback


void CALLBACK waveInCallbackFunction(HWAVEIN hWaveIn, 
                                     UINT uMsg, 
                                     DWORD dwInstance, 
                                     LPARAM lParam1, 
                                     LPARAM lParam2); 

The waveInCallbackFunction function name is a placeholder for the callback function name supplied by the application. If a waveInOpen 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 recording. Callback Arguments HWAVEIN hWaveIn
Specifies a handle to a waveform audio device associated with the callback function.

UINT uMsg
Specifies a waveform audio input message. The following messages are defined:

WIM_CLOSE
Sent when the device is closed using the waveInClose function.

WIM_OPEN
Sent when the device is opened using the waveInOpen function.

WIM_DATA
Sent when the device driver is finished processing a data block that was sent using the waveInAddBuffer function.

DWORD dwInstance
Specifies the user instance data specified as dwCallbackInstance with the waveInOpen function call.

LPARAM lParam1
Specifies an argument for the message. For the WIM_OPEN and WIM_CLOSE messages, this argument is not used.

For the WIM_DATA 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 waveInAddBuffer 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

1
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
Error Code Description
MMSYSERR_ALLOCATED The specified resource is allocated.
MMSYSERR_BADDEVICEID The specified device ID is out of range.
MMSYSERR_INVALHANDLE The specified device handle is invalid.
MMSYSERR_INVALPARAM The lphWaveIn argument is passed as NULL and the dwFlags argument is not set to WAVE_FORMAT_QUERY.
MMSYSERR_NOMEM Unable to allocate or lock memory.
WAVERR_BADFORMAT Attempted to open with an unsupported wave format.
WAVERR_DEVICENOTSHAREABLE The specified device is already opened as an exclusive device.
WAVERR_DEVICESHAREABLE The specified device is already opened as a shareable device.
See Also waveInClose

waveInReset

Name waveInReset --- Stop audio recording and reset current position Syntax


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


Description

The waveInReset function stops input on the specified waveform audio input device and resets the current position to 0. All pending buffers are marked as done and returned to the application via the callback defined in the waveInOpen function.

Before attempting to close a waveform audio input device, 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_BADDEVICEID The specified device ID is out of range.
MMSYSERR_HANDLEBUSY The handle hWaveIn is in use on another thread.
See Also waveInAddBuffer , waveInClose , waveInStart , waveInStop

waveInSelectPorts

Name waveInSelectPorts --- Select the ports through which input of audio data is enabled. This function is meaningful only for a wave input device with multiple ports. Syntax


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

DWORD dwPortMask
Specifies one or more ports to be selected.


Description

The waveInSelectPorts function enables audio input to be acquired through the ports specified by the dwPortMask parameter. The dwPortMask value is a bit mask; each bit set defines whether the corresponding port is to be selected. Mask values MME_PORTMASK_01 through MME_PORTMASK_32 are defined for use in specifying the port mask value.
Extensions The waveInSelectPorts 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 dwPortMask is not valid, or the selection of the ports specified is not supported by this device.
Device-Specific Notes

MSB Sound Board

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

Internally, with reference to the audio chip signals, these ports correspond to the following:
Port Number External Name Internal Signal Name
1 Microphone MIC
2 Line Input AUX1
3 Not Available LINE_IN
4 Loopback LINE_OUT_LOOPBACK

Note

The following Compaq device-dependent names are defined in the file mmsystem.h within an #ifdef DEC envelope:


#define MME_MSB_MICROPHONE_IN  MME_PORTMASK_01 
#define MME_MSB_LINE_IN   MME_PORTMASK_02 
#define MME_MSB_LINE_OUT_LOOPBACK_IN MME_PORTMASK_04 
 
#define MME_MAXWAVEPORTDESCLEN 32 /* Maximum port description length */ 
#define MME_MAXWAVEPORTS 32 /*Maximum number of ports for a wave device */ 

Ensoniq AudioPCI Board

The Ensoniq AudioPCI Board provides input and output port selection using the AC97 CODEC Version 2.1 chip. Not all of these may be available on a particular version of the Ensoniq AudioPCI Board. Note that the port numbers have been assigned to be compatible with the port numbers on the MSB. The AC97 input port assignments are:

Internally, with reference to the Audio Codec Version 2.1 specification, these ports correspond as follows:
Port Number External Name Internal Signal Name
1 Microphone MIC
2 Line Input LINE_IN
3 CD Input CD
4 Stereo Mix STEREO_MIX
5 Tuner Audio VIDEO
6 Aux AUX
7 Mono Mix MONO_MIX
8 Speaker Phone PHONE

Note

The following Compaq device-dependent names are defined in the file mmsystem.h :


#define MME_ENS_MIC_IN  MME_PORTMASK_01 
#define MME_ENS_LINE_IN  MME_PORTMASK_02 
#define MME_ENS_CD_IN  MME_PORTMASK_03 
#define MME_ENS_STEREO_MIX_IN MME_PORTMASK_04 
#define MME_ENS_VIDEO_IN MME_PORTMASK_05 
#define MME_ENS_AUX_IN  MME_PORTMASK_06 
#define MME_ENS_MONO_MIX_IN MME_PORTMASK_07 
#define MME_ENS_PHONE_IN  MME_PORTMASK_08 
#define MME_ENS_RECORD_SELECT_PORTS_IN 8 
 
#define MME_ENS_MIC_20DB MME_PORTMASK_09 
#define MME_ENS_MIX_MIC  MME_PORTMASK_10  
#define MME_ENS_MIX_LINE MME_PORTMASK_11 
#define MME_ENS_MIX_CD  MME_PORTMASK_12 
#define MME_ENS_MIX_PCM_OUT MME_PORTMASK_13 
#define MME_ENS_MIX_PC_BEEP MME_PORTMASK_14 
#define MME_ENS_MIX_PHONE MME_PORTMASK_15 
#define MME_ENS_MIX_VIDEO MME_PORTMASK_16 
#define MME_ENS_MIX_AUX  MME_PORTMASK_17 
 
#define MME_ENS_NUMBER_OF_PORTS_IN 17 

See Also waveOutSelectPorts


Previous Next Contents Index