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_STREAMINTERFACE_H
24#define PHONON_STREAMINTERFACE_H
25
26#include "phonon_export.h"
27#include <QtCore/QObject>
28
29QT_BEGIN_HEADER
30QT_BEGIN_NAMESPACE
31
32#ifndef QT_NO_PHONON_ABSTRACTMEDIASTREAM
33
34namespace Phonon
35{
36class StreamInterfacePrivate;
37class MediaSource;
38
39/** \class StreamInterface streaminterface.h Phonon/StreamInterface
40 * \brief Backend interface to handle media streams (AbstractMediaStream).
41 *
42 * \author Matthias Kretz <kretz@kde.org>
43 */
44class PHONON_EXPORT StreamInterface
45{
46 friend class StreamInterfacePrivate;
47 friend class AbstractMediaStreamPrivate;
48 public:
49 virtual ~StreamInterface();
50 /**
51 * Called by the application to send a chunk of (encoded) media data.
52 *
53 * It is recommended to keep the QByteArray object until the data is consumed so that no
54 * memcopy is needed.
55 */
56 virtual void writeData(const QByteArray &data) = 0;
57 /**
58 * Called when no more media data is available and writeData will not be called anymore.
59 */
60 virtual void endOfData() = 0;
61 /**
62 * Called at the start of the stream to tell how many bytes will be sent through writeData
63 * (if no seeks happen, of course). If this value is negative the stream size cannot be
64 * determined (might be a "theoretically infinite" stream - like webradio).
65 */
66 virtual void setStreamSize(qint64 newSize) = 0;
67 /**
68 * Tells whether the stream is seekable.
69 */
70 virtual void setStreamSeekable(bool s) = 0;
71
72 /**
73 * Call this function from the constructor of your StreamInterface implementation (or as
74 * soon as you get the MediaSource object). This will connect your object to the
75 * AbstractMediaStream object. Only after the connection is done will the following
76 * functions have an effect.
77 */
78 void connectToSource(const MediaSource &mediaSource);
79
80 /**
81 * Call this function to tell the AbstractMediaStream that you need more data. The data will
82 * arrive through writeData. Don't rely on writeData getting called from needData, though
83 * some AbstractMediaStream implementations might do so.
84 *
85 * Depending on the buffering you need you either treat needData as a replacement for a
86 * read call like QIODevice::read, or you start calling needData whenever your buffer
87 * reaches a certain lower threshold.
88 */
89 void needData();
90
91 /**
92 * Call this function to tell the AbstractMediaStream that you have enough data in your
93 * buffer and that it should pause calling writeData if possible.
94 */
95 void enoughData();
96
97 /**
98 * If the stream is seekable, calling this function will make the next call to writeData
99 * pass data that starts at the byte offset \p seekTo.
100 */
101 void seekStream(qint64 seekTo);
102
103 /**
104 * Resets the AbstractMediaStream. E.g. this can be useful for non-seekable streams to start
105 * over again.
106 */
107 void reset();
108
109 protected:
110 StreamInterface();
111
112 StreamInterfacePrivate *const d;
113};
114} // namespace Phonon
115
116Q_DECLARE_INTERFACE(Phonon::StreamInterface, "StreamInterface1.phonon.kde.org")
117
118#endif //QT_NO_PHONON_ABSTRACTMEDIASTREAM
119
120QT_END_NAMESPACE
121QT_END_HEADER
122
123#endif // PHONON_STREAMINTERFACE_H
124