IDirectMusicGraph::StampPMsg

  • Article

This 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
);

Parameters

  • pPMSG
    Address of a structure that contains the message to stamp. This structure is of a type derived from DMUS_PMSG. For an overview of message types, see Messages.

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, 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.

Requirements

OS Versions: Windows CE .NET 4.0 and Windows CE .NET 4.1.
Header: Dmusici.h.
Link Library: Dmusic.lib.

See Also

DirectMusic Tools | IDirectMusicTool::GetMediaTypes | IDirectMusicTool::GetMsgDeliveryType | DMUS_PMSG

 Last updated on Monday, April 12, 2004

© 1992-2002 Microsoft Corporation. All rights reserved.