1/* This file is part of the KDE project
2 Copyright (C) 2006-2007 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 Lesser General Public
6 License as published by the Free Software Foundation; either
7 version 2.1 of the License, or (at your option) version 3, or any
8 later version accepted by the membership of KDE e.V. (or its
9 successor approved by the membership of KDE e.V.), Nokia Corporation
10 (or its successors, if any) and the KDE Free Qt Foundation, which shall
11 act as a proxy defined in Section 6 of version 3 of the license.
12
13 This library is distributed in the hope that it will be useful,
14 but WITHOUT ANY WARRANTY; without even the implied warranty of
15 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 Lesser General Public License for more details.
17
18 You should have received a copy of the GNU Lesser General Public
19 License along with this library. If not, see <http://www.gnu.org/licenses/>.
20
21*/
22
23#ifndef PHONON_MEDIAOBJECTINTERFACE_H
24#define PHONON_MEDIAOBJECTINTERFACE_H
25
26#include "mediaobject.h"
27#include <QtCore/QObject>
28
29QT_BEGIN_HEADER
30QT_BEGIN_NAMESPACE
31
32namespace Phonon
33{
34class StreamInterface;
35
36/** \class MediaObjectInterface mediaobjectinterface.h Phonon/MediaObjectInterface
37 * \short Backend interface for media sources.
38 *
39 * The backend implementation has to provide two signals, that are not defined
40 * in this interface:
41 * <ul>
42 * <li>\anchor phonon_MediaObjectInterface_stateChanged
43 * <b>void stateChanged(\ref Phonon::State newstate, \ref Phonon::State oldstate)</b>
44 *
45 * Emitted when the state of the MediaObject has changed.
46 * In case you're not interested in the old state you can also
47 * connect to a slot that only has one State argument.
48 *
49 * \param newstate The state the Player is in now.
50 * \param oldstate The state the Player was in before.
51 * </li>
52 * <li>\anchor phonon_MediaObjectInterface_tick
53 * <b>void tick(qint64 time)</b>
54 *
55 * This signal gets emitted every tickInterval milliseconds.
56 *
57 * \param time The position of the media file in milliseconds.
58 *
59 * \see setTickInterval()
60 * \see tickInterval()
61 * </li>
62 * </ul>
63 *
64 * \author Matthias Kretz <kretz@kde.org>
65 * \see MediaObject
66 */
67class MediaObjectInterface
68{
69 public:
70 virtual ~MediaObjectInterface() {}
71
72 /**
73 * Requests the playback to start.
74 *
75 * This method is only called if the state transition to \ref PlayingState is possible.
76 *
77 * The backend should react immediately
78 * by either going into \ref PlayingState or \ref BufferingState if the
79 * former is not possible.
80 */
81 virtual void play() = 0;
82
83 /**
84 * Requests the playback to pause.
85 *
86 * This method is only called if the state transition to \ref PausedState is possible.
87 *
88 * The backend should react as fast as possible. Go to \ref PausedState
89 * as soon as playback is paused.
90 */
91 virtual void pause() = 0;
92
93 /**
94 * Requests the playback to be stopped.
95 *
96 * This method is only called if the state transition to \ref StoppedState is possible.
97 *
98 * The backend should react as fast as possible. Go to \ref StoppedState
99 * as soon as playback is stopped.
100 *
101 * A subsequent call to play() will start playback at the beginning of
102 * the media.
103 */
104 virtual void stop() = 0;
105
106 /**
107 * Requests the playback to be seeked to the given time.
108 *
109 * The backend does not have to finish seeking while in this function
110 * (i.e. the backend does not need to block the thread until the seek is
111 * finished; even worse it might lead to deadlocks when using a
112 * ByteStream which gets its data from the thread this function would
113 * block).
114 *
115 * As soon as the seek is done the currentTime() function and
116 * the tick() signal will report it.
117 *
118 * \param milliseconds The time where playback should seek to in
119 * milliseconds.
120 */
121 virtual void seek(qint64 milliseconds) = 0;
122
123 /**
124 * Return the time interval in milliseconds between two ticks.
125 *
126 * \returns Returns the tick interval that it was set to (might not
127 * be the same as you asked for).
128 */
129 virtual qint32 tickInterval() const = 0;
130 /**
131 * Change the interval the tick signal is emitted. If you set \p
132 * interval to 0 the signal gets disabled.
133 *
134 * \param interval tick interval in milliseconds
135 *
136 * \returns Returns the tick interval that it was set to (might not
137 * be the same as you asked for).
138 */
139 virtual void setTickInterval(qint32 interval) = 0;
140
141 /**
142 * Check whether the media data includes a video stream.
143 *
144 * \return returns \p true if the media contains video data
145 */
146 virtual bool hasVideo() const = 0;
147 /**
148 * If the current media may be seeked returns true.
149 *
150 * \returns whether the current media may be seeked.
151 */
152 virtual bool isSeekable() const = 0;
153 /**
154 * Get the current time (in milliseconds) of the file currently being played.
155 */
156 virtual qint64 currentTime() const = 0;
157 /**
158 * Get the current state.
159 */
160 virtual Phonon::State state() const = 0;
161
162 /**
163 * A translated string describing the error.
164 */
165 virtual QString errorString() const = 0;
166
167 /**
168 * Tells your program what to do about the error.
169 *
170 * \see Phonon::ErrorType
171 */
172 virtual Phonon::ErrorType errorType() const = 0;
173
174 /**
175 * Returns the total time of the media in milliseconds.
176 *
177 * If the total time is not know return -1. Do not block until it is
178 * known, instead emit the totalTimeChanged signal as soon as the total
179 * time is known or changes.
180 */
181 virtual qint64 totalTime() const = 0;
182
183 /**
184 * Returns the current source.
185 */
186 virtual MediaSource source() const = 0;
187
188 /**
189 * Sets the current source. When this function is called the MediaObject is
190 * expected to stop all current activity and start loading the new
191 * source (i.e. go into LoadingState).
192 *
193 * It is expected that the
194 * backend now starts preloading the media data, filling the audio
195 * and video buffers and making all media meta data available. It
196 * will also trigger the totalTimeChanged signal.
197 *
198 * If the backend does not know how to handle the source it needs to
199 * change state to Phonon::ErrorState. Don't bother about handling KIO
200 * URLs. It is enough to handle AbstractMediaStream sources correctly.
201 *
202 * \warning Keep the MediaSource object around as long as the backend
203 * uses the AbstractMediaStream returned by the MediaSource. In case
204 * that no other reference to the MediaSource exists and it is set to
205 * MediaSource::autoDelete, the AbstractMediaStream is deleted when the
206 * last MediaSource ref is deleted.
207 */
208 virtual void setSource(const MediaSource &) = 0;
209
210 /**
211 * Sets the next source to be used for transitions. When a next source
212 * is set playback should continue with the new source. In that case
213 * finished and prefinishMarkReached are not emitted.
214 *
215 * \param source The source to transition to (crossfade/gapless/gap). If
216 * \p source is an invalid MediaSource object then the queue is empty
217 * and the playback should stop normally.
218 *
219 * \warning Keep the MediaSource object around as long as the backend
220 * uses the AbstractMediaStream returned by the MediaSource. In case
221 * that no other reference to the MediaSource exists and it is set to
222 * MediaSource::autoDelete, the AbstractMediaStream is deleted when the
223 * last MediaSource ref is deleted.
224 */
225 virtual void setNextSource(const MediaSource &source) = 0;
226
227 virtual qint64 remainingTime() const { return totalTime() - currentTime(); }
228 virtual qint32 prefinishMark() const = 0;
229 virtual void setPrefinishMark(qint32) = 0;
230
231 virtual qint32 transitionTime() const = 0;
232 virtual void setTransitionTime(qint32) = 0;
233};
234}
235
236Q_DECLARE_INTERFACE(Phonon::MediaObjectInterface, "MediaObjectInterface3.phonon.kde.org")
237
238QT_END_NAMESPACE
239QT_END_HEADER
240
241#endif // PHONON_MEDIAOBJECTINTERFACE_H
242// vim: sw=4 ts=4 tw=80
243