The IDirectMusicGraph::StampPMsg method stamps a message with a pointer to the next tool that is to receive it. After processing a message, a tool must call StampPMsg.
HRESULT StampPMsg(
DMUS_PMSG* pPMSG
);
If the method succeeds, the return value is S_OK or DMUS_S_LAST_TOOL. See Remarks.
If it fails, the method may return E_POINTER.
The value of pPMSG->pTool (see DMUS_PMSG) on entry equals the current tool. StampPMsg uses this member to determine the current tool in order to find the next in the graph. It will be NULL to find the first tool in the graph.
The value of pPMSG->pGraph equals the graph that contains the tool. This is stamped inside StampPMsg along with the tool itself, and may change during the message's traversal from the segment state to the performance, as there may be multiple tool graphs.
The value of pPMSG->dwType equals the media type of the message, and is also used to find the next tool. The media types supported are those returned by the IDirectMusicTool::GetMediaTypes method.
The value of pPMSG->dwPChannel is used to determine which track the tool must be capable of processing. Tracks are identified by unique numbers when a segment is authored.
This method calls Release on the current pPMSG->pTool, replaces it with the next tool in the graph, and calls AddRef on the new tool.
It also flags the message with the correct delivery type according to what type the next tool returns in its IDirectMusicTool::GetMsgDeliveryType method. This flag determines when the message is delivered to the next tool.
The implementations of this method in the DirectMusicSegmentState and DirectMusicPerformance objects always return S_OK on success. The implementation in DirectMusicGraph returns DMUS_S_LAST_TOOL if there is no tool other than the output tool waiting to receive the message.
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.