phonon/mediaobject.h

   1 /*  This file is part of the KDE project
   2     Copyright (C) 2005 Matthias Kretz <kretz@kde.org>
   3
   4     This library is free software; you can redistribute it and/or
   5     modify it under the terms of the GNU Library General Public
   6     License version 2 as published by the Free Software Foundation.
   7
   8     This library is distributed in the hope that it will be useful,
   9     but WITHOUT ANY WARRANTY; without even the implied warranty of
  10     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11     Library General Public License for more details.
  12
  13     You should have received a copy of the GNU Library General Public License
  14     along with this library; see the file COPYING.LIB.  If not, write to
  15     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16     Boston, MA 02110-1301, USA.
  17
  18 */
  19 #ifndef Phonon_MEDIAOBJECT_H
  20 #define Phonon_MEDIAOBJECT_H
  21
  22 #include "abstractmediaproducer.h"
  23 #include <kmimetype.h>
  24 #include <kdelibs_export.h>
  25 #include "phonondefs.h"
  26
  27 class KUrl;
  28
  29 namespace Phonon
  30 {
  31         class MediaObjectPrivate;
  32
  33         /**
  34          * \short Interface for media playback of a given URL.
  35          *
  36          * This class is the most important class for most mediaplayback tasks. With
  37          * this class you open a URL, play, pause, stop, seek and get a lot of
  38          * information about the media data.
  39          *
  40          * A common usage example is the following:
  41          * \code
  42          * media = new MediaObject( this );
  43          * connect( media, SIGNAL( finished() ), SLOT( slotFinished() );
  44          * media->setUrl( KUrl("/home/username/music/filename.ogg") );
  45          * media->play();
  46          * \endcode
  47          *
  48          * \author Matthias Kretz <kretz@kde.org>
  49          */
  50         class PHONONCORE_EXPORT MediaObject : public AbstractMediaProducer
  51         {
  52                 friend class MediaQueue;
  53                 Q_OBJECT
  54                 K_DECLARE_PRIVATE( MediaObject )
  55                 PHONON_HEIR( MediaObject )
  56                 Q_PROPERTY( KUrl url READ url WRITE setUrl )
  57                 Q_PROPERTY( qint32 aboutToFinishTime READ aboutToFinishTime WRITE setAboutToFinishTime )
  58                 public:
  59                         /**
  60                          * Get the URL the MediaObject should use as media data source.
  61                          *
  62                          * \return The currently used URL to the media data
  63                          */
  64                         KUrl url() const;
  65                         /**
  66                          * Get the total time (in milliseconds) of the file currently being played.
  67                          *
  68                          * \see length
  69                          */
  70                         qint64 totalTime() const;
  71                         /**
  72                          * Get the remaining time (in milliseconds) of the file currently being played.
  73                          */
  74                         qint64 remainingTime() const;
  75
  76                         /**
  77                          * Returns the time in milliseconds the aboutToFinish signal is
  78                          * emitted before the playback finishes. Defaults to 0.
  79                          *
  80                          * \return The aboutToFinish time in milliseconds.
  81                          *
  82                          * \see setAboutToFinishTime
  83                          * \see aboutToFinish
  84                          */
  85                         qint32 aboutToFinishTime() const;
  86
  87                 public Q_SLOTS:
  88                         /**
  89                          * \reimp
  90                          */
  91                         void stop();
  92                         /**
  93                          * \reimp
  94                          */
  95                         void play();
  96
  97                         /**
  98                          * Set the URL the MediaObject should use as media data source.
  99                          *
 100                          * \param url The URL to the media data.
 101                          */
 102                         void setUrl( const KUrl& url );
 103
 104                         /**
 105                          * Sets the time in milliseconds the aboutToFinish signal is emitted
 106                          * before the playback finishes. Defaults to 0.
 107                          *
 108                          * \param newAboutToFinishTime The new aboutToFinishTime in
 109                          * milliseconds
 110                          *
 111                          * \see aboutToFinishTime
 112                          * \see aboutToFinish
 113                          */
 114                         void setAboutToFinishTime( qint32 newAboutToFinishTime );
 115
 116                 Q_SIGNALS:
 117                         /**
 118                          * Emitted when the file has finished playing on its own.
 119                          * I.e. it is not emitted if you call stop(), pause() or
 120                          * load(), but only on end-of-file or a critical error.
 121                          *
 122                          * \see aboutToFinish
 123                          */
 124                         void finished();
 125
 126                         /**
 127                          * Emitted when there are only aboutToFinishTime milliseconds left
 128                          * for playback.
 129                          *
 130                          * \param msec The remaining time until the playback finishes.
 131                          *
 132                          * \see setAboutToFinishTime
 133                          * \see aboutToFinishTime
 134                          * \see finished
 135                          */
 136                         void aboutToFinish( qint32 msec );
 137
 138                         /**
 139                          * This signal is emitted as soon as the length of the media file is
 140                          * known or has changed. For most non-local media data the length of
 141                          * the media can only be known after some time. At that time the
 142                          * totalTime function can not return useful information. You have
 143                          * to wait for this signal to know the real length.
 144                          *
 145                          * \param length The length of the media file in milliseconds.
 146                          *
 147                          * \see totalTime
 148                          */
 149                         void length( qint64 length );
 150
 151                 protected:
 152                         MediaObject( Phonon::MediaObjectPrivate& dd, QObject* parent );
 153
 154                 private:
 155                         Q_PRIVATE_SLOT( k_func(), void _k_bytestreamNeedData() )
 156                         Q_PRIVATE_SLOT( k_func(), void _k_bytestreamEnoughData() )
 157                         Q_PRIVATE_SLOT( k_func(), void _k_bytestreamData( KIO::Job*, const QByteArray& ) )
 158                         Q_PRIVATE_SLOT( k_func(), void _k_bytestreamResult( KJob* ) )
 159                         Q_PRIVATE_SLOT( k_func(), void _k_bytestreamTotalSize( KJob*, qulonglong ) )
 160                         Q_PRIVATE_SLOT( k_func(), void _k_cleanupByteStream() )
 161                         Q_PRIVATE_SLOT( k_func(), void _k_setupKioJob() )
 162                         Q_PRIVATE_SLOT( k_func(), void _k_bytestreamSeekStream(qint64) )
 163                         Q_PRIVATE_SLOT( k_func(), void _k_bytestreamFileJobOpen(KIO::Job*) )
 164                         Q_PRIVATE_SLOT( k_func(), void _k_bytestreamSeekDone(KIO::Job*, KIO::filesize_t) )
 165                         Q_PRIVATE_SLOT( k_func(), void _k_stateChanged( Phonon::State, Phonon::State ) )
 166         };
 167 } //namespace Phonon
 168
 169 // vim: sw=4 ts=4 tw=80
 170 #endif // Phonon_MEDIAOBJECT_H