Share via

IDirectMusicPerformance::DownloadInstrument

  • Article

This 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
    Address of a variable that contains the 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
    Address of an 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 is 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 a pointer to the port to which the instrument was downloaded.
  • pdwGroup
    Address of a variable to receive the group to which the instrument is assigned.
  • pdwMChannel
    Address of a variable to receive the MIDI channel to which the instrument is assigned.

Return Values

If the method succeeds, the return value is S_OK.

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

E_INVALIDARG
E_POINTER

Remarks

Most applications do not need to use this method because instrument downloading is normally handled by bands. For more information, see Downloading and Unloading Bands.

The method returns E_INVALIDARG if the PChannel is not assigned to a port.

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

Requirements

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

See Also

Working with Instruments | IDirectMusicPort::DownloadInstrument | IDirectMusicPort::UnloadInstrument | DMUS_NOTERANGE

 Last updated on Monday, April 12, 2004

© 1992-2002 Microsoft Corporation. All rights reserved.