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
31class QByteArray;
32
33#ifndef QT_NO_PHONON_ABSTRACTMEDIASTREAM
34
35namespace Phonon
36{
37class MediaObject;
38class 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 */
101class 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

source code of phonon/phonon/abstractmediastream.h