Class: TPlayer

Declaration: TimeMedia.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TMediaComponent, MDelegatingNotifier

Inherited By:

TGraphicPlayer TMIDI TMIDIPlayer TMovie TSound TAudioPlayer

Purpose:

The abstract base class for all Time Media players. It defines the polymorphic interface that all players must support including protocol for playing, stopping, random access, and synchronizing playable media.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

TPlayer is derived to create players that can play particular media sequence types. Examples of TPlayers are TAudioPlayer, TGraphicPlayer, and TMIDIPlayer. Some media types take up large amounts of storage, because of this, copying a TPlayer should not create a copy of the media storage. Override IsEqual, inherited from MCollectible, as follows: Returns true if both TMediaSequence objects are equal, otherwise returns false. IsEqual should not concern itself with position, clock synchronization, or port connections. IsEqual should be true immediately after calling the Copy Constructor or operator=.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TPlayer::~TPlayer

virtual ~ TPlayer ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called by derived classes.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::GetMediaComponentType

virtual const TMediaComponentType& GetMediaComponentType () const

Interface Category:

API.

Purpose:

Determines the media type and category of this player. The base class implementation provides the default values of TMediaType::GetMedia for the media type and TMediaComponentType::GetPlayer for the component category. Deriving classes of TPlayer should override this function to provide derived class specific type information.

Calling Context:

Call directly to determine the component category. Used by TimeMediaRegistryServer and Media UI Framework.

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:

Deriving classes should declare and initialize a static TMediaComponentType in their implementations of this member function so that the constant reference remains valid.

Member Function: TPlayer::Play

virtual void Play ()

Interface Category:

API.

Purpose:

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

Calling Context:

Call directly when you want to play. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::Record

virtual void Record ()

Interface Category:

API.

Purpose:

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

Calling Context:

Call directly when you want to record. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

The default implementation throws kIsNotRecordable.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::Stop

virtual void Stop ()

Interface Category:

API.

Purpose:

Stops playback or recording immediately.

Calling Context:

Call directly to stop the player from playing or recording. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::WaitUntilComplete

virtual void WaitUntilComplete ()

Interface Category:

API.

Purpose:

Blocks the calling thread until playback or recording finishes.

Calling Context:

Call directly to block until play or record function is done.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::IsRecordable

virtual bool IsRecordable () const

Interface Category:

API.

Purpose:

Determines if the media sequence can be recorded into.

Calling Context:

Call directly to determine if the player can record. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::IsPlaying

virtual bool IsPlaying () const

Interface Category:

API.

Purpose:

Determines if the player is playing.

Calling Context:

Call directly to determine if a player is playing. Used by Media UI Framework.

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: TPlayer::IsRecording

virtual bool IsRecording () const

Interface Category:

API.

Purpose:

Determines if the player is recording.

Calling Context:

Call directly to determine whether a player is recording. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

Returns true if the player is recording, false if it is playing or stopped.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::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.

Calling Context:

Call directly only if you want to know the minimum latency between when Play is called and when the player actually starts to play. You rarely need to call AdviseWillPlay.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::AdviseWillRecord

virtual void AdviseWillRecord ()

Interface Category:

API.

Purpose:

Performs time-consuming preparation for recording.

Calling Context:

Call directly only if you want to know the minimal latency between when Record is called and when recording actually starts. You rarely need to call this.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

The default implementation throws kIsNotRecordable.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::GetPreroll

virtual void GetPreroll (TTime & preroll) const

Interface Category:

API.

Purpose:

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

Calling Context:

Call directly. If you want to start a player 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 TSeconds, TMilliseconds, TSamples, or any TTime derived class.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::GetDuration

virtual void GetDuration (TTime & duration) const

Interface Category:

API.

Purpose:

Fills in the TTime with the length of the player's media sequence.

Calling Context:

Call directly to determine how long a player's media sequence is. Used by Media UI Framework.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::Seek

virtual void Seek (const TTime & position)

Interface Category:

API.

Purpose:

Sets the current position in the player.

Calling Context:

Call directly to jump to specific point in the player's media sequence. Works while stopped or while playing. Used by Media UI Framework.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::GetPosition

virtual void GetPosition (TTime & position) const

Interface Category:

API.

Purpose:

Fills in the TTime with the current position of the player's media sequence.

Calling Context:

Call directly to determine the current position of the player's media sequence. Works at all times regardless of whether the player is stopped, playing, or recording. Used by Media UI Framework.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::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 directly if you've created a player sequence and want this player to play it. Used by Media UI Framework.

Parameters:

TMediaSequence * sequence -The media sequence to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::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 you to delete the sequence.

Calling Context:

Call directly to remove the media sequence from the player. Used by Media UI Framework.

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: TPlayer::GetClock

virtual void GetClock (TSyncableClockSurrogate & internalClock) const

Interface Category:

API.

Purpose:

Returns a clock surrogate that is synced to the player's internal clock. You can synchronize another TPlayer to this player using this clock.

Calling Context:

Call directly when you want the player to be a master clock in a master/slave clock. Used by Media UI Framework.

Parameters:

TSyncableClockSurrogate & internalClock -The surrogate for the player's clock.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::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 directly to synchronize the player to an external clock. Used by Media UI Framework.

Parameters:

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

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::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 directly when you want to synchronize the player to an external clock, but want the player clock's time (and hence the player's current position) to be unchanged. Used by Media UI Framework.

Parameters:

const TSyncableClockSurrogate & externalClock -The external clock to sync to.
double rate =1.0 -The player's rate relative to the external clock.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::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 TPlayer.

Calling Context:

Call directly when you no longer want the player to be synchronized to an external clock. It undoes the effect of SyncTo or SyncToKeepMyTime. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::CreateStoppedInterest

virtual TInterest * CreateStoppedInterest ()

Interface Category:

API.

Purpose:

Creates a TInterest that can be used to get notification when the player stops playing or recording.

Calling Context:

Call directly to get notification when a player stops. Used by Media UI Framework.

Parameters:

Takes no parameters.

Return Value:

TInterest * -An interest that you can pass into a notification connection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::operator<<=

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

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called by derived classes. Used by ::Resurrect for polymorphic streaming.

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: TPlayer::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called by derived classes. Used by ::Flatten for polymorphic streaming.

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: TPlayer::Hash

virtual long Hash () const

Interface Category:

API.

Purpose:

For use in collections.

Calling Context:

Called by collection.

Parameters:

Takes no parameters.

Return Value:

The hash value.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::TPlayer

TPlayer ()
TPlayer (const TPlayer &)

Interface Category:

API.

Purpose:

Default constructor.
Copy constructor.

Calling Context:

Protected -called by a derived class.
Protected -called by a derived class.

Parameters:

Takes no parameters.
const TPlayer & -The player to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::GetNotifier

virtual MNotifier * GetNotifier () const

Interface Category:

API.

Purpose:

Obtains the notifier used for stopped notification.

Calling Context:

Called by Notification Framework.

Parameters:

Takes no parameters.

Return Value:

MNotifier * -The notifier used for stopped notification.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::NotifyOfStopped

virtual void NotifyOfStopped ()

Interface Category:

API.

Purpose:

Called by derived classes of TPlayer to send notification that they have stopped playing or recording.

Calling Context:

Called by a TPlayer derived class that has stopped playing or recording.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TPlayer::operator=

TPlayer & operator =(const TPlayer &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Call directly when an object is assigned to another compatible object.

Parameters:

const TPlayer & -The object to be assigned.

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.

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