Step 3: Specifying Message Types

The CEchoTool class needs to define all the IDirectMusicTool methods. But because it does not need to perform any work in Init or Flush, it simply returns E_NOTIMPL from those methods.

The following methods are used to specify what messages will get passed to the tool for processing:

• GetMsgDeliveryType specifies when messages should be passed to the tool—as soon as they are available, at the exact time they are stamped for, or just in time to be processed and put in the port buffer. These three "delivery types" are represented respectively by the DMUS_PMSGF_TOOL_IMMEDIATE, DMUS_PMSGF_TOOL_ATTIME, and DMUS_PMSGF_TOOL_QUEUE flags in the dwFlags member of the DMUS_PMSG structure.
• GetMediaTypes establishes what type of messages should be passed to the tool, based on the content of the message. CEchoTool processes only music notes and patch changes, so it will accept MIDI short messages, music note messages, and DirectMusic patch messages. These messages are identified by flags of the DMUS_PMSGT_TYPES enumerated type in the DMUS_PMSG message structure.
• GetMediaTypeArraySize returns the number of elements in the media type array.

CEchoTool implements these methods in the following sample code:

HRESULT STDMETHODCALLTYPE CEchoTool::GetMsgDeliveryType(
        DWORD* pdwDeliveryType )
{
    // This tool wants messages immediately.
    // This is the default, so returning E_NOTIMPL
    // would work. The other method is to specifically
    // set *pdwDeliveryType to the delivery type,
// DMUS_PMSGF_TOOL_IMMEDIATE, DMUS_PMSGF_TOOL_QUEUE, 
// or DMUS_PMSGF_TOOL_ATTIME.
 
    *pdwDeliveryType = DMUS_PMSGF_TOOL_IMMEDIATE;
  return S_OK;
}
 
HRESULT STDMETHODCALLTYPE CEchoTool::GetMediaTypeArraySize(
        DWORD* pdwNumElements)
{
  *pdwNumElements = 3;
  return S_OK;
}
 
HRESULT STDMETHODCALLTYPE CEchoTool::GetMediaTypes(
        DWORD** padwMediaTypes, 
        DWORD dwNumElements)
{
  if (dwNumElements == 3)
  {
    (*padwMediaTypes)[0] = DMUS_PMSGT_NOTE;
    (*padwMediaTypes)[1] = DMUS_PMSGT_MIDI;
    (*padwMediaTypes)[2] = DMUS_PMSGT_PATCH;
    return S_OK;
  }
  else
  {
    // This should never happen.
    return E_FAIL;
  }
}