added abstract Playable class, which is a common ancestor of AudioClip and

Playlist; plus some clarification in the PlaylistElement documentation

livesupport/modules/core/include/LiveSupport/Core/AudioClip.h

@@ -22,7 +22,7 @@
  
  
     Author   : $Author: fgerlits $
-    Version  : $Revision: 1.8 $
+    Version  : $Revision: 1.9 $
     Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/modules/core/include/LiveSupport/Core/AudioClip.h,v $
 
 ------------------------------------------------------------------------------*/
@@ -48,6 +48,7 @@
 #include "LiveSupport/Core/Ptr.h"
 #include "LiveSupport/Core/UniqueId.h"
 #include "LiveSupport/Core/Configurable.h"
+#include "LiveSupport/Core/Playable.h"
 
 
 namespace LiveSupport {
@@ -94,9 +95,10 @@ using namespace boost::posix_time;
  *  </code></pre>
  *
  *  @author  $Author: fgerlits $
- *  @version $Revision: 1.8 $
+ *  @version $Revision: 1.9 $
  */
-class AudioClip : public Configurable
+class AudioClip : public Configurable,
+                  public Playable
 {
     private:
         /**
@@ -190,7 +192,7 @@ class AudioClip : public Configurable
          *
          *  @return the unique id of the audio clip.
          */
-        Ptr<UniqueId>::Ref
+        virtual Ptr<UniqueId>::Ref
         getId(void) const                       throw ()
         {
             return id;
@@ -199,53 +201,57 @@ class AudioClip : public Configurable
         /**
          *  Return the total playing length for this audio clip.
          *
-         *  @return the playing length of this audio clip, in microseconds.
+         *  @return the playing length in microseconds.
          */
-        Ptr<time_duration>::Ref
+        virtual Ptr<time_duration>::Ref
         getPlaylength(void) const               throw ()
         {
             return playlength;
         }
 
         /**
-         *  Return the URI of the binary sound file of this audio clip.
+         *  Return the URI of the binary sound file of this audio clip, 
+         *  which can be played by the helix client.
          *
-         *  @return the URI of this audio clip.
+         *  @return the URI.
          */
-        Ptr<const string>::Ref
+        virtual Ptr<const string>::Ref
         getUri(void) const                      throw ()
         {
             return uri;
         }
 
         /**
-         *  Set the URI of the binary sound file of this audio clip.
+         *  Set the URI of the binary sound file of this audio clip, 
+         *  which can be played by the helix client.
          *
-         *  @return the URI of this audio clip.
+         *  @param uri the new URI.
          */
-        void
+        virtual void
         setUri(Ptr<const string>::Ref uri)      throw ()
         {
             this->uri = uri;
         }
 
         /**
-         *  Return the token returned by the storage server.
+         *  Return the token which is used to identify this audio clip
+         *  to the storage server.
          *
-         *  @return the token of this audio clip.
+         *  @return the token.
          */
-        Ptr<const string>::Ref
+        virtual Ptr<const string>::Ref
         getToken(void) const                    throw ()
         {
             return token;
         }
 
         /**
-         *  Set the token returned by the storage server.
+         *  Set the token which is used to identify this audio clip
+         *  to the storage server.
          *
-         *  @return the token of this audio clip.
+         *  @param token a new token.
          */
-        void
+        virtual void
         setToken(Ptr<const string>::Ref token)  throw ()
         {
             this->token = token;

livesupport/modules/core/include/LiveSupport/Core/Playable.h

@@ -0,0 +1,144 @@
+/*------------------------------------------------------------------------------
+
+    Copyright (c) 2004 Media Development Loan Fund
+ 
+    This file is part of the LiveSupport project.
+    http://livesupport.campware.org/
+    To report bugs, send an e-mail to bugs@campware.org
+ 
+    LiveSupport is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+  
+    LiveSupport is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+ 
+    You should have received a copy of the GNU General Public License
+    along with LiveSupport; if not, write to the Free Software
+    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ 
+ 
+    Author   : $Author: fgerlits $
+    Version  : $Revision: 1.1 $
+    Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/modules/core/include/LiveSupport/Core/Playable.h,v $
+
+------------------------------------------------------------------------------*/
+#ifndef LiveSupport_Core_Playable_h
+#define LiveSupport_Core_Playable_h
+
+#ifndef __cplusplus
+#error This is a C++ include file
+#endif
+
+
+/* ============================================================ include files */
+
+#ifdef HAVE_CONFIG_H
+#include "configure.h"
+#endif
+
+#include <stdexcept>
+#include <string>
+#include <libxml++/libxml++.h>
+#include <boost/date_time/posix_time/posix_time.hpp>
+
+#include "LiveSupport/Core/Ptr.h"
+#include "LiveSupport/Core/UniqueId.h"
+#include "LiveSupport/Core/Configurable.h"
+
+
+namespace LiveSupport {
+namespace Core {
+
+using namespace std;
+using namespace boost::posix_time;
+
+/* ================================================================ constants */
+
+
+/* =================================================================== macros */
+
+
+/* =============================================================== data types */
+
+/**
+ *  A purely abstract class which is extended by AudioClip and Playlist.
+ *  It contains the methods which are common to these classes.
+ *
+ *  @author  $Author: fgerlits $
+ *  @version $Revision: 1.1 $
+ */
+class Playable
+{
+    public:
+
+        /**
+         *  Return the id of the audio clip or playlist.
+         *
+         *  @return the unique id of the audio clip or playlist.
+         */
+        virtual Ptr<UniqueId>::Ref
+        getId(void) const                       throw () = 0;
+
+        /**
+         *  Return the total playing length for this audio clip or playlist.
+         *
+         *  @return the playing length in microseconds.
+         */
+        virtual Ptr<time_duration>::Ref
+        getPlaylength(void) const               throw () = 0;
+
+        /**
+         *  Return the URI of the sound file of this audio clip or
+         *  playlist, which can be played by the helix client.  This
+         *  sound file can be an mp3 or a SMIL file.
+         *
+         *  @return the URI.
+         */
+        virtual Ptr<const string>::Ref
+        getUri(void) const                      throw () = 0;
+
+        /**
+         *  Set the URI of the sound file of this audio clip or
+         *  playlist, which can be played by the helix client.  This
+         *  sound file can be an mp3 or a SMIL file.
+         *
+         *  @param uri the new URI.
+         */
+        virtual void
+        setUri(Ptr<const string>::Ref uri)      throw () = 0;
+
+        /**
+         *  Return the token which is used to identify this audio clip
+         *  or playlist to the storage server.
+         *
+         *  @return the token.
+         */
+        virtual Ptr<const string>::Ref
+        getToken(void) const                    throw () = 0;
+
+        /**
+         *  Set the token which is used to identify this audio clip
+         *  or playlist to the storage server.
+         *
+         *  @param token a new token.
+         */
+        virtual void
+        setToken(Ptr<const string>::Ref token)  throw () = 0;
+};
+
+
+/* ================================================= external data structures */
+
+
+/* ====================================================== function prototypes */
+
+
+} // namespace Core
+} // namespace LiveSupport
+
+#endif // LiveSupport_Core_Playable_h
+

livesupport/modules/core/include/LiveSupport/Core/Playlist.h

@@ -22,7 +22,7 @@
  
  
     Author   : $Author: fgerlits $
-    Version  : $Revision: 1.17 $
+    Version  : $Revision: 1.18 $
     Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/modules/core/include/LiveSupport/Core/Playlist.h,v $
 
 ------------------------------------------------------------------------------*/
@@ -48,6 +48,7 @@
 #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"
 
 
@@ -92,9 +93,10 @@ using namespace boost::posix_time;
  *  </code></pre>
  *
  *  @author  $Author: fgerlits $
- *  @version $Revision: 1.17 $
+ *  @version $Revision: 1.18 $
  */
-class Playlist : public Configurable
+class Playlist : public Configurable,
+                 public Playable
 {
     private:
         /**
@@ -232,8 +234,8 @@ class Playlist : public Configurable
          *
          *  @return the unique id of the playlist.
          */
-        Ptr<UniqueId>::Ref
+        virtual Ptr<UniqueId>::Ref
-        getId(void) const                        throw ()
+        getId(void) const                       throw ()
         {
             return id;
         }
@@ -241,52 +243,58 @@ class Playlist : public Configurable
         /**
          *  Return the total playing length for this playlist.
          *
-         *  @return the playling length of this playlist, in microseconds.
+         *  @return the playing length in microseconds.
          */
-        Ptr<time_duration>::Ref
+        virtual Ptr<time_duration>::Ref
-        getPlaylength(void) const                throw ()
+        getPlaylength(void) const               throw ()
         {
             return playlength;
         }
 
         /**
-         *  Return the URI of the SMIL file generated from this playlist.
+         *  Return the URI of the SMIL file created from this
+         *  playlist, which can be played by the helix client.
          *
-         *  @return the uri of the playlist.
+         *  @return the URI.
          */
-        Ptr<const std::string>::Ref
+        virtual Ptr<const string>::Ref
-        getUri(void) const                                  throw ()
+        getUri(void) const                      throw ()
         {
             return uri;
         }
 
         /**
-         *  Set the URI of the SMIL file generated from this playlist.
+         *  Set the URI of the SMIL file created from this
+         *  playlist, which can be played by the helix client.
          *
+         *  @param uri the new URI.
          */
-        void
+        virtual void
-        setUri(Ptr<const std::string>::Ref uri)             throw ()
+        setUri(Ptr<const string>::Ref uri)      throw ()
         {
             this->uri = uri;
         }
 
         /**
-         *  Return the token given to this playlist by the storage server.
+         *  Return the token which is used to identify this
+         *  playlist to the storage server.
          *
-         *  @return the uri of the playlist.
+         *  @return the token.
          */
-        Ptr<const std::string>::Ref
+        virtual Ptr<const string>::Ref
-        getToken(void) const                                throw ()
+        getToken(void) const                    throw ()
         {
             return token;
         }
 
         /**
-         *  Set the token given to this playlist by the storage server.
+         *  Set the token which is used to identify this
+         *  playlist to the storage server.
          *
+         *  @param token a new token.
          */
-        void
+        virtual void
-        setToken(Ptr<const std::string>::Ref token)         throw ()
+        setToken(Ptr<const string>::Ref token)  throw ()
         {
             this->token = token;
         }

livesupport/modules/core/include/LiveSupport/Core/PlaylistElement.h

@@ -22,7 +22,7 @@
  
  
     Author   : $Author: fgerlits $
-    Version  : $Revision: 1.8 $
+    Version  : $Revision: 1.9 $
     Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/modules/core/include/LiveSupport/Core/PlaylistElement.h,v $
 
 ------------------------------------------------------------------------------*/
@@ -49,7 +49,9 @@
 #include "LiveSupport/Core/Ptr.h"
 #include "LiveSupport/Core/UniqueId.h"
 #include "LiveSupport/Core/Configurable.h"
+#include "LiveSupport/Core/Playable.h"
 #include "LiveSupport/Core/AudioClip.h"
+#include "LiveSupport/Core/Playlist.h"
 #include "LiveSupport/Core/FadeInfo.h"
 
 
@@ -76,6 +78,10 @@ class Playlist;
  *  An item in a Playlist, consisting of an AudioClip or another Playlist
  *  and optional FadeInfo (fade in / fade out information).
  *
+ *  The contents of the playlist element can be accessed either by calling
+ *  getPlayable(), or, if a specific type of element is needed, by checking
+ *  getType() first, and then calling either getAudioClip() or getPlaylist().
+ *
  *  This object has to be configured with an XML configuration element
  *  called playlistElement. This may look like the following:
  *
@@ -98,7 +104,7 @@ class Playlist;
  *  </code></pre>
  *
  *  @author  $Author: fgerlits $
- *  @version $Revision: 1.8 $
+ *  @version $Revision: 1.9 $
  */
 class PlaylistElement : public Configurable 
 {
@@ -130,6 +136,12 @@ class PlaylistElement : public Configurable
          */
         Type                        type;
 
+        /**
+         *  The generic playable object associated with the entry.
+         *  This is either an audio clip or a playlist.
+         */
+        Ptr<Playable>::Ref          playable;
+
         /**
          *  The audio clip associated with the entry.
          */
@@ -176,6 +188,7 @@ class PlaylistElement : public Configurable
             this->id             = id;
             this->relativeOffset = relativeOffset;
             this->audioClip      = audioClip;
+            this->playable       = audioClip;
             this->fadeInfo       = fadeInfo;
         }
 
@@ -198,6 +211,7 @@ class PlaylistElement : public Configurable
             this->id             = UniqueId::generateId();
             this->relativeOffset = relativeOffset;
             this->audioClip      = audioClip;
+            this->playable       = audioClip;
             this->fadeInfo       = fadeInfo;
             this->type           = AudioClipType;
         }
@@ -221,6 +235,7 @@ class PlaylistElement : public Configurable
             this->id             = UniqueId::generateId();
             this->relativeOffset = relativeOffset;
             this->playlist       = playlist;
+            this->playable       = playlist;
             this->fadeInfo       = fadeInfo;
             this->type           = PlaylistType;
         }
@@ -281,7 +296,10 @@ class PlaylistElement : public Configurable
         }
 
         /**
-         *  Return the type of this playlist element.
+         *  Return the type of this playlist element.  If the return
+         *  value is PlaylistElement::AudioClipType (resp. PlaylistType),
+         *  the getAudioClip() (resp. getPlaylist())
+         *  method is guaranteed to return a non-zero value.
          *
          *  @return either AudioClipType or PlaylistType.
          */
@@ -291,9 +309,24 @@ class PlaylistElement : public Configurable
             return type;
         }
 
+        /**
+         *  Return the Playable instance (an AudioClip or a Playlist)
+         *  associated with the playlist element.  Use this if you don't
+         *  care which type this playlist element is, e.g., you
+         *  just want to play it in a helix client.
+         *
+         *  @return the Playable instance associated with the element.
+         */
+        Ptr<Playable>::Ref
+        getPlayable(void) const                            throw ()
+        {
+            return playable;
+        }
+
         /**
          *  Return the audio clip associated with the playlist element.
          *
+         *  @see getType()
          *  @return the audio clip associated with the element.
          */
         Ptr<AudioClip>::Ref
@@ -305,6 +338,7 @@ class PlaylistElement : public Configurable
         /**
          *  Return the sub-playlist associated with the playlist element.
          *
+         *  @see getType()
          *  @return the sub-playlist associated with the element.
          */
         Ptr<Playlist>::Ref

livesupport/modules/core/src/PlaylistElement.cxx

@@ -22,7 +22,7 @@
  
 
     Author   : $Author: fgerlits $
-    Version  : $Revision: 1.5 $
+    Version  : $Revision: 1.6 $
     Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/modules/core/src/PlaylistElement.cxx,v $
 
 ------------------------------------------------------------------------------*/
@@ -129,6 +129,7 @@ PlaylistElement :: configure(const xmlpp::Element & element)
                                 = dynamic_cast<const xmlpp::Element*> (*it);
         type = AudioClipType;
         audioClip.reset(new AudioClip);
+        playable = audioClip;
         audioClip->configure(*audioClipElement);        // may throw exception
         
         ++it;
@@ -147,6 +148,7 @@ PlaylistElement :: configure(const xmlpp::Element & element)
                                 = dynamic_cast<const xmlpp::Element*> (*it);
             type = PlaylistType;
             playlist.reset(new Playlist);
+            playable = playlist;
             playlist->configure(*playlistElement);      // may throw exception
             ++it;
             if (it != childNodes.end()) {

livesupport/modules/core/src/PlaylistElementTest.cxx

@@ -22,7 +22,7 @@
  
  
     Author   : $Author: fgerlits $
-    Version  : $Revision: 1.4 $
+    Version  : $Revision: 1.5 $
     Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/modules/core/src/PlaylistElementTest.cxx,v $
 
 ------------------------------------------------------------------------------*/
@@ -125,6 +125,11 @@ PlaylistElementTest :: firstTest(void)
         CPPUNIT_ASSERT(playlistElement->getType() 
                                         == PlaylistElement::PlaylistType);
                                         
+        // check that we can access the playlist inside the playlist element
+        //   as a Playable instance
+        CPPUNIT_ASSERT(playlistElement->getPlaylist()
+                    == playlistElement->getPlayable()); 
+
         // the playlist inside the playlist element
         CPPUNIT_ASSERT(playlistElement->getPlaylist()->getId()->getId()
                                                          == 2);
@@ -146,6 +151,11 @@ PlaylistElementTest :: firstTest(void)
         // and the audio clip inside the playlist element
         CPPUNIT_ASSERT(playlistElement->getAudioClip()->getId()->getId()
                                                          == 10003);
+
+        // check that we can access this audio clip as a Playable instance
+        CPPUNIT_ASSERT(playlistElement->getAudioClip()
+                    == playlistElement->getPlayable()); 
+
     } catch (std::invalid_argument &e) {
         std::string eMsg = "semantic error in configuration file:\n";
         eMsg += e.what();