waveOutGetPorts(3mms) — Subroutines
Name
waveOutGetPorts --- Determine the ports through which output of audio data is enabled and determine information about all output ports supported by this device. This function is meaningful only for a wave output device with multiple ports.
Syntax
#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, 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 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.
Extensions
The waveOutGetPorts 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 output device supports several configurations of ports that are platform dependent. Port 1 (MME_PORTMASK_01) is the output side of the handset/headset RJ11 port as well as the output side of the headset jack. Port 2 (MME_PORTMASK_02) is the internal speaker port. The default selection is both ports enabled.
The Digital J300 wave audio output device supports two ports. Port 1 (MME_PORTMASK_01) corresponds to the 1/8-inch (3.45 mm) stereo output jack. Port 2 (MME_PORTMASK_02) corresponds to the output portion of the headset jack. The default selection is port 1.
The MSB (Microsoft Sound Board or equivalent) output device does not support multiple ports.
The Personal Workstation audio device supports two output ports. Both ports can be independently enabled and disabled. (See Appendix B of the Programmer’s Guide for more information.)
Port 1 (MME_PORTMASK1) corresponds to the PC Speaker. The PC Speaker port is used for mixing beeps generated by the system with other audio output.
Port 2 (MME_PORTMASK2) corresponds to the Record Monitor. Normal operation is with the Remote Monitor not enabled. This allows the playback audio stream to be heard through the speakers and headphones. If the Remote Monitor is enabled, then the record audio stream is heard through the speakers and headphones.