IDirectMusicPerformance::DownloadInstrument

The IDirectMusicPerformance::DownloadInstrument method downloads DLS data for an instrument to a port.

HRESULT DownloadInstrument(
  IDirectMusicInstrument* pInst,
  DWORD dwPChannel,
  IDirectMusicDownloadedInstrument** ppDownInst,
  DMUS_NOTERANGE* pNoteRanges, 
  DWORD dwNumNoteRanges, 
  IDirectMusicPort** ppPort,
  DWORD* pdwGroup,
  DWORD* pdwMChannel
);
 

Parameters

pInst

Instrument to download.

dwPChannel

PChannel to which the instrument is assigned.

ppDownInst

Address of a variable to receive a pointer to the downloaded instrument.

pNoteRanges

Array of DMUS_NOTERANGE structures. Each entry in the array specifies a contiguous range of MIDI note messages to which the instrument must respond. An instrument region will be downloaded only if at least one note in that region is specified in the DMUS_NOTERANGE structures.

dwNumNoteRanges

Number of DMUS_NOTERANGE structures in the array pointed to by pNoteRanges. If this value is set to 0, the pNoteRanges parameter is ignored and all regions and wave data for the instrument are downloaded.

ppPort

Address of a variable to receive the port to which the instrument was downloaded.

pdwGroup

Address of a variable to receive the group to which the instrument was assigned.

pdwMChannel

Address of a variable to receive the MIDI channel to which the instrument was assigned.

Return Values

If the method succeeds, the return value is S_OK.

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

Remarks

Most applications will not need to use this method, as instrument downloading is normally handled by bands. See Downloading Bands.

The method will return E_INVALIDARG if the PChannel isn't assigned to a port.

To prevent loss of resources, the instrument should be unloaded by using the IDirectMusicPort::UnloadInstrument method when it is no longer needed.

QuickInfo

  Windows NT/2000: Requires Windows 2000.
  Windows 95/98: Requires Windows 95 or later. Available as a redistributable for Windows 95.
  Header: Declared in dmusici.h.

See Also

IDirectMusicPort::DownloadInstrument, IDirectMusicPort::UnloadInstrument, Working with Instruments