IDirectMusicGraph8::StampPMsg
The 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.
Syntax
HRESULT StampPMsg(
DMUS_PMSG* pPMSG
);
Parameters
pPMSG
Address of a structure that contains the message to stamp. This structure is of a type derived from DMUS_PMSG.
Return Values
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.
Remarks
On entry, the pTool member of the DMUS_PMSG part of the message structure points to the current tool. StampPMsg uses this member to find the next tool in the graph. A value of NULL represents the first tool in the graph.
The object pointed to by the pGraph member 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 toolgraphs.
The value of 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 IDirectMusicTool8::GetMediaTypes method.
This method calls Release on the current IDirectMusicTool8 pointed to by 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 IDirectMusicTool8::GetMsgDeliveryType method. This flag determines when the message is delivered to the next tool.
Tools should not call StampPMsg until all other tasks have been performed. When audiopaths are in use, StampPMsg can have the effect of changing the value in the dwPChannel member of the message structure. A tool that uses this value cannot rely on it if StampPMsg has already been called
The implementations of this method in the segment state and performance objects always return S_OK on success. The implementation in the graph returns DMUS_S_LAST_TOOL if there is no tool other than the output tool waiting to receive the message.
Requirements
** Header:** Dmusici.h
Library: Dmime.dll, Dmimed.dll
See Also