Installing Device Interfaces for an Audio Adapter

A client accesses an audio device through a set of device interfaces that a vendor specifies in the adapter's INF file. The device interfaces specified in the INF file have a one-to-one correspondence with the subdevices that the adapter driver creates when it initializes the device (see Subdevice Creation). For each device interface, the INF file specifies a FriendlyName entry value, which is accessible in user mode, under the interface's registry key.

In the kernel-streaming architecture, topology categories (see KSPROPERTY_TOPOLOGY_CATEGORIES) represent device interface classes.

The following table lists the topology categories that audio adapters are most likely to use to describe the capabilities of their subdevices.

Category	Description
KSCATEGORY_ACOUSTIC_ECHO_CANCEL	An audio device that can perform acoustic echo cancellation (see DirectSound Capture Effects) registers itself under this category.
KSCATEGORY_AUDIO	All audio devices register themselves under this category.
KSCATEGORY_CAPTURE	An audio device that can capture a data stream registers itself under this category.
KSCATEGORY_DATATRANSFORM	An audio device that performs a data transformation on a stream registers itself under this category.
KSCATEGORY_MIXER	An audio device that can mix data streams registers itself under this category.
KSCATEGORY_RENDER	An audio device that can render a data stream registers itself under this category.
KSCATEGORY_SYNTHESIZER	An audio device that can convert MIDI messages to either wave audio samples or an analog output signal registers itself under this category (see Synthesizers and Wave Sinks).
KSCATEGORY_TOPOLOGY	A device's Topology miniport driver registers itself under this category.
KSCATEGORY_DRM_DESCRAMBLE	An audio device that can unscramble a DRM-protected wave stream registers itself under this category (see Digital Rights Management).

For a complete list of topology categories, see the KSCATEGORY_XXX GUIDs that are defined in the header files Ks.h and Ksmedia.h.

All audio devices are classified under KSCATEGORY_AUDIO, but an audio device might also be classified under additional categories such as KSCATEGORY_RENDER (for an audio rendering device) or KSCATEGORY_SYNTHESIZER (for a synthesizer). For each category that the INF file specifies for a device, the Windows Installer builds a set of registry entries for that device under the category name (see Filter Factories).

Only a device that contains a built-in synthesizer should register itself under the category KSCATEGORY_SYNTHESIZER. Note that this category excludes a pure MPU-401 device. A pure MPU-401 device, which can output or input raw MIDI to or from a UART, should register itself under these categories:

• KSCATEGORY_AUDIO

• KSCATEGORY_RENDER

• KSCATEGORY_CAPTURE

Note that the SysAudio system driver reserves the registry category KSCATEGORY_AUDIO_DEVICE exclusively for its virtual audio devices. Adapter drivers should not register themselves in this category.

The following example installs four common system-defined device interfaces that an adapter typically supports for an audio device.

Example: Installing Audio Device Interfaces

In this example, the device-install section for the XYZ Audio Device uses the INF AddInterface directive to install four audio adapter interfaces. In the following, each of the four directives assigns a unique reference string to an interface, which the adapter driver can use to distinguish between instances of each interface class.

  [XYZ-Audio-Device.Interfaces]
  AddInterface=%KSCATEGORY_AUDIO%,%KSName_Wave%,XYZ-Audio-Device.Wave
  AddInterface=%KSCATEGORY_RENDER%,%KSName_Wave%,XYZ-Audio-Device.Wave
  AddInterface=%KSCATEGORY_CAPTURE%,%KSName_Wave%,XYZ-Audio-Device.Wave
  AddInterface=%KSCATEGORY_TOPOLOGY%,%KSName_Topology%,XYZ-Audio-Device.Topology

The first three AddInterface directives specify an add-interface section named XYZ-Audio-Device.Wave. The last specifies an add-interface section named XYZ-Audio-Device.Topology. Each add-interface section adds the following registry entries to a device interface subkey, which is accessible in user mode under the \DeviceClasses\<InterfaceGUID> registry key:

• A FriendlyName registry entry specifies a friendly name for each device interface.

• Microsoft DirectShow requires a CLSID registry entry, set to a proxy GUID value, which indicates that the adapter can be accessed and controlled by the KSProxy system driver.

The two add-interface sections appear in the following example, which contains INF file entries that add each interface's FriendlyName and CLSID to the registry:

  [XYZ-Audio-Device.Wave]
  AddReg=XYZ-Audio-Device.Wave.AddReg
  [XYZ-Audio-Device.Wave.AddReg]
  HKR,,FriendlyName,,%WaveDeviceName%
  HKR,,CLSID,,%Proxy.CLSID%

  [XYZ-Audio-Device.Topology]
  AddReg=XYZ-Audio-Device.Topology.AddReg
  [XYZ-Audio-Device.Topology.AddReg]
  HKR,,FriendlyName,,%WaveDeviceMixerName%
  HKR,,CLSID,,%Proxy.CLSID%

The keyword HKR in this example denotes the system-supplied registry path for the device. For more information, see INF AddReg Directive.

The following is the Strings section for this example.

  [Strings]
  KSCATEGORY_AUDIO="{6994AD04-93EF-11D0-A3CC-00A0C9223196}"
  KSCATEGORY_RENDER="{65E8773E-8F56-11D0-A3B9-00A0C9223196}"
  KSCATEGORY_CAPTURE="{65E8773D-8F56-11D0-A3B9-00A0C9223196}"
  KSCATEGORY_TOPOLOGY="{DDA54A40-1E4C-11D1-A050-405705C10000}"
  Proxy.CLSID="{17CCA71B-ECD7-11D0-B908-00A0C9223196}"
  WaveDeviceName="XYZ Audio Device"
  WaveDeviceMixerName="XYZ Audio Device Super Mixer"

The string name that an AddInterface directive specifies for a KSCATEGORY_XXX device interface cannot be localized because the adapter driver uses the same name internally as a string constant. The sample adapter drivers in the Windows Driver Kit (WDK) use the following string names for their audio device interfaces:

  KSNAME_Wave="Wave"
  KSNAME_UART="UART"
  KSNAME_FMSynth="FMSynth"
  KSNAME_Topology="Topology"
  KSNAME_Wavetable="Wavetable"
  KSNAME_DMusic="DMusic"

For the sake of uniformity, your proprietary driver should assign these same names to its corresponding device interfaces. If your driver supports additional device interfaces that are proprietary, you can invent your own proprietary names for these interfaces. Make sure that the names that the driver uses match those in your INF file. If the strings do not match, system setup will not load the driver.