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.
- 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.
virtual ~ TMIDI ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Call this function directly.
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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:
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.
Copyright©1995 Taligent,Inc. All rights reserved.