sbIPlaylistPlayback Interface Reference

Defines standard media player playback functionality. This interface defines the interface for managing playback cores (adding selecting and removing) and for controlling the playback of media in the cores (play, stop, pause, etc). Objects wishing to control playback should get an instance of this class via Components.Classes() and call these methods on that object. More...

import "sbIPlaylistPlayback.idl";

List of all members.

Public Member Functions

void addCore (in sbICoreWrapper aCore, in boolean aSelect)
 Add a playback core. Add a playback core to the collection of cores available for media playback. If the core already exists it doesn't get added again but will be selected if aSelect is true.
void removeCore (in sbICoreWrapper aCore)
 Take a core out of the collection of available playback cores.
void selectCore (in sbICoreWrapper aCore)
 Select the core passed in as the current core. If the core passed in doesn't already exist in the collection it gets added first. Then it is selected as the current playback core.
boolean play ()
 Begin playback. If previously paused playback will start at the same position. If stopped playback will begin at the beginning of the track. Paused playback will start from the same point.
boolean pause ()
 Halt playback This maintains the position in the track and halts the playback.
boolean stop ()
 Halt playback Stops the playback of the current track. Restarting the playback after this call casuses it to start from the beginning of the track.
PRInt32 next ()
 Advance playback to the next track.
PRInt32 previous ()
 Set playback to the track before the current one in play order.
PRInt32 current ()
 Get the index of the current track.
void goFullscreen ()
 Make the playback take the full screen. This only makes sense for video playback.
boolean playRef (in AString aSourceRef, in PRInt32 aIndex)
 Play a particular track from a source.
boolean playRefByID (in AString aSourceRef, in PRInt32 aRowID)
 Play a particular track from a source.
boolean playRefByUUID (in AString aSourceRef, in AString aMediaUUID)
 Play a particular track from a source.
boolean playRefByURL (in AString aSourceRef, in AString aURL)
 Play a particular track from a source.
boolean playTable (in AString aDatabaseID, in AString aTable, in PRInt32 aIndex)
 Play a table, starting at the index provided.
boolean playTableByURL (in AString aDatabaseID, in AString aTable, in AString aURL)
 Play a table, starting at the url provided.
boolean playTableByID (in AString aDatabaseID, in AString aTable, in PRInt32 aRowID)
 Play a table, starting at the ID provided.
boolean playTableByUUID (in AString aDatabaseID, in AString aTable, in AString aMediaUUID)
 Play a table, starting at the UUID provided.
boolean playObject (in sbIPlaylist aPlaylist, in PRInt32 aIndex)
 Play an item in a playlist.
boolean playURL (in AString aURL)
 Play a piece of media directly via URL.
boolean playAndImportURL (in AString aURL)
 Add the track to the library and play it.
PRInt32 importURL (in AString aURL)
 Adds a piece of media to the library.
void getMetadataFields (out PRUint32 aFieldCount,[array, size_is(aFieldCount), retval] out wstring aMetaFields)
 Return metadata metadata. Return the number of fields supported and their identifiers.
AString getCurrentValue (in AString aField)
 Give the value of the metadata field specified.
void setCurrentValue (in AString aField, in AString aValue)
 Set the value of the metadata specified.
void getCurrentValues (in PRUint32 aFieldCount,[array, size_is(aFieldCount)] in wstring aMetaFields, out PRUint32 aValueCount,[array, size_is(aValueCount), retval] out wstring aMetaValues)
 Get the values of multiple metadata fields.
void setCurrentValues (in PRUint32 aFieldCount,[array, size_is(aFieldCount)] in wstring aMetaFields, in PRUint32 aValueCount,[array, size_is(aValueCount)] in wstring aMetaValues)
 Set the values of multiple metadata fields.
boolean isMediaURL (in AString aURL)
 Check to see if an url points to media content This checks for a number of known file extensions and prefixes to see if the URL contains them and is therefore media.
boolean isVideoURL (in AString aURL)
 Check to see if an url points to video content This checks for a number of known file extensions to see if the URL contains them and is therefore video.
boolean isPlaylistURL (in AString aURL)
 Check to see if an url points to a playlist This checks for a number of known file extensions to see if the URL contains them and is therefore a playlist.
AString stripHoursFromTimeString (in AString aTimeString)
 Removes the hours from the string passed in.
AString emitSecondsToTimeString (in AString aSeconds)
 Convert an integer into a time duration.
AString convertURLToDisplayName (in AString aURL)
 Un-Escape a URL and find the leaf name.
AString convertURLToFolder (in AString aURL)
 Unescape a URL and find the "basename".

Public Attributes

const short REPEAT_MODE_OFF = 0
 No repeat.
const short REPEAT_MODE_ONE = 1
 Repeat the current track (again and again and... ).
const short REPEAT_MODE_ALL = 2
 Play through all tracks and then do it again.
attribute sbICoreWrapper core
 The current core responsible for playback. This object is the wrapper around the actual playback engine. All calls to the playback engine go through this wrapper. This may be only one of several available playback cores, but it is the current core controlling playback.
attribute short volume
 The volume. The volume as reported by the core, or set upon the core.
attribute boolean mute
 The mute state. The mute state as reported by the core, or set upon the core.
attribute PRInt64 position
 The position within the current track. The number of milliseconds from the start of the current track as reported by or set upon the core.
readonly attribute PRInt64 length
readonly attribute boolean paused
readonly attribute boolean playing
 The playing state of the core. Seperate from pause state. A paused track is playing, a stopped track is not playing AND not paused. A.
attribute short repeat
 Repeat state. This has 3 possible states the are reflected in the constants.
attribute boolean shuffle
 Shuffle state.
readonly attribute PRInt32 itemCount
 Number of items in the current playlist. As reported by the playlistsource.
readonly attribute AString currentGUID
 The GUID for the current track in the playback core.
readonly attribute AString currentURL
 The URL for the current track in the playback core.
readonly attribute boolean started
 Has playback started. This is mainly used internally. This does not check the state of the player.


Detailed Description

Defines standard media player playback functionality. This interface defines the interface for managing playback cores (adding selecting and removing) and for controlling the playback of media in the cores (play, stop, pause, etc). Objects wishing to control playback should get an instance of this class via Components.Classes() and call these methods on that object.

See also:
sbICoreWrapper sbIPlaylist An interface that describes the PlaylistPlayback Service

Definition at line 55 of file sbIPlaylistPlayback.idl.


Member Function Documentation

void sbIPlaylistPlayback::addCore ( in sbICoreWrapper  aCore,
in boolean  aSelect 
)

Add a playback core. Add a playback core to the collection of cores available for media playback. If the core already exists it doesn't get added again but will be selected if aSelect is true.

Parameters:
aCore - The Core wrapper that interfaces with the core implementation
aSelect - A boolean to indicate if the core should be selected as the current playback core.
Returns:
void

AString sbIPlaylistPlayback::convertURLToDisplayName ( in AString  aURL  ) 

Un-Escape a URL and find the leaf name.

Parameters:
aURL - the URL to convert
Returns:
The URL passed in if it does not decode properly

The text after the last '\' or '//' in the URL

AString sbIPlaylistPlayback::convertURLToFolder ( in AString  aURL  ) 

Unescape a URL and find the "basename".

Parameters:
aURL - the URL to convert
Returns:
The URL passed in if it does not decode properly

The text before the last '\' or '//' in the URL

PRInt32 sbIPlaylistPlayback::current (  ) 

Get the index of the current track.

Exceptions:
NS_ERROR_NOT_INITIALIZED if no core has been set.
Returns:
the index of the currently playing track

AString sbIPlaylistPlayback::emitSecondsToTimeString ( in AString  aSeconds  ) 

Convert an integer into a time duration.

Parameters:
aSeconds - an integer representing the number of seconds
Returns:
A time string in the format HH:MM:SS

"Error" if hours is greater than 50

AString sbIPlaylistPlayback::getCurrentValue ( in AString  aField  ) 

Give the value of the metadata field specified.

Todo:
  • implement getCurrentValue - currently returns ""
Parameters:
aField - the metadata for which we return the value
Returns:
the value of the metadata

void sbIPlaylistPlayback::getCurrentValues ( in PRUint32  aFieldCount,
[array, size_is(aFieldCount)] in wstring  aMetaFields,
out PRUint32  aValueCount,
[array, size_is(aValueCount), retval] out wstring  aMetaValues 
)

Get the values of multiple metadata fields.

Todo:
implement getCurrentValues - currently sets out paramst to 0 and ""
Parameters:
aFieldCount - the number of metadata fields to retrieve
aMetaFields - the identifiers for the metadata fields
aValueCount - the number of metadata values returned
aMetaValues - The values of the metadata requested.
Returns:
void

void sbIPlaylistPlayback::getMetadataFields ( out PRUint32  aFieldCount,
[array, size_is(aFieldCount), retval] out wstring  aMetaFields 
)

Return metadata metadata. Return the number of fields supported and their identifiers.

Todo:
  • implement getMetadataFields, currently sets out params to 0 and ""
Parameters:
aFieldCount - the number of metadata fields supported
aMetaFields - An array of metadata identifiers.
Exceptions:
NS_ERROR_NOT_INITIALIZED if the core has not been set.
Returns:
void

void sbIPlaylistPlayback::goFullscreen (  ) 

Make the playback take the full screen. This only makes sense for video playback.

Exceptions:
NS_ERROR_NOT_INITIALIZED if no core has been set.
Returns:
true

PRInt32 sbIPlaylistPlayback::importURL ( in AString  aURL  ) 

Adds a piece of media to the library.

Parameters:
aURL - the URL of the media to add.
Returns:
the row of the media in the library.

boolean sbIPlaylistPlayback::isMediaURL ( in AString  aURL  ) 

Check to see if an url points to media content This checks for a number of known file extensions and prefixes to see if the URL contains them and is therefore media.

Parameters:
aURL - the URL to check
Returns:
true if the URL points to media content

false if the URL does not point to media content

boolean sbIPlaylistPlayback::isPlaylistURL ( in AString  aURL  ) 

Check to see if an url points to a playlist This checks for a number of known file extensions to see if the URL contains them and is therefore a playlist.

Parameters:
aURL - the URL to check
Returns:
true if the URL points to a playlist

false if the URL does not point a playlist

boolean sbIPlaylistPlayback::isVideoURL ( in AString  aURL  ) 

Check to see if an url points to video content This checks for a number of known file extensions to see if the URL contains them and is therefore video.

Parameters:
aURL - the URL to check
Returns:
true if the URL points to video content

false if the URL does not point to video content

PRInt32 sbIPlaylistPlayback::next (  ) 

Advance playback to the next track.

Exceptions:
NS_ERROR_NOT_INITIALIZED if no core has been set.
Returns:
the index of the currently playing track

boolean sbIPlaylistPlayback::pause (  ) 

Halt playback This maintains the position in the track and halts the playback.

Exceptions:
NS_ERROR_NOT_INITIALIZED if no core has been set.
Returns:
true

boolean sbIPlaylistPlayback::play (  ) 

Begin playback. If previously paused playback will start at the same position. If stopped playback will begin at the beginning of the track. Paused playback will start from the same point.

Exceptions:
NS_ERROR_NOT_INITIALIZED if no core has been set.
Returns:
true

boolean sbIPlaylistPlayback::playAndImportURL ( in AString  aURL  ) 

Add the track to the library and play it.

Parameters:
aURL - the URL to the media
Returns:
true if import and playback was successful

false if import or playback was not successful

boolean sbIPlaylistPlayback::playObject ( in sbIPlaylist  aPlaylist,
in PRInt32  aIndex 
)

Play an item in a playlist.

Parameters:
aPlaylist - a valid playlist to play from.
aIndex - the index of the track to play
Exceptions:
NS_ERROR_INVALID_ARG if the playlist or index is null or if the playlist does not have ref.
NS_ERROR_NOT_INITIALIZED if the core has not been set.
Returns:

boolean sbIPlaylistPlayback::playRef ( in AString  aSourceRef,
in PRInt32  aIndex 
)

Play a particular track from a source.

Parameters:
aSourceRef - A valid table reference in the library
aIndex - The index for the row corresponding to the track to play.
Exceptions:
NS_ERROR_INVALID_ARG if aSourceRef or aIndex is null or if aIndex is negative.
NS_ERROR_NOT_INITIALIZED if the core has not been set.
Returns:
true if playback is successful

false if playback is not successful

boolean sbIPlaylistPlayback::playRefByID ( in AString  aSourceRef,
in PRInt32  aRowID 
)

Play a particular track from a source.

Parameters:
aSourceRef - A valid table reference in the libary
aRowID - The ID for the row corresponding to the track to play.
Exceptions:
NS_ERROR_INVALID_ARG if aSourceRef or aRowID is null or if aRowID is negative.
NS_ERROR_NOT_INITIALIZED if the core has not been set.
Returns:
true if playback is successful

false if playback is not successful

boolean sbIPlaylistPlayback::playRefByURL ( in AString  aSourceRef,
in AString  aURL 
)

Play a particular track from a source.

Parameters:
aSourceRef - A valid table reference in the library
aURL - the url of the track to play
Exceptions:
NS_ERROR_INVALID_ARG if aSourceRef or aURL is empty
NS_ERROR_NOT_INITIALIZED if the core has not been set.
Returns:
true if playback is successful

false if playback is not successful

boolean sbIPlaylistPlayback::playRefByUUID ( in AString  aSourceRef,
in AString  aMediaUUID 
)

Play a particular track from a source.

Parameters:
aSourceRef - A valid table reference in the library
aMediaUUID - the UUID for the track to play
Exceptions:
NS_ERROR_INVALID_ARG if aSourceRef or aMediaUUID is null
NS_ERROR_NOT_INITIALIZED if the core has not been set.
Returns:
true if playback is successful

false if playback is not successful

boolean sbIPlaylistPlayback::playTable ( in AString  aDatabaseID,
in AString  aTable,
in PRInt32  aIndex 
)

Play a table, starting at the index provided.

Parameters:
aDatabaseID - An identifier to a database
aTable - A table in the database referenced by the id
aIndex - The index at which to start playback.
Exceptions:
NS_ERROR_INVALID_ARG if aDatabaseID or aTable is empty or if aURL isn't contained in the table.
NS_ERROR_NOT_INITIALIZED if the core has not been set.
Returns:
true if playback is successful

false if playback is not successful

boolean sbIPlaylistPlayback::playTableByID ( in AString  aDatabaseID,
in AString  aTable,
in PRInt32  aRowID 
)

Play a table, starting at the ID provided.

Parameters:
aDatabaseID - An identifier to a database
aTable - A table in the database referenced by the id
aRowID - The ID of the row at which to start playback.
Exceptions:
NS_ERROR_INVALID_ARG if aDatabaseID or aTable is empty or if aRowID isn't a valid row.
NS_ERROR_NOT_INITIALIZED if the core has not been set.
Returns:
true if playback is successful

false if playback is not successful

boolean sbIPlaylistPlayback::playTableByURL ( in AString  aDatabaseID,
in AString  aTable,
in AString  aURL 
)

Play a table, starting at the url provided.

Parameters:
aDatabaseID - An identifier to a database
aTable - A table in the database referenced by the id
aURL - The URL of the track within to the table to start playing
Exceptions:
NS_ERROR_INVALID_ARG if aDatabaseID or aTable is empty or if aURL isn't contained in the table.
NS_ERROR_NOT_INITIALIZED if the core has not been set.
Returns:
true if playback is successful

false if playback is not successful

boolean sbIPlaylistPlayback::playTableByUUID ( in AString  aDatabaseID,
in AString  aTable,
in AString  aMediaUUID 
)

Play a table, starting at the UUID provided.

Parameters:
aDatabaseID - An identifier to a database
aTable - A table in the database referenced by the id
aMediaUUID - The UUID of the row at which to start playback.
Exceptions:
NS_ERROR_INVALID_ARG if aDatabaseID or aTable is empty or if aMediaUUID isn't a valid row.
NS_ERROR_NOT_INITIALIZED if the core has not been set.
Returns:
true if playback is successful

false if playback is not successful

boolean sbIPlaylistPlayback::playURL ( in AString  aURL  ) 

Play a piece of media directly via URL.

Parameters:
aURL - the URL of the media to play.
Exceptions:
NS_ERROR_NOT_INITIALIZED if the core has not been set.
Returns:
true if playback is successfull

false if playback was not successful

PRInt32 sbIPlaylistPlayback::previous (  ) 

Set playback to the track before the current one in play order.

Exceptions:
NS_ERROR_NOT_INITIALIZED if no core has been set.
Returns:
the index of the currently playing track

void sbIPlaylistPlayback::removeCore ( in sbICoreWrapper  aCore  ) 

Take a core out of the collection of available playback cores.

Parameters:
aCore - the core to remove
Returns:
void

void sbIPlaylistPlayback::selectCore ( in sbICoreWrapper  aCore  ) 

Select the core passed in as the current core. If the core passed in doesn't already exist in the collection it gets added first. Then it is selected as the current playback core.

Parameters:
aCore - the core to add.
Returns:
void

void sbIPlaylistPlayback::setCurrentValue ( in AString  aField,
in AString  aValue 
)

Set the value of the metadata specified.

Todo:
  • implement setCurrentValue - current does nothing.
Parameters:
aField - the metadata for which to set the data
aValue - the value to set the metadata to.
Returns:
void

void sbIPlaylistPlayback::setCurrentValues ( in PRUint32  aFieldCount,
[array, size_is(aFieldCount)] in wstring  aMetaFields,
in PRUint32  aValueCount,
[array, size_is(aValueCount)] in wstring  aMetaValues 
)

Set the values of multiple metadata fields.

Todo:
implement setCurrentValues - currently does nothing.
Parameters:
aFieldCount - the number of metadata fields to set
aMetaFields - the identifiers for the metadata fields
aValueCount - the number of metadata values
aMetaValues - The values of the metadata to set.
Exceptions:
\return 

boolean sbIPlaylistPlayback::stop (  ) 

Halt playback Stops the playback of the current track. Restarting the playback after this call casuses it to start from the beginning of the track.

Exceptions:
NS_ERROR_NOT_INITIALIZED if no core has been set.
Returns:
true

AString sbIPlaylistPlayback::stripHoursFromTimeString ( in AString  aTimeString  ) 

Removes the hours from the string passed in.

Parameters:
aTimeString - a string in the format HH:MM:SS
Returns:
- The string with the HH:


Member Data Documentation

readonly attribute PRInt64 sbIPlaylistPlayback::length

/brief The length of the current track. Reported by the core.

Definition at line 110 of file sbIPlaylistPlayback.idl.

readonly attribute boolean sbIPlaylistPlayback::paused

/brief The pause state of the core. If paused, playback will continue from the current position.

See also:
playing

Definition at line 117 of file sbIPlaylistPlayback.idl.

readonly attribute boolean sbIPlaylistPlayback::playing

The playing state of the core. Seperate from pause state. A paused track is playing, a stopped track is not playing AND not paused. A.

See also:
paused

Definition at line 125 of file sbIPlaylistPlayback.idl.

attribute short sbIPlaylistPlayback::repeat

Repeat state. This has 3 possible states the are reflected in the constants.

See also:
REPEAT_MODE_NONE

REPEAT_MODE_ALL

REPEAT_MODE_ONE

Definition at line 139 of file sbIPlaylistPlayback.idl.

readonly attribute boolean sbIPlaylistPlayback::started

Has playback started. This is mainly used internally. This does not check the state of the player.

Does this really need to be exposed through an interface?

Definition at line 168 of file sbIPlaylistPlayback.idl.


The documentation for this interface was generated from the following file:
Generated on Mon Aug 21 21:01:55 2006 for Songbird by  doxygen 1.4.7