The DeviceTopology API provides client applications with the ability to traverse the functional hardware topologies of audio rendering and capture devices. Through the interfaces and methods in the DeviceTopology API, clients can discover the functional subunits (for example, volume control) that lie along the data paths that lead to and from audio endpoint devices. Clients can traverse the internal topologies of both audio adapter devices and audio endpoint devices and step across the connections that link one device to another. For more information, see Device Topologies.
Header file Devicetopology.h defines the interfaces in the DeviceTopology API.
To access the DeviceTopology API interfaces, a client first obtains a reference to the IDeviceTopology interface for an audio endpoint device by following these steps:
- By using one of the techniques described in IMMDevice Interface, obtain a reference to the IMMDevice interface for an audio endpoint device.
- Call the IMMDevice::Activate method with parameter iid set to REFIID IID_IDeviceTopology.
The client can obtain references to the other interfaces in the DeviceTopology API by calling the methods in the IDeviceTopology interface.
The DeviceTopology API implements the following interfaces.
|IAudioAutoGainControl||Provides access to a hardware automatic gain control (AGC).|
|IAudioBass||Provides access to a hardware bass-level control.|
|IAudioChannelConfig||Provides access to a hardware channel-configuration control.|
|IAudioInputSelector||Provides access to a hardware multiplexer control (input selector).|
|IAudioLoudness||Provides access to a "loudness" compensation control.|
|IAudioMidrange||Provides access to a hardware midrange-level control.|
|IAudioMute||Provides access to a hardware mute control.|
|IAudioOutputSelector||Provides access to a hardware demultiplexer control (output selector).|
|IAudioPeakMeter||Provides access to a hardware peak-meter control.|
|IAudioTreble||Provides access to a hardware treble-level control.|
|IAudioVolumeLevel||Provides access to a hardware volume control.|
|IConnector||Represents a point of connection between components.|
|IControlInterface||Represents a control interface on a part (subunit or connector).|
|IDeviceSpecificProperty||Represents a device-specific property of a connector or subunit.|
|IDeviceTopology||Provides access to the topology of an audio device.|
|IKsFormatSupport||Provides information about the audio data formats that are supported by a software-configured I/O connection (typically a DMA channel) between the audio device and system memory.|
|IKsJackDescription||Provides information about the jacks or internal connectors that provide a physical connection between a device on an audio adapter and an external or internal endpoint device (for example, a microphone or CD player).|
|IPart||Represents a part (connector or subunit) of a device topology.|
|IPartsList||Represents a list of parts (connectors and subunits).|
|IPerChannelDbLevel||Represents a generic subunit control interface that provides per-channel control over the volume level, in decibels, of an audio stream or of a frequency band in an audio stream.|
|ISubunit||Represents a hardware subunit (for example, a volume-level control) that lies in the data path between a client and an audio endpoint device.|
DeviceTopology API clients that require notification of control-change events in connectors and subunits should implement the following interface.
|IControlChangeNotify||Provides notifications when the status of a part (connector or subunit) changes.|