IDirectMusicTrack::Play

The IDirectMusicTrack::Play method causes the track to play. It performs any work the track must do when the segment is played, such as creating and sending messages.

HRESULT Play(
  void* pStateData, 
  MUSIC_TIME mtStart,
  MUSIC_TIME mtEnd,
  MUSIC_TIME mtOffset
  DWORD dwFlags, 
  IDirectMusicPerformance* pPerf, 
  IDirectMusicSegmentState* pSegSt,
  DWORD dwVirtualID
);
 

Parameters

pStateData

State data pointer, from the IDirectMusicTrack::InitPlay method. The format and use of the data is specific to the track.

mtStart

Start time.

mtEnd

End time.

mtOffset

Offset to add to all messages sent to IDirectMusicPerformance::SendPMsg.

dwFlags

Flags that indicate the state of this call. See DMUS_TRACKF_FLAGS. A value of 0 indicates that this call to Play continues playback from the previous call.

pPerf

The performance used to allocate and send the message.

pSegSt

The segment state this track belongs to. The IDirectMusicSegmentState::QueryInterface method can be called to obtain an IDirectMusicGraph interface—in order to call IDirectMusicGraph::StampPMsg, for instance.

dwVirtualID

Virtual Identifier of the track. This value must be put in the dwVirtualTrackID member of any message (see DMUS_PMSG) that will be sent by IDirectMusicPerformance::SendPMsg.

Return Values

If the method succeeds, the return value may be S_OK or DMUS_S_END.

If it fails, the method may return one of the following error values:

Remarks

If the track is empty, the method returns DMUS_S_END.

Tracks generate messages in a medium-priority thread. You can call time-consuming functions, such as code to stream data from a file, from within a track's Play method. However, be sure to follow the guidelines for safe multithreading.

QuickInfo

  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.