Class: TMIDI

Declaration: MIDI.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TPlayer

Inherited By:

None.

Purpose:

Convenience class for playback of MIDI files.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Derive to provide another implementation (for example, wrap a host service).

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TMIDI::TMIDI

TMIDI ()
TMIDI (TDirectory & directory, const TFileSystemEntityName & fileName, MOpenFile :: EPermissionsForMe forMe =MOpenFile :: kRead, MOpenFile :: EPermissionsForOthers forOthers =MOpenFile :: kAllowRead)
TMIDI (const TFileSystemEntity & theFile, MOpenFile :: EPermissionsForMe forMe =MOpenFile :: kRead, MOpenFile :: EPermissionsForOthers forOthers =MOpenFile :: kAllowRead)
TMIDI (const TMIDI &)

Interface Category:

API.

Purpose:

Default constructor.
Constructor.
Constructor.
Copy constructor.

Calling Context:

Called by the stream-in operators and to create an empty object.
Call this function directly.
Call this function directly.
Call this function directly.

Parameters:

Takes no parameters.
TDirectory & directory -The directory for the file.
const TFileSystemEntityName & fileName -The name for the file.
MOpenFile :: EPermissionsForMe forMe =MOpenFile :: kRead -Specifies owner permissions for the file system. The value must be MOpenFile::kReadWrite for recording.
MOpenFile :: EPermissionsForOthers forOthers =MOpenFile :: kAllowRead -Specifies non-owners' permissions for the file system.
const TFileSystemEntity & theFile -The name of the MIDI file to play or record.
MOpenFile :: EPermissionsForMe forMe =MOpenFile :: kRead -Specifies owner permissions for the file system. The value must be MOpenFile::kReadWrite for recording.
MOpenFile :: EPermissionsForOthers forOthers =MOpenFile :: kAllowRead -Specifies non-owners' permissions for the file system.
const TMIDI & -The object to copy.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kNoSequence if the MIDI can't be opened.

Concurrency:

Multithread safe.

Other Considerations:

Note: The file system entity parameter used in constructing objects of this class contains an absolute pathname. When streamed, objects will continue to reference a file on the machine of origin.

Member Function: TMIDI::~TMIDI

virtual ~ TMIDI ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::EnableChasing

virtual void EnableChasing (bool)

Interface Category:

API.

Purpose:

Sets the chasing mode.

Calling Context:

Call this function directly.

Parameters:

bool -true for on, false for off.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::IsChasingEnabled

virtual bool IsChasingEnabled () const

Interface Category:

API.

Purpose:

Determines if chasing is enabled.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if chasing is enabled, otherwise returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::SetQuantum

virtual void SetQuantum (const TTime &)

Interface Category:

API.

Purpose:

Sets the time quantum.

Calling Context:

Call this function directly.

Parameters:

const TTime & -The time quantum.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::GetQuantum

virtual void GetQuantum (TTime &) const

Interface Category:

API.

Purpose:

Gets the time quantum.

Calling Context:

Call this function directly.

Parameters:

TTime & -The time quantum.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::GetMediaComponentType

virtual const TMediaComponentType& GetMediaComponentType () const

Interface Category:

API.

Purpose:

Determines the media type and category of this player. Provides the values of TMediaType::GetMIDI for the media type and MediaComponentType::GetConveniencePlayer for the component category.

Calling Context:

Called by the Media Registry as a key into the component dictionary.

Parameters:

Takes no parameters.

Return Value:

const TMediaComponentType& -The media component type value associated with this player.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::Play

virtual void Play ()

Interface Category:

API.

Purpose:

Starts playback and returns immediately. Playback begins from the current position.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::Stop

virtual void Stop ()

Interface Category:

API.

Purpose:

Stops playback or recording immediately.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::WaitUntilComplete

virtual void WaitUntilComplete ()

Interface Category:

API.

Purpose:

Blocks the calling thread until playback or recording finishes.

Calling Context:

Play and Record return immediately, so call this to stop all processing in a thread until playback or recording stops.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::IsRecordable

virtual bool IsRecordable () const

Interface Category:

API.

Purpose:

Determines whether the current sequence can be recorded.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the current sequence can be recorded, otherwise returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::IsPlaying

virtual bool IsPlaying () const

Interface Category:

API.

Purpose:

Determines whether the player is playing.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the player is playing, otherwise returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::IsRecording

virtual bool IsRecording () const

Interface Category:

API.

Purpose:

Determines whether the player is recording.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the player is recording, otherwise returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::AdviseWillPlay

virtual void AdviseWillPlay ()

Interface Category:

API.

Purpose:

Hints to the player that you are going to call Play soon. Gives the player a chance to perform time-consuming preparation for playback (such as paging in the first few seconds of a media sequence) in advance of Play being called. You rarely need to call AdviseWillPlay.

Calling Context:

Only Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::GetPreroll

virtual void GetPreroll (TTime & preroll) const

Interface Category:

API.

Purpose:

Returns the worst case delay that occurs before playback starts. The time is relative to the real-time clock.

Calling Context:

If you want to start playing a MIDI file exactly at time x, do the following: 1) Sync the player to a clock (see SyncTo). 2) Call GetPreroll to get the preroll time. 3) Call Play at least preroll seconds in advance of time x. The player will start playing at time x.

Parameters:

TTime & preroll -The preroll time. You can pass in any TTime derived class, such as TSeconds, TMilliseconds, or TSamples.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::GetDuration

virtual void GetDuration (TTime & duration) const

Interface Category:

API.

Purpose:

Fills in the TTime with the duration of the MIDI file.

Calling Context:

Call this function directly.

Parameters:

TTime & duration -The duration. You can pass in any TTime derived class, such as TSeconds, TMilliseconds, or TSamples.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::Seek

virtual void Seek (const TTime & position)

Interface Category:

API.

Purpose:

Sets the current position in the player. Works while stopped or while playing.

Calling Context:

Call this function directly.

Parameters:

const TTime & position -The position you want to seek to. You can pass in any TTime derived class, such as TSeconds, TMilliseconds, or TSamples.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::GetPosition

virtual void GetPosition (TTime & position) const

Interface Category:

API.

Purpose:

Fills in the TTime with the current position of the player. Works at all times regardless of whether the player is stopped, playing, or recording.

Calling Context:

Call this function directly.

Parameters:

TTime & position -The current position. You can pass in any TTime derived class, such as TSeconds, TMilliseconds, or TSamples.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::IsSyncable

virtual bool IsSyncable () const

Interface Category:

API.

Purpose:

Specifies whether TMIDI implementation supports synchronization.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

bool -true if full API is supported, false if API is only partially supported.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::GetClock

virtual void GetClock (TSyncableClockSurrogate & masterClock) const

Interface Category:

API.

Purpose:

Accesses the internal clock.

Calling Context:

Call this function directly.

Parameters:

TSyncableClockSurrogate & masterClock -Filled in with the master clock.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::SyncTo

virtual void SyncTo (const TSyncableClockSurrogate & externalClock, double rate =1.0, const TTime & offset =TTime :: kZero)

Interface Category:

API.

Purpose:

Synchronizes the player to the specified clock.

Calling Context:

Call this function directly.

Parameters:

const TSyncableClockSurrogate & externalClock -The master clock to sync to.
double rate =1.0 -The player will run at this rate relative to the master clock.
const TTime & offset =TTime :: kZero -The player's clock (and current position) will be at this offset from the master clock's time.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::SyncToKeepMyTime

virtual void SyncToKeepMyTime (const TSyncableClockSurrogate & externalClock, double rate =1.0)

Interface Category:

API.

Purpose:

Synchronizes the player to the specified clock, but leaves the player's current position unchanged.

Calling Context:

Call this function directly.

Parameters:

const TSyncableClockSurrogate & externalClock -The master clock to sync to.
double rate =1.0 -The player will run at this rate relative to the master clock.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::SyncToSelf

virtual void SyncToSelf ()

Interface Category:

API.

Purpose:

Synchronizes the player to its own internal clock, as opposed to an external clock. Internal sync is the default behavior of a newly constructed TMIDI.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::AdoptSequence

virtual void AdoptSequence (TMediaSequence * sequence)

Interface Category:

API.

Purpose:

Loads a media sequence into the player. The player now owns the storage for the media sequence, so do not delete the sequence unless you get it back by calling OrphanSequence.

Calling Context:

Call this function directly.

Parameters:

TMediaSequence * sequence -The sequence to adopt.

Return Value:

None.

Exceptions:

Throws TTimeMediaException::kNoSequence if the sequence is NIL. Throws TTimeMediaException::kCannotPlaySequence if the sequence is the wrong type.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::OrphanSequence

virtual TMediaSequence * OrphanSequence ()

Interface Category:

API.

Purpose:

Ejects the media sequence from the player, returning a pointer to the sequence. The player no longer owns the storage for the sequence. It is up to the client to delete the sequence.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TMediaSequence* -The media sequence ejected from the player.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::Record

virtual void Record ()

Interface Category:

API.

Purpose:

Starts recording and returns immediately. Currently unimplemented. Call Stop to stop recording. Call WaitUntilComplete to block until recording is finished. Note that a TMIDI is either recording, stopped, or playing. It cannot record and play at the same time.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws kIsNotRecordable if the media sequence in the player is not recordable.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::AdviseWillRecord

virtual void AdviseWillRecord ()

Interface Category:

API.

Purpose:

Performs time-consuming preparation for recording.

Calling Context:

Only call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::CreateStoppedInterest

virtual TInterest * CreateStoppedInterest ()

Interface Category:

API.

Purpose:

Creates an interest in when the player stops playing.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TInterest* -The created interest.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Returns a hash value.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

long -The hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::operator==

virtual bool operator== (const TMIDI &) const

Interface Category:

API.

Purpose:

Determines equality.

Calling Context:

Call this function directly.

Parameters:

const TMIDI & -The object to compare with this object.

Return Value:

Returns true if the objects are equal.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::operator=

TMIDI & operator =(const TMIDI &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function directly.

Parameters:

const TMIDI & -The source object for the assignment.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::operator>>=

virtual TStream & operator >>=(TStream & towhere) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Call this function directly.

Parameters:

TStream & towhere -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::operator<<=

virtual TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Call this function directly.

Parameters:

TStream & fromwhere -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws TInvalidVersionError if the versions don't match.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::IsRecordEnabled

virtual bool IsRecordEnabled (const TMIDITrack &) const

Interface Category:

API.

Purpose:

Queries the status of a track.

Calling Context:

Call this function directly.

Parameters:

const TMIDITrack & -The track to check.

Return Value:

Returns true if the track is record enabled.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::EnableRecord

virtual void EnableRecord (const TMIDITrack &, bool)

Interface Category:

API.

Purpose:

Enables or disables recording on a specified track.

Calling Context:

Call this function directly.

Parameters:

const TMIDITrack & -The track to enable record.
bool -true to enable, false to disable.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::GetSequence

virtual const TMIDISequence * GetSequence () const

Interface Category:

API.

Purpose:

Accesses the sequence.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A const pointer to the player's sequence. The lifetime ends with the player.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TMIDI::GetFileEntity

virtual TFileSystemEntity GetFileEntity () const

Interface Category:

API.

Purpose:

Gets the file entity of the player's sequence.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

A TFileSystemEntity for the player's sequence. Can be invalid if the sequence has no backing file (for example, TMIDISequence vs. TStandardMIDIFile).

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.