Property Sets for DirectMusic Ports

Through property sets, DirectMusic is able to support extended services offered by synthesizers.

Hardware vendors define new capabilities as properties and publish the specification for these properties. A GUID identifies a property set, and a ULONG identifies a particular property within the set. Individual properties may also have associated parameters. The meaning of the parameters is defined along with the properties.

Use the IKsControl::KsProperty method to find out whether a property is available and then to set and retrieve values for that property. You can obtain the IKsControl interface for a port by calling the IDirectMusicPort8::QueryInterface method, passing IID_IKsControl as the interface identifier.

A property set is represented by a GUID, and each item within the set is represented by a zero-based index. The meaning of the indexed items for a GUID never changes. For a list of the property sets supported by DirectMusic, see KSPROPERTY.

All property sets predefined by DirectMusic have only one item, usually at index 0. However, the full definition of kernel-streaming (KS) properties is supported, and vendors are free to create property sets with any number of items and instances, and data of any size.

Routing of the property item request to the port varies depending on the port implementation. No properties are supported by ports that represent DirectMusic emulation over the Win32® handle-based multimedia calls (the midiOut and midiIn functions).

The following code example uses the IKsControl::KsProperty method to determine if the port supports General MIDI in hardware:

#include <dmksctrl.h>

BOOL IsGMSupported(IDirectMusicPort8 *pPort) 
{ 
  HRESULT   hr; 
  IKsControl  *pControl; 
  KSPROPERTY  ksp; 
  DWORD   dwFlags; 
  ULONG   cb; 
  BOOL    fIsSupported;
 
  hr = pPort->QueryInterface(IID_IKsControl, (void**)&pControl); 
  if (FAILED(hr)) 
  { 
    // Port does not support properties; assume no GM support.
    return FALSE; 
  }
  ksp.Set = GUID_DMUS_PROP_GM_Hardware; 
  ksp.Id  = 0; 
  ksp.Flags = KSPROPERTY_TYPE_BASICSUPPORT;
  hr = pControl->KsProperty(&ksp, sizeof(ksp),
    &dwFlags, sizeof(dwFlags), &cb);
  fIsSupported = FALSE; 
  if ((SUCCEEDED(hr)) || (cb >= sizeof(dwFlags)))
  {
    // Set is supported.
    fIsSupported = (BOOL)(dwFlags & KSPROPERTY_TYPE_GET);
  }
  pControl->Release();
  return fIsSupported;
}