DMUS_PMSG
The DMUS_PMSG structure contains information common to all DirectMusic messages. Because C does not support inheritance, the members of this structure are included in all message types (including DMUS_PMSG itself) by the inclusion of the DMUS_PMSG_PART macro, which expands to the syntax shown here.
typedef struct DMUS_PMSG {
DWORD dwSize;
REFERENCE_TIME rtTime;
MUSIC_TIME mtTime;
DWORD dwFlags;
DWORD dwPChannel;
DWORD dwVirtualTrackID;
IDirectMusicTool* pTool;
IDirectMusicGraph* pGraph;
DWORD dwType;
DWORD dwVoiceID;
DWORD dwGroupID;
IUnknown* punkUser;
} DMUS_PMSG;
- dwSize
- Size of the structure, in bytes. This member is initialized by IDirectMusicPerformance::AllocPMsg.
- rtTime
- Reference time at which the message is to be played, modified by dwFlags. Used only if DMUS_PMSGF_REFTIME is present in dwFlags.
- mtTime
- Music time at which the message is to be played, modified by dwFlags. Used only if DMUS_PMSGF_MUSICTIME is present in dwFlags.
- dwFlags
- Various bits (see DMUS_PMSGF_FLAGS and DMUS_TIME_RESOLVE_FLAGS). Must contain DMUS_PMSGF_REFTIME or DMUS_PMSGF_MUSICTIME.
- dwPChannel
- Performance channel (). The port, channel group, and MIDI channel can be derived from this value by using the IDirectMusicPerformance::PChannelInfo method. Set this value to 0 for messages that are not channel-specific, such as tempo messages.
- dwVirtualTrackID
- Identifier of the track. Set to 0 if the message is not being sent by a track.
- pTool
- Address of the tool interface. Can be set by using IDirectMusicGraph::StampPMsg, or can be NULL if the message is not to go to tools other than the output tool.
- pGraph
- Address of the tool graph interface. Can be set by using IDirectMusicGraph::StampPMsg, or can be NULL if the message is not to go to tools other than the output tool.
- dwType
- Message type (see DMUS_PMSGT_TYPES).
- dwVoiceID
- Reserved for future use. Should be set to 0.
- dwGroupID
- Identifier of the track group or groups that the message belongs to if the message is being generated by a track. (Tracks are assigned to groups in the IDirectMusicSegment::InsertTrack method.) For most purposes, this value can be 0xFFFFFFF.
- punkUser
- Address of an IUnknown interface supplied by the application. This pointer is always released when the message is freed. If the application wants to retain the object, it should call AddRef before the message is freed. If the message does not need a COM pointer, this value should be NULL.
Remarks
The DMUS_PMSG structure is used by itself for messages containing the following values in the dwType member:
- DMUS_PMSGT_STOP
- Sending a message of this type stops the performance at the specified time.
- DMUS_PMSGT_DIRTY
- When a control segment starts or ends, all tools in the segment and performance graphs receive a message of this type, indicating that if they cache data from GetParam calls, they must call GetParam again to refresh their data. Tools that want to receive this message type must indicate this through a call to IDirectMusicTool::GetMediaTypes. Tools in the performance graph receive one copy of the message for each segment in the performance. Such tools can safely ignore the extra messages with the same time stamp.
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