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

source code of phonon/phonon/mediaobjectinterface.h