Property Sets for DirectMusic Ports

Use the IKsControl::KsProperty method to find out whether a property is available and then to set and retrieve values for that property. You 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:

BOOL IsGMSupported(IDirectMusicPort8 *pPort) 
{ 
  HRESULT   hr; 
  IKsControl  *pControl; 
  KSPROPERTY  ksp; 
  DWORD   dwFlags; 
  ULONG   cb; 
  BOOL    fIsSupported;
 
  // Query for an IKsControl interface.
  hr = pPort->QueryInterface(IID_IKsControl, (void**)&pControl); 
  if (FAILED(hr)) 
  { 
    // Port does not support properties; assume no GM support.
    return FALSE; 
  }
  // Ask about GM. 
  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;
}