80.2.1 Querying Audio Devices

Before playing or recording audio, you must determine the capabilities of the audio hardware present in the system. Audio capability can vary from one multimedia computer to the next; applications should not make assumptions about the audio hardware present in a given system.

80.2.1.1 Getting the Number of Devices

Windows provides the following functions to determine how many devices of a certain type are available in a given system:

Function Description

auxGetNumDevs Retrieves the number of auxiliary audio devices present in the system.
midiInGetNumDevs Retrieves the number of MIDI input devices present in the system.
midiOutGetNumDevs Retrieves the number of MIDI output devices present in the system.
waveInGetNumDevs Retrieves the number of waveform input devices present in the system.
waveOutGetNumDevs Retrieves the number of waveform output devices present in the system.

Audio devices are identified by a device identifier (device ID). The device ID is determined implicitly from the number of devices present in a given system. Device IDs range from 0 to 1 less than the number of devices present. For example, if there are 2 MIDI output devices in a system, valid device IDs are 0 and 1.

80.2.1.2 Getting the Capabilities of a Device

Once you determine how many devices of a certain type are present in a system, you can inquire about the capabilities of each device. Windows provides the following functions to determine the capabilities of audio devices:

Function Description

auxGetDevCaps Retrieves the capabilities of a given auxiliary audio device.
midiInGetDevCaps Retrieves the capabilities of a given MIDI input device.
midiOutGetDevCaps Retrieves the capabilities of a given MIDI output device.
waveInGetDevCaps Retrieves the capabilities of a given waveform input device.
waveOutGetDevCaps Retrieves the capabilities of a given waveform output device.

Each of these functions takes a far pointer to a data structure the function fills with information on the capabilities of a specified device. The following are the data structures that correspond to each of the device-inquiry functions:

Function Data Structure

auxGetDevCaps AUXCAPS
midiInGetDevCaps MIDIINCAPS
midiOutGetDevCaps MIDIOUTCAPS
waveInGetDevCaps WAVEINCAPS
waveOutGetDevCaps WAVEOUTCAPS

All of the device capabilities data structures have the following fields:

Field Description

wMid Specifies a manufacturer ID for the author of the device driver.
wPid Specifies a product ID for the device.
szPname Specifies an array of characters containing the name of the device in a null-terminated string.
vDriverVersion Specifies the version number of the device driver.

Microsoft will assign manufacturer IDs and product IDs specified by the wMid and wPid fields. The MMSYSTEM.H file contains constants for currently defined IDs.

The szPname field points to a null-terminated string containing the product name. You should use the product name to identify devices to users.

The vDriverVersion field specifies a version number for the device driver. The high-order of this field is the major version number; the low-order byte is the minor version number.