IDirectMusicCollection::EnumInstrument

  • Article

This method retrieves the patch and name of an instrument by its index in the collection.

HRESULT EnumInstrument(
  DWORD dwIndex,
  DWORD* pdwPatch,
  LPWSTR pwszName,
  DWORD dwNameLen
);

Parameters

  • dwIndex
    Index of the instrument in the collection.
  • pdwPatch
    Address of a variable to receive the patch number.
  • pwszName
    Address of a buffer to receive the instrument name. Can be NULL if the name is not wanted.
  • dwNameLen
    Size of the instrument name buffer, in WCHARs.

Return Values

If the method succeeds, the return value is S_OK, or S_FALSE if there is no instrument with that index number.

If it fails, the method can return one of the following error values:

E_FAIL
E_OUTOFMEMORY
E_POINTER

Remarks

To enumerate all instruments in a collection, start with a dwIndex of 0 and increment until EnumInstrument returns S_FALSE.

The patch number returned in pdwPatch describes the full patch address, including the MIDI parameters for MSB and LSB bank select. For more information, see MIDI Channel Messages.

Although the ordering of the enumeration is consistent within one instance of a DLS collection, it has no relationship to the ordering of instruments in the file, their patch numbers, or their names.

For an example of instrument enumeration, see Working with Instruments.

Requirements

OS Versions: Windows CE .NET 4.0 and Windows CE .NET 4.1.
Header: Dmusicc.h.
Link Library: Dmusic.lib.

 Last updated on Monday, April 12, 2004

© 1992-2002 Microsoft Corporation. All rights reserved.