IDirectMusicPerformance8::GetParamEx

DirectMusic

previous page next page

Microsoft DirectX 9.0 SDK Update (Summer 2004)

^{IDirectMusicPerformance8::GetParamEx}

The GetParamEx method retrieves data from a track. This method is similar to IDirectMusicPerformance8::GetParam but adds support for self-controlling segments. It is used chiefly by tools.

Syntax

HRESULT GetParamEx(
  REFGUID rguidType, 
  DWORD dwTrackID,
  DWORD dwGroupBits,
  DWORD dwIndex, 
  MUSIC_TIME mtTime,
  MUSIC_TIME* pmtNext,
  void* pParam
);

Parameters

rguidType

Reference to (C++) or address of (C) the identifier of the type of data to obtain. See Standard Track Parameters.

dwTrackID

Unique identifier of a track within the segment state from which the parameter is to be obtained. Every performance message that originates from a track carries an identifier of the track instance that generated the message. This identifier is kept in the dwVirtualTrackID member of the DMUS_PMSG part of the message structure. When this value is passed to GetParamEx, the method is able to determine whether the track is self-controlling, in which case it gets its data from another track in the same segment rather than from one in the control segment.

dwGroupBits

Group that the track is in (see Remarks). Set this value to 0xFFFFFFFF for all groups.

dwIndex

Index of the track in the group.

mtTime

Time from which to obtain the data, in performance time.

pmtNext

Address of a variable that receives the time (relative to mtTime) until which the data is valid. If this returns a value of 0, either the data is always valid, or it is not known when it might become invalid. If this information is not needed, pmtNext can be set to NULL. See Remarks.

pParam

Address of an allocated structure in which the data is to be returned. The structure must be of the appropriate kind and size for the data type identified by rguidType.

Return Values

If the method succeeds, the return value is S_OK.

If it fails, the method can return one of the error values shown in the following table.

Return code

DMUS_E_GET_UNSUPPORTED

DMUS_E_NO_MASTER_CLOCK

DMUS_E_NOT_FOUND

DMUS_E_TRACK_NOT_FOUND

E_POINTER

Remarks

Each track belongs to one or more groups, and each group is represented by a bit in dwGroupBits. For more information, see IDirectMusicSegment8::InsertTrack and Identifying the Track.

The data returned in *pParam can become invalid before the time returned in *pmtNext if another control segment is cued.

Requirements

Header: Declared in dmusici.h.

See Also

previous page start next page