MODM_CACHEDRUMPATCHES function

WINMM sends the MODM_CACHEDRUMPATCHES message to the modMessage function of a MIDI output driver to ask the driver to cache or uncache the specified drum keys. This allows the internal synthesizer drivers to load the patches that are needed by the client application.

Syntax


DWORD modMessage(
  UINT uDeviceID,
  UINT uMsg,
  DWORD_PTR dwUser,
  DWORD_PTR dwParam1,
  DWORD_PTR dwParam2
);

Parameters

uDeviceID

Specifies the ID of the target device. Device IDs are sequential with an initial value of zero and a final value equal to one less than the number of devices that the driver supports.

uMsg

WINMM sets this parameter to MODM_CACHEDRUMPATCHES when it calls modMessage to process this message.

dwUser

Use this parameter to return instance data to the driver. Drivers that support multiple clients can use this instance data to keep track of the client that is associated with the message.

dwParam1

Specifies a far pointer to a KEYARRAY array and indicates the patches that must be cached or uncached.

dwParam2

The high-order word specifies the bank of patches to which the array refers. The low-order word specifies whether the patches must be cached or uncached (when you call modMessage) according to one of the following flags:

MIDI_CACHE_ALL. All patches specified in the array must be cached. If the synthesizer cannot cache all the patches, it should not cache any. Instead, it must clear the KEYARRAY and return MMSYSERR_NOMEM.

MIDI_CACHE_BESTFIT. If the driver can cache all the patches specified in the array, it must do so. Otherwise, it must cache as many as it can and then alter the KEYARRAY to reflect what it has actually cached. The driver must return MMSYSERR_NOMEM.

MIDI_CACHE_QUERY. The array of patches in KEYARRAY must be read to determine the patches that have already been cached.

MIDI_UNCACHE. The patches that are specified in KEYARRAY must be uncached and the array must be cleared.

Return value

modMessage returns MMSYSERR_NOERROR if the MODM_CACHEDRUMPATCHES message was successfully processed. Otherwise, it returns one of the following error messages.

Return codeDescription
MMSYSERR_NOTENABLED

The driver failed to load or initialize.

MMSYSERR_NOTSUPPORTED

The function specified in the call to modMessage is not supported.

 

Remarks

Patch caching is only supported by internal synthesizer device drivers. Drivers for MIDI output ports must return an MMSYSERR_NOTSUPPORTED error for this message. Support for patch caching is optional for internal synthesizer devices. When a driver receives a MODM_GETDEVCAPS message, it must indicate support for patch caching by setting or clearing the MIDICAPS_CACHE bit in the dwSupport field of the MIDIOUTCAPS data structure.

Requirements

Version

Available in Windows XP and later Windows operating systems.

Header

Mmddk.h (include Mmddk.h, Mmsystem.h, or Windows.h)

See also

modMessage
MODM_GETDEVCAPS
MIDIOUTCAPS
KEYARRAY

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft. All rights reserved.