waveInGetPorts(3mms) — Subroutines
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, this 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, this 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, this 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 returned identifies the maximum number of ports supported on the specified device.
The lpText value returned 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 Digital extension to the Microsoft multimedia API specification.
Return Values
Returns MMSYSERR_NOERROR if the function is successful; otherwise, it returns one of the following error codes:
MMSYSERR_BADDEVICEID@T{ The specified device ID is out of range. T} MMSYSERR_NOTSUPPORTED@T{ This function is not supported for this device. T} MMSYSERR_INVALPARAM@T{ The value of uSize is positive, but the value of lpText is NULL. T}
Device-Specific Notes
The Alpha AXP Baseboard wave audio input device does not support input port selection and returns MMSYSERR_NOTSUPPORTED.
The Digital J300 wave audio input device supports two ports. Port 1 (MME_PORTMASK_01), the default port, corresponds to the 1/8-inch (3.45 mm) stereo input jack. Port 2 (MME_PORTMASK_02) corresponds to the input portion of the headset jack. Only one port may be selected at a time.
The MSB (Microsoft Sound Board or equivalent) input device supports multiple ports. For the MSB:
Port 1 (MME_PORTMASK_01) corresponds to the microphone port.
Port 2 (MME_PORTMASK_02) corresponds to the line input port (left and right.
Port 3 (MME_PORTMASK_03) is not available on the Microsoft Sound Board.
Port 4 (MME_PORTMASK_04) corresponds to the internal loopback of the output to the input.
Internally, with reference to the audio chip signals, these ports correspond to the following:
1@Microphone@T{ MIC T} 2@Line Input@T{ AUX1 T} 3@Not Available@T{ LINE_IN T} 4@Loopback@T{ LINE_OUT_LOOPBACK T}
The Personal Workstation audio device supports five input ports. Only one input port at a time can be selected. (See Appendix B of the Programmer’s Guide for more information about these ports.)
Port 1 (MME_PORTMASK_01) corresponds to the microphone port.
Port 2 (MME_PORTMASK_02) corresponds to the auxiliary CD-ROM port.
Port 3 (MME_PORTMASK_03) corresponds to the line input port.
Port 4 (MME_PORTMASK_04) corresponds to the playback mixer port. The playback mixer can be used to record the playback of an audio wave file stream mixed with audio input from another source.
Port 5 (MME_PORTMASK_05) corresponds to the record mixer port. The record mixer by default has all of its input signals muted.
The following Digital device-dependent names are defined in the file mmsystem.h.
#define MME_J300_STEREO_IN MME_PORTMASK_01
#define MME_J300_LINE_IN MME_PORTMASK_01
#define MME_J300_HEADSET_IN MME_PORTMASK_02
#define MME_J300_PHONE_IN MME_PORTMASK_02
#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_ESS_MICROPHONE_IN MME_PORTMASK_01
#define MME_ESS_AUX_CD_IN MME_PORTMASK_02
#define MME_ESS_LINE_IN MME_PORTMASK_03
#define MME_ESS_PLAYBACK_MIXER_IN MME_PORTMASK_04
#define MME_ESS_RECORD_MIXER_IN MME_PORTMASK_05
#define MME_MAXWAVEPORTDESCLEN 32 /∗ Maximum port description length ∗/
#define MME_MAXWAVEPORTS 32 /∗Maximum number of ports for a wave device ∗/