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 | |
29 | QT_BEGIN_HEADER |
30 | QT_BEGIN_NAMESPACE |
31 | |
32 | namespace Phonon |
33 | { |
34 | class 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 | */ |
67 | class 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 | |
236 | Q_DECLARE_INTERFACE(Phonon::MediaObjectInterface, "MediaObjectInterface3.phonon.kde.org" ) |
237 | |
238 | QT_END_NAMESPACE |
239 | QT_END_HEADER |
240 | |
241 | #endif // PHONON_MEDIAOBJECTINTERFACE_H |
242 | // vim: sw=4 ts=4 tw=80 |
243 | |