| Platform SDK: DirectX |
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 this method.
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 can return E_POINTER.
On entry, pPMSG->pTool (see DMUS_PMSG) points to the current tool. StampPMsg uses this member to determine the current tool to find the next tool in the graph. A value of NULL represents the first tool in the graph.
The object pointed to by pPMSG->pGraph represents the graph that contains the tool. This is stamped inside StampPMsg, along with the tool itself, and can change while the message travels from the segment state to the performance because there can 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 IDirectMusicTool pointed to by 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.