-
-#include "LiveSupport/Core/Ptr.h"
-#include "LiveSupport/Core/UniqueId.h"
-#include "LiveSupport/Core/Configurable.h"
-#include "LiveSupport/Core/Playable.h"
-#include "LiveSupport/Core/PlaylistElement.h"
-
-
-namespace LiveSupport {
-namespace Core {
-
-using namespace boost::posix_time;
-
-/* ================================================================ constants */
-
-
-/* =================================================================== macros */
-
-
-/* =============================================================== data types */
-
-/**
- * A class representing playlist.
- * Playlist are containers for AudioClips, with the additional
- * information of when and how each audio clip is played inside
- * the playlist.
- *
- * This object has to be configured with an XML configuration element
- * called playlist. This may look like the following:
- *
- *
- * <playlist id="0000000000000001"
- * title="My Playlist"
- * playlength="00:18:30.000000">
- * <playlistElement> ... </playlistElement>
- * ...
- * <playlistElement> ... </playlistElement>
- * <metadata xmlns="http://mdlf.org/livesupport/elements/1.0/"
- * xmlns:ls="http://mdlf.org/livesupport/elements/1.0/"
- * xmlns:dc="http://purl.org/dc/elements/1.1/"
- * xmlns:dcterms="http://purl.org/dc/terms/"
- * xmlns:xml="http://www.w3.org/XML/1998/namespace">
- * <dc:title>File Title txt</dc:title>
- * <dcterms:extent>00:02:30.000000</dcterms:extent>
- * ...
- * </metadata>
- * </playlist>
- *
- *
- * The DTD for the above element is:
- *
- *
- * <!ELEMENT playlist (playlistElement*, metadata?) >
- * <!ATTLIST playlist id NMTOKEN #REQUIRED >
- * <!ATTLIST playlist title CDATA "" >
- * <!ATTLIST playlist playlength NMTOKEN #IMPLIED >
- *
- *
- * For detais of the playlistElement element, see the documentation
- * for the PlaylistElement class.
- *
- * The metadata element is optional. The configure() method
- * sets only those fields which had not been set previously: e.g., if we set
- * some or all fields of the Playlist in the constructor, then these fields
- * in the XML element will be ignored by configure().
- * The title attribute and the <dc:title>
- * element set the same field; if both are present, the title is set from
- * the attribute and the element is ignored..
- * The same is true for the playlength attribute and the
- * <dcterms:extent> element.
- *
- * It is required that by the end of the configure() method, the playlength
- * is set somehow (from a constructor, the attribute or the element).
- * If the title is not set by the end of the configure() method, it is then
- * set to the empty string.
- *
- * A Playlist can be of various kinds, depending on what we want to use it
- * for, and how we got it from the StorageClientInterface:
- *
- * - A playlist obtained by getPlaylist() has its
uri,
- * token and editToken fields all unset
- * (i.e., null). Such playlists contain sub-playlists which
- * are just stubs, i.e., id, title, playlength triples,
- * without actual references to its content objects.
- * - A playlist obtained by acquirePlaylist() has its
uri
- * and token fields set, but its editToken
- * field unset. These are complete Playlist objects, and their
- * sub-playlists contain references to all their sub-objects etc.
- * The sub-playlists have their uri fields set, which
- * allows them to be played by the audio player, but their
- * token field is unset, because these sub-playlists
- * are acquired and will be released recursively when the outermost
- * playlist containing them is acquired and released.
- * - A playlist obtained by editPlaylist() has its
editToken
- * field set (but uri and token unset).
- * The sub-playlists of these are also just stubs.
- *
- *
- * The playlists are stored by the storage server in the format returned by
- * the getXmlDocumentString() function:
- *
- * - The outermost <playlist> has an id attribute,
- * a list of <playlistElement> children
- * and a <metadata> child.
- * - Each <playlistElement> has an id
- * and a relativeOffset attribute,
- * either a <playlist> or an <audioClip> child,
- * and optionally a <fadeInfo> child.
- * - Each <playlist> and <audioClip> has id, title
- * and playlength attributes (and no children).
- * - Each <fadeInfo> has fadeIn and fadeOut attributes
- * (and no children).
- * - The <metadata> element contains all the metadata of
- * the outermost playlist.
- * The dc:title and dcterms:extent elements are compulsory,
- * everything else is optional.
- *
- * An example:
- *
- *
- * <playlist id="0000000000000001">
- * <playlistElement id="0000000000000101"
- * relativeOffset="00:00:00.000000">
- * <audioClip id="0000000000010001"
- * title="My Audio Clip"
- * playlength="00:02:30.000000"/>
- * <fadeInfo id="0000000000009901"
- * fadeIn="00:00:02.000000"
- * fadeOut="00:00:01.500000"/>
- * </playlistElement>
- * <playlistElement id="0000000000000102"
- * relativeOffset="00:02:30.000000">
- * <playlist id="0000000000000002"
- * title="Embedded Playlist"
- * playlength="00:18:30.000000"/>
- * </playlistElement>
- * <metadata xmlns="http://mdlf.org/livesupport/elements/1.0/"
- * xmlns:ls="http://mdlf.org/livesupport/elements/1.0/"
- * xmlns:dc="http://purl.org/dc/elements/1.1/"
- * xmlns:dcterms="http://purl.org/dc/terms/"
- * xmlns:xml="http://www.w3.org/XML/1998/namespace">
- * <dc:title>My Playlist</dc:title>
- * <dcterms:extent>00:21:00.000000</dcterms:extent>
- * ...
- * </metadata>
- * </playlist>
- *
- *
- */
-class Playlist : public Configurable,
- public Playable
-{
- private:
- /**
- * The name of the configuration XML elmenent used by Playlist.
- */
- static const std::string configElementNameStr;
-
- /**
- * The unique id of the playlist.
- */
- Ptr::Ref id;
-
- /**
- * The title of the playlist.
- */
- Ptr::Ref title;
-
- /**
- * The playling length of the playlist.
- */
- Ptr::Ref playlength;
-
- /**
- * The uri of the SMIL file generated from this playlist (if any).
- */
- Ptr::Ref uri;
-
- /**
- * The token given to this playlist by the storage server when
- * the playlist is acquired; removed when it is released.
- */
- Ptr::Ref token;
-
- /**
- * The token given to this playlist by the storage server when
- * it is opened for editing; removed when it is saved or reverted.
- */
- Ptr::Ref editToken;
-
- /**
- * A map type for storing the playlist elements associated with
- * this playlist, indexed by their relative offsets.
- */
- typedef std::multimap::Ref>
- PlaylistElementListType;
-
- /**
- * The list of playlist elements for this playlist.
- */
- Ptr::Ref elementList;
-
- /**
- * A saved copy of this playlist.
- */
- Ptr::Ref savedCopy;
-
-
- /**
- * This playlist in XML format.
- */
- Ptr::Ref xmlPlaylist;
-
- /**
- * Set the value of a metadata field in this playlist.
- *
- * @param value the new value of the metadata field.
- * @param name the name of the metadata field (without prefix)
- * @param prefix the prefix of the metadata field
- * @exception std::invalid_argument if the key is dcterms:extent,
- * but the value is not a valid ISO-8601 time
- */
- void
- setMetadata(Ptr::Ref value,
- const std::string &name, const std::string &prefix)
- throw (std::invalid_argument);
-
- /**
- * Set the total playing length of this playlist.
- *
- * @param playlength the playing length in microseconds precision.
- */
- void
- setPlaylength(Ptr::Ref playlength)
- throw ();
-
- /**
- * Set the playlength member of this audio clip.
- *
- * @param timeString the playing length in microseconds precision.
- * @exception std::invalid_argument if the argument is not
- * a valid ISO-8601 time
- */
- void
- setPlaylength(Ptr::Ref timeString)
- throw (std::invalid_argument);
-
- /**
- * A private iterator type for internal use. It is non-constant;
- * otherwise it is the same as Playlist::const_iterator.
- */
- typedef PlaylistElementListType::iterator iterator;
-
- /**
- * Get an iterator pointing to a playlist element with a given ID.
- *
- * @param playlistElementId (a pointer to) the ID of the
- * playlist element.
- * @return an iterator to the playlist element if it exists,
- * or this->end() if it does not.
- */
- iterator
- find(Ptr::Ref playlistElementId)
- throw ();
-
- /**
- * Convert a time_duration to string, in format HH:MM:SS.ssssss.
- */
- std::string
- toFixedString(Ptr::Ref time) const
- throw ()
- {
- if (time->fractional_seconds()) {
- return to_simple_string(*time);
- } else {
- return to_simple_string(*time) + ".000000";
- }
- }
-
-
- public:
- /**
- * Copy constructor.
- *
- * @param otherPlaylist the playlist to be copied
- */
- Playlist(const Playlist & otherPlaylist)
- throw ();
-
- /**
- * Default constructor.
- *
- * NOTE: this constructor creates a Playlist with a null pointer
- * for both the ID and the playlength fields! It is meant for
- * internal use only.
- *
- * If you want to create an empty Playlist, use the storage client:
- *
- * Ptr::Ref
- * storageClientFactory = StorageClientFactory::getInstance();
- * Ptr::Ref
- * storageClient = storageClientFactory->getStorageClient();
- * Ptr::Ref
- * playlist = storageClient->createPlaylist(sessionId);
- *
- *
- * @see StorageClient::StorageClientFactory
- * @see StorageClient::StorageClientInterface
- */
- Playlist(void) throw ()
- : Playable(PlaylistType)
- {
- elementList.reset(new PlaylistElementListType);
- }
-
- /**
- * Create a playlist by specifying its ID only.
- *
- * For internal use; see the note at the default constructor.
- */
- Playlist(Ptr::Ref id) throw ()
- : Playable(PlaylistType)
- {
- this->id = id;
-
- elementList.reset(new PlaylistElementListType);
- }
-
- /**
- * Create a playlist by specifying all details, except the title.
- *
- * This is used for testing purposes;
- * see the note at the default constructor.
- *
- * @param id the id of the playlist.
- * @param playlength the playing length of the playlist.
- * @param uri the location of the SMIL file representing this
- * playlist (optional)
- */
- Playlist(Ptr::Ref id,
- Ptr::Ref playlength,
- Ptr::Ref uri = Ptr::Ref())
- throw ();
-
- /**
- * Create a playlist by specifying all details.
- *
- * This is used for testing purposes;
- * see the note at the default constructor.
- *
- * @param id the id of the playlist.
- * @param title the title of the playlist.
- * @param playlength the playing length of the playlist.
- * @param uri the location of the SMIL file representing this
- * playlist (optional)
- */
- Playlist(Ptr::Ref id,
- Ptr::Ref title,
- Ptr::Ref playlength,
- Ptr::Ref uri = Ptr::Ref())
- throw ();
-
- /**
- * Convert the playlist to an XmlRpcValue (marshalling).
- *
- * @return an XmlRpcValue struct, containing a
- * field named playlist, with value of type string,
- * which contains an XML document representing the playlist.
- */
- operator XmlRpc::XmlRpcValue() const
- throw ();
-
- /**
- * Construct a playlist from an XmlRpcValue (demarshalling).
- *
- * @param xmlRpcValue an XmlRpcValue struct, containing a
- * field named playlist, with value of type string,
- * which contains an XML document, the root node of which
- * can be passed to the configure() method.
- * @exception std::invalid_argument if the argument is invalid
- */
- Playlist(XmlRpc::XmlRpcValue & xmlRpcValue)
- throw (std::invalid_argument);
-
-
- /**
- * A virtual destructor, as this class has virtual functions.
- */
- virtual
- ~Playlist(void) throw ()
- {
- }
-
-
- /**
- * Return the name of the XML element this object expects
- * to be sent to a call to configure().
- *
- * @return the name of the expected XML configuration element.
- */
- static const std::string
- getConfigElementName(void) throw ()
- {
- return configElementNameStr;
- }
-
- /**
- * Configure the object based on the XML element supplied.
- * The supplied element is expected to be of the name
- * returned by configElementName().
- *
- * @param element the XML element to configure the object from.
- * @exception std::invalid_argument if the supplied XML element
- * contains bad configuraiton information
- */
- virtual void
- configure(const xmlpp::Element & element)
- throw (std::invalid_argument);
-
- /**
- * Return the id of the playlist.
- *
- * @return the unique id of the playlist.
- */
- virtual Ptr::Ref
- getId(void) const throw ()
- {
- return id;
- }
-
-
- /**
- * Return the title of this playlist.
- *
- * @return the title.
- */
- virtual Ptr::Ref
- getTitle(void) const throw ()
- {
- return title;
- }
-
- /**
- * Set the title of this playlist.
- *
- * @param title a new title.
- */
- virtual void
- setTitle(Ptr::Ref title)
- throw ();
-
-
- /**
- * Return the total playing length for this playlist.
- *
- * @return the playing length in microseconds precision.
- */
- virtual Ptr