Microsoft DirectX 9.0

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 contained in all message types (including DMUS_PMSG itself) as the DMUS_PMSG_PART macro, which expands to the syntax shown here.

Syntax

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;

Members

dwSize

Size of the structure, in bytes. This member is initialized by IDirectMusicPerformance8::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

Flags from the DMUS_PMSGF_FLAGS or DMUS_TIME_RESOLVE_FLAGS enumeration. It 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 IDirectMusicPerformance8::PChannelInfo method. Set this value to zero for messages that are not channel-specific, such as tempo messages. To send the message to more than channel, use one of the following values.

Value	Description
DMUS_PCHANNEL_BROADCAST_AUDIOPATH	Send a copy of the message to all channels of the audiopath.
DMUS_PCHANNEL_BROADCAST_GROUPS	Send a copy of the message to each channel group in the performance. Used for messages that need to be sent only once per channel group, such as system exclusive messages.
DMUS_PCHANNEL_BROADCAST_PERFORMANCE	Send a copy of the message to all channels of the performance.
DMUS_PCHANNEL_BROADCAST_SEGMENT	Send a copy of the message to all channels of the segment.

dwVirtualTrackID

Identifier of the track. Set to zero if the message is not being sent by a track.

pTool

Address of the tool interface. Can be set by using IDirectMusicGraph8::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 IDirectMusicGraph8::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. Must be zero.

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 IDirectMusicSegment8::InsertTrack method.) For most purposes, this value can be 0xFFFFFFFF.

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.

Value	Description
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 get-parameter calls, they must call the method again to refresh their data. Tools that want to receive this message type must indicate this through a call to IDirectMusicTool8::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.

Requirements

Header: Declared in dmusici.h.

See Also

IDirectMusicPerformance8::SendPMsg