IDirectMusicTool::ProcessPMsg

The IDirectMusicTool::ProcessPMsg method performs the main task of the tool. It is called from inside the performance's real-time thread for all messages that match the types specified by IDirectMusicTool::GetMediaTypes.

HRESULT ProcessPMsg(
  IDirectMusicPerformance* pPerf,
  DMUS_PMSG* pPMSG
);

Parameters

pPerf

Performance that is generating messages.

pPMSG

Message to process.

Return Values

Return values are determined by the implementation. If the method succeeds, the return value can be one of the following:

If it fails, the method can return E_POINTER.

Remarks

If the method returns DMUS_S_REQUEUE, the tool wants the message to be requeued. This allows the tool to put a new time stamp and parameters on the message and requeue it, or to requeue the message with a different delivery type.

If the return value is DMUS_S_FREE, the tool wants the message freed automatically, and does not want to requeue the message.

If S_OK is returned, the tool does not want the message to be freed automatically. Perhaps the tool is holding onto the message for some reason, or has freed it itself.

Tools should not perform time-consuming activities because doing so can severely affect overall performance. Also be sure not to create a circular reference to the performance represented by pPerf. For more information, see DirectMusic Tools.

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

IDirectMusicPerformance::SendPMsg, Messages, Message Creation and Delivery