IDirectMusicBand::Download

The IDirectMusicBand::Download method downloads the DLS data for instruments in the band to a performance object. The method downloads each instrument in the band by calling the IDirectMusicPerformance::DownloadInstrument method. DownloadInstrument, in turn, uses the PChannel of the instrument to find the appropriate port, and then calls the IDirectMusicPort::DownloadInstrument method on that port.

Once a band has been downloaded, the instruments in the band can be selected, either individually with program-change MIDI messages, or all at once by playing a band segment created through a call to the IDirectMusicBand::CreateSegment method.

HRESULT Download(
  IDirectMusicPerformance* pPerformance
);

Parameters

pPerformance

Performance to which instruments are to be downloaded. The performance manages the mapping of PChannels to DirectMusic ports.

Return Values

If the method succeeds, the return value is S_OK, or DMUS_S_PARTIALDOWNLOAD. (See Remarks.)

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

Remarks

Because a downloaded band uses synthesizer resources, it should be unloaded when no longer needed by using the IDirectMusicBand::Unload method.

In the current version of DirectMusic, this method may return S_OK even though the port does not support DLS.

If the download completely fails, DMUS_E_NOT_INIT is returned. This usually means that the performance was not properly connected up to an initialized port. Since this is a complete failure, there is no need to call IDirectMusicBand::Unload later.

If the download partially succeeds, DMUS_S_PARTIALDOWNLOAD is returned. This means that some of the instruments successfully downloaded while others did not. This usually occurs because of programming error setting up the performance and port. The best way to find the problem is to set debug traces to 1 for Dmime.dll, Dmband.dll, and Dmsynth.dll. (See Debugging DirectMusic Projects.)

The following are some common causes of a partial download:

• The band has instruments on PChannels that have not been set up on the performance (by using IDirectMusicPerformance::AssignPChannelBlock).
• The band has instruments on PChannels that are on channel groups not allocated on the port.
• The band has instruments in a DLS format incompatible with the synthesizer they are being downloaded to.

Requirements

  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

IDirectMusicBand::Unload