1 | /* This file is part of the KDE project |
2 | Copyright (C) 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_ABSTRACTMEDIASTREAM_H |
24 | #define PHONON_ABSTRACTMEDIASTREAM_H |
25 | |
26 | #include "phonon_export.h" |
27 | #include "phononnamespace.h" |
28 | #include <QObject> |
29 | |
30 | |
31 | class QByteArray; |
32 | |
33 | #ifndef QT_NO_PHONON_ABSTRACTMEDIASTREAM |
34 | |
35 | namespace Phonon |
36 | { |
37 | class MediaObject; |
38 | class AbstractMediaStreamPrivate; |
39 | |
40 | /** \class AbstractMediaStream abstractmediastream.h phonon/AbstractMediaStream |
41 | * \brief Base class for custom media data streams. |
42 | * |
43 | * Implement this class to provide a custom data stream to the backend. The class supports both, the |
44 | * push and the pull model. |
45 | * |
46 | * Push: |
47 | * \code |
48 | * PushStream::PushStream(QObject *parent) |
49 | * : AbstractMediaStream(parent), m_timer(new QTimer(this)) |
50 | * { |
51 | * setStreamSize(getMediaStreamSize()); |
52 | * |
53 | * connect(m_timer, SIGNAL(timeout()), SLOT(moreData())); |
54 | * m_timer->setInterval(0); |
55 | * } |
56 | * |
57 | * void PushStream::moreData() |
58 | * { |
59 | * const QByteArray data = getMediaData(); |
60 | * if (data.isEmpty()) { |
61 | * endOfData(); |
62 | * } else { |
63 | * writeData(data); |
64 | * } |
65 | * } |
66 | * |
67 | * void PushStream::needData() |
68 | * { |
69 | * m_timer->start(); |
70 | * moreData(); |
71 | * } |
72 | * |
73 | * void PushStream::enoughData() |
74 | * { |
75 | * m_timer->stop(); |
76 | * } |
77 | * \endcode |
78 | * |
79 | * Pull: |
80 | * \code |
81 | * PullStream::PullStream(QObject *parent) |
82 | * : AbstractMediaStream(parent) |
83 | * { |
84 | * setStreamSize(getMediaStreamSize()); |
85 | * } |
86 | * |
87 | * void PullStream::needData() |
88 | * { |
89 | * const QByteArray data = getMediaData(); |
90 | * if (data.isEmpty()) { |
91 | * endOfData(); |
92 | * } else { |
93 | * writeData(data); |
94 | * } |
95 | * } |
96 | * \endcode |
97 | * |
98 | * \ingroup Playback |
99 | * \author Matthias Kretz <kretz@kde.org> |
100 | */ |
101 | class PHONON_EXPORT AbstractMediaStream : public QObject |
102 | { |
103 | Q_OBJECT |
104 | Q_DECLARE_PRIVATE(AbstractMediaStream) |
105 | friend class MediaObject; |
106 | friend class MediaObjectPrivate; |
107 | friend class StreamInterface; |
108 | public: |
109 | ~AbstractMediaStream() override; |
110 | |
111 | protected: |
112 | /** |
113 | * Constructs an AbstractMediaStream object with a \p parent. |
114 | */ |
115 | explicit AbstractMediaStream(QObject *parent = nullptr); |
116 | |
117 | /** |
118 | * Returns the stream size that was set with \ref setStreamSize. |
119 | * |
120 | * A negative value means that the length of the stream cannot be known. |
121 | * |
122 | * Defaults to \c 0. |
123 | */ |
124 | qint64 streamSize() const; |
125 | |
126 | /** |
127 | * Sets the size of the stream in number of bytes. |
128 | * |
129 | * A negative value means that the length of the stream cannot be known. |
130 | * |
131 | * Defaults to 0. |
132 | * |
133 | * This function has to be called. A backend will not call \ref needData() until the |
134 | * stream size is set. |
135 | */ |
136 | void setStreamSize(qint64); |
137 | |
138 | /** |
139 | * Returns whether your data stream is set as seekable. |
140 | * |
141 | * Defaults to \c false. |
142 | */ |
143 | bool streamSeekable() const; |
144 | |
145 | /** |
146 | * Sets whether your data stream is seekable. |
147 | * |
148 | * Defaults to \c false. |
149 | * |
150 | * If you set this to \c true you have to implement the \ref seekStream function. |
151 | */ |
152 | void setStreamSeekable(bool); |
153 | |
154 | /** |
155 | * Sends the media \p data to the backend for decoding. |
156 | * |
157 | * \warning Don't call this function before the first needData() is emitted. |
158 | */ |
159 | void writeData(const QByteArray &data); |
160 | |
161 | /** |
162 | * Tells the backend that the media data stream is at its end. |
163 | * |
164 | * \warning Don't call this function before the first needData() is emitted. |
165 | */ |
166 | void endOfData(); |
167 | |
168 | /** |
169 | * If an I/O error occurs you should call this function to make MediaObject go into |
170 | * ErrorState. |
171 | * |
172 | * \see MediaObject::errorType() |
173 | * \see MediaObject::errorString() |
174 | */ |
175 | void error(Phonon::ErrorType errorType, const QString &errorString); |
176 | |
177 | /** |
178 | * Reimplement this function to reset the stream. Subsequent calls to writeData should start |
179 | * from the first position of the data unless a seek is requested. |
180 | * |
181 | * The function is necessary for the case where a non-seekable MediaStream is |
182 | * played more than once. For a seekable stream the implementation can simply call |
183 | * \code |
184 | * seekStream(0); |
185 | * \endcode. |
186 | */ |
187 | Q_INVOKABLE virtual void reset() = 0; |
188 | |
189 | /** |
190 | * Reimplement this function to be notified when the backend needs data. |
191 | * |
192 | * When this function is called you should try to call writeData or endOfData before |
193 | * returning. |
194 | */ |
195 | Q_INVOKABLE virtual void needData() = 0; |
196 | |
197 | /** |
198 | * Reimplement this function to be notified when the backend has enough data and your stream |
199 | * object may take a break. This method is important for pushing data to the backend in |
200 | * order to not fill the backend buffer unnecessarily. |
201 | */ |
202 | Q_INVOKABLE virtual void enoughData(); |
203 | |
204 | /** |
205 | * Reimplement this function if your stream is seekable. |
206 | * |
207 | * When this function is called the next call to writeData has to be at the requested \p |
208 | * offset. |
209 | * |
210 | * \warning Do not call the parent implementation. |
211 | */ |
212 | Q_INVOKABLE virtual void seekStream(qint64 offset); |
213 | |
214 | AbstractMediaStream(AbstractMediaStreamPrivate &dd, QObject *parent); |
215 | QScopedPointer<AbstractMediaStreamPrivate> d_ptr; |
216 | }; |
217 | |
218 | } // namespace Phonon |
219 | |
220 | #endif //QT_NO_PHONON_ABSTRACTMEDIASTREAM |
221 | |
222 | |
223 | #endif // PHONON_ABSTRACTMEDIASTREAM_H |
224 | |