Class: TStandardMIDIFile

Declaration: MIDISequence.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TMIDISequence

Inherited By:

None.

Purpose:

Reads, writes, and creates standard MIDI files as per MMA 1.0 specification, formats 0 and 1. Transforms the file to the base class representation for use by TMIDIPlayer.

Allocate on the heap or the stack. Normally allocated on the heap so that TMIDIPlayer can adopt the file.

Deriving Classes:

Derive to handle additional file formats.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TStandardMIDIFile::TStandardMIDIFile

TStandardMIDIFile ()
TStandardMIDIFile (const TFileSystemEntity & theFile, MOpenFile :: EPermissionsForMe forMe =MOpenFile :: kRead, MOpenFile :: EPermissionsForOthers forOthers =MOpenFile :: kAllowRead)
TStandardMIDIFile (const TFileSystemEntity &, Resolution ticksPerQuarterNote, MOpenFile :: EPermissionsForMe forMe =MOpenFile :: kRead, MOpenFile :: EPermissionsForOthers forOthers =MOpenFile :: kAllowRead)
TStandardMIDIFile (const TFileSystemEntity &, Resolution framesPerSecond, Resolution ticksPerFrame, MOpenFile :: EPermissionsForMe forMe =MOpenFile :: kRead, MOpenFile :: EPermissionsForOthers forOthers =MOpenFile :: kAllowRead)
TStandardMIDIFile (const TStandardMIDIFile &)

Interface Category:

API.

Purpose:

Default constructor. Default constructors are provided only for assignment and in-streaming. Default-constructed objects are not valid and should not be copied or streamed themselves.
Constructor to open or create any MIDI file.
Constructor to create or open a metrical MIDI file.
Constructor to create or open an SMPTE MIDI file.
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.
Call this function directly.

Parameters:

Takes no parameters.
const TFileSystemEntity & theFile -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 TFileSystemEntity & theFile -The MIDI file to play or record.
Resolution ticksPerQuarterNote -The metrical specification.
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 MIDI file to play or record.
Resolution framesPerSecond -The first part of SMPTE specification.
Resolution ticksPerFrame -The second part of SMPTE specification.
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 TStandardMIDIFile & -The object to copy.

Return Value:

None.

Exceptions:

Throws TMIDIException::kEmptyFile if the file exists but has no data. Throws TMIDIException::kExpectedHeaderChunk if the file exists without a header chunk. Throws TMIDIException::kUnsupportedFileFormat if the format is not format 0 or format 1. Throws TMIDIException::kUnkownEvent if an event type is not known. Throws TMIDIException::kUnknownSMPTEFormat if the SMPTE format is not recognized.

Concurrency:

Not 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: TStandardMIDIFile::~TStandardMIDIFile

virtual ~ TStandardMIDIFile ()

Interface Category:

API.

Purpose:

Destructor. Writes the file if it's writable and SetModified has been called.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardMIDIFile::operator=

TStandardMIDIFile & operator =(const TStandardMIDIFile &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call this function directly.

Parameters:

const TStandardMIDIFile & -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:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardMIDIFile::SetModified

virtual void SetModified (bool)

Interface Category:

API.

Purpose:

Sets the status to modified such that a writable file is written upon destruction (the saveless model).

Calling Context:

Call this function directly.

Parameters:

bool -true for modified and false otherwise.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardMIDIFile::IsModified

virtual bool IsModified () const

Interface Category:

API.

Purpose:

Queries whether SetModified has been called.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the last value of the call to SetModified.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardMIDIFile::GetFileFormat

virtual EFileFormat GetFileFormat () const

Interface Category:

API.

Purpose:

Gets the file format of the standard MIDI file.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The file format.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardMIDIFile::GetNumberOfTracks

virtual TrackNumber GetNumberOfTracks () const

Interface Category:

API.

Purpose:

Gets the number of tracks in the standard MIDI file.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The number of tracks.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardMIDIFile::GetDivision

virtual Division GetDivision () const

Interface Category:

API.

Purpose:

Gets the file division of the standard MIDI file.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

The file division.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardMIDIFile::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:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardMIDIFile::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:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardMIDIFile::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

Determines a hash value for collections.

Calling Context:

Called by collections.

Parameters:

Takes no parameters.

Return Value:

The hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TStandardMIDIFile::IsEqual

virtual bool IsEqual (const MCollectible *) const

Interface Category:

API.

Purpose:

Determines if this is equal to another object.

Calling Context:

Called by collections and directly.

Parameters:

const MCollectible * -The MCollectible to be compared.

Return Value:

Returns true if the objects refer to the same file and contents.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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