File indexing completed on 2025-02-09 05:31:49
0001 /* This file is part of the KDE project 0002 Copyright (C) 2006-2007 Matthias Kretz <kretz@kde.org> 0003 0004 This library is free software; you can redistribute it and/or 0005 modify it under the terms of the GNU Lesser General Public 0006 License as published by the Free Software Foundation; either 0007 version 2.1 of the License, or (at your option) version 3, or any 0008 later version accepted by the membership of KDE e.V. (or its 0009 successor approved by the membership of KDE e.V.), Nokia Corporation 0010 (or its successors, if any) and the KDE Free Qt Foundation, which shall 0011 act as a proxy defined in Section 6 of version 3 of the license. 0012 0013 This library is distributed in the hope that it will be useful, 0014 but WITHOUT ANY WARRANTY; without even the implied warranty of 0015 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0016 Lesser General Public License for more details. 0017 0018 You should have received a copy of the GNU Lesser General Public 0019 License along with this library. If not, see <http://www.gnu.org/licenses/>. 0020 0021 */ 0022 0023 #ifndef PHONON_MEDIAOBJECTINTERFACE_H 0024 #define PHONON_MEDIAOBJECTINTERFACE_H 0025 0026 #include "mediaobject.h" 0027 #include <QObject> 0028 0029 0030 namespace Phonon 0031 { 0032 class StreamInterface; 0033 0034 /** \class MediaObjectInterface mediaobjectinterface.h phonon/MediaObjectInterface 0035 * \short Backend interface for media sources. 0036 * 0037 * The backend implementation has to provide two signals, that are not defined 0038 * in this interface: 0039 * <ul> 0040 * <li>\anchor phonon_MediaObjectInterface_stateChanged 0041 * <b>void stateChanged(\ref Phonon::State newstate, \ref Phonon::State oldstate)</b> 0042 * 0043 * Emitted when the state of the MediaObject has changed. 0044 * In case you're not interested in the old state you can also 0045 * connect to a slot that only has one State argument. 0046 * 0047 * \param newstate The state the Player is in now. 0048 * \param oldstate The state the Player was in before. 0049 * </li> 0050 * <li>\anchor phonon_MediaObjectInterface_tick 0051 * <b>void tick(qint64 time)</b> 0052 * 0053 * This signal gets emitted every tickInterval milliseconds. 0054 * 0055 * \param time The position of the media file in milliseconds. 0056 * 0057 * \see setTickInterval() 0058 * \see tickInterval() 0059 * </li> 0060 * </ul> 0061 * 0062 * \author Matthias Kretz <kretz@kde.org> 0063 * \see MediaObject 0064 */ 0065 class MediaObjectInterface 0066 { 0067 public: 0068 virtual ~MediaObjectInterface() {} 0069 0070 /** 0071 * Requests the playback to start. 0072 * 0073 * This method is only called if the state transition to \ref PlayingState is possible. 0074 * 0075 * The backend should react immediately 0076 * by either going into \ref PlayingState or \ref BufferingState if the 0077 * former is not possible. 0078 */ 0079 virtual void play() = 0; 0080 0081 /** 0082 * Requests the playback to pause. 0083 * 0084 * This method is only called if the state transition to \ref PausedState is possible. 0085 * 0086 * The backend should react as fast as possible. Go to \ref PausedState 0087 * as soon as playback is paused. 0088 */ 0089 virtual void pause() = 0; 0090 0091 /** 0092 * Requests the playback to be stopped. 0093 * 0094 * This method is only called if the state transition to \ref StoppedState is possible. 0095 * 0096 * The backend should react as fast as possible. Go to \ref StoppedState 0097 * as soon as playback is stopped. 0098 * 0099 * A subsequent call to play() will start playback at the beginning of 0100 * the media. 0101 */ 0102 virtual void stop() = 0; 0103 0104 /** 0105 * Requests the playback to be seeked to the given time. 0106 * 0107 * The backend does not have to finish seeking while in this function 0108 * (i.e. the backend does not need to block the thread until the seek is 0109 * finished; even worse it might lead to deadlocks when using a 0110 * ByteStream which gets its data from the thread this function would 0111 * block). 0112 * 0113 * As soon as the seek is done the currentTime() function and 0114 * the tick() signal will report it. 0115 * 0116 * \param milliseconds The time where playback should seek to in 0117 * milliseconds. 0118 */ 0119 virtual void seek(qint64 milliseconds) = 0; 0120 0121 /** 0122 * Return the time interval in milliseconds between two ticks. 0123 * 0124 * \returns Returns the tick interval that it was set to (might not 0125 * be the same as you asked for). 0126 */ 0127 virtual qint32 tickInterval() const = 0; 0128 /** 0129 * Change the interval the tick signal is emitted. If you set \p 0130 * interval to 0 the signal gets disabled. 0131 * 0132 * \param interval tick interval in milliseconds 0133 * 0134 * \returns Returns the tick interval that it was set to (might not 0135 * be the same as you asked for). 0136 */ 0137 virtual void setTickInterval(qint32 interval) = 0; 0138 0139 /** 0140 * Check whether the media data includes a video stream. 0141 * 0142 * \return returns \p true if the media contains video data 0143 */ 0144 virtual bool hasVideo() const = 0; 0145 /** 0146 * If the current media may be seeked returns true. 0147 * 0148 * \returns whether the current media may be seeked. 0149 */ 0150 virtual bool isSeekable() const = 0; 0151 /** 0152 * Get the current time (in milliseconds) of the file currently being played. 0153 */ 0154 virtual qint64 currentTime() const = 0; 0155 /** 0156 * Get the current state. 0157 */ 0158 virtual Phonon::State state() const = 0; 0159 0160 /** 0161 * A translated string describing the error. 0162 */ 0163 virtual QString errorString() const = 0; 0164 0165 /** 0166 * Tells your program what to do about the error. 0167 * 0168 * \see Phonon::ErrorType 0169 */ 0170 virtual Phonon::ErrorType errorType() const = 0; 0171 0172 /** 0173 * Returns the total time of the media in milliseconds. 0174 * 0175 * If the total time is not know return -1. Do not block until it is 0176 * known, instead emit the totalTimeChanged signal as soon as the total 0177 * time is known or changes. 0178 */ 0179 virtual qint64 totalTime() const = 0; 0180 0181 /** 0182 * Returns the current source. 0183 */ 0184 virtual MediaSource source() const = 0; 0185 0186 /** 0187 * Sets the current source. When this function is called the MediaObject is 0188 * expected to stop all current activity and start loading the new 0189 * source (i.e. go into LoadingState). 0190 * 0191 * It is expected that the 0192 * backend now starts preloading the media data, filling the audio 0193 * and video buffers and making all media meta data available. It 0194 * will also trigger the totalTimeChanged signal. 0195 * 0196 * If the backend does not know how to handle the source it needs to 0197 * change state to Phonon::ErrorState. Don't bother about handling KIO 0198 * URLs. It is enough to handle AbstractMediaStream sources correctly. 0199 * 0200 * \warning Keep the MediaSource object around as long as the backend 0201 * uses the AbstractMediaStream returned by the MediaSource. In case 0202 * that no other reference to the MediaSource exists and it is set to 0203 * MediaSource::autoDelete, the AbstractMediaStream is deleted when the 0204 * last MediaSource ref is deleted. 0205 */ 0206 virtual void setSource(const MediaSource &) = 0; 0207 0208 /** 0209 * Sets the next source to be used for transitions. When a next source 0210 * is set playback should continue with the new source. In that case 0211 * finished and prefinishMarkReached are not emitted. 0212 * 0213 * \param source The source to transition to (crossfade/gapless/gap). If 0214 * \p source is an invalid MediaSource object then the queue is empty 0215 * and the playback should stop normally. 0216 * 0217 * \warning Keep the MediaSource object around as long as the backend 0218 * uses the AbstractMediaStream returned by the MediaSource. In case 0219 * that no other reference to the MediaSource exists and it is set to 0220 * MediaSource::autoDelete, the AbstractMediaStream is deleted when the 0221 * last MediaSource ref is deleted. 0222 */ 0223 virtual void setNextSource(const MediaSource &source) = 0; 0224 0225 virtual qint64 remainingTime() const { return totalTime() - currentTime(); } 0226 virtual qint32 prefinishMark() const = 0; 0227 virtual void setPrefinishMark(qint32) = 0; 0228 0229 virtual qint32 transitionTime() const = 0; 0230 virtual void setTransitionTime(qint32) = 0; 0231 }; 0232 } 0233 0234 Q_DECLARE_INTERFACE(Phonon::MediaObjectInterface, "MediaObjectInterface3.phonon.kde.org") 0235 0236 0237 #endif // PHONON_MEDIAOBJECTINTERFACE_H 0238 // vim: sw=4 ts=4 tw=80