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 | |
30 | namespace Phonon |
31 | { |
32 | class 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 | */ |
65 | class 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 | |
234 | Q_DECLARE_INTERFACE(Phonon::MediaObjectInterface, "MediaObjectInterface3.phonon.kde.org" ) |
235 | |
236 | |
237 | #endif // PHONON_MEDIAOBJECTINTERFACE_H |
238 | // vim: sw=4 ts=4 tw=80 |
239 | |