1/*
2 Copyright (C) 2007 Matthias Kretz <kretz@kde.org>
3 Copyright (C) 2011 Harald Sitter <sitter@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) version 3, or any
9 later version accepted by the membership of KDE e.V. (or its
10 successor approved by the membership of KDE e.V.), Nokia Corporation
11 (or its successors, if any) and the KDE Free Qt Foundation, which shall
12 act as a proxy defined in Section 6 of version 3 of the license.
13
14 This library is distributed in the hope that it will be useful,
15 but WITHOUT ANY WARRANTY; without even the implied warranty of
16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
17 Lesser General Public License for more details.
18
19 You should have received a copy of the GNU Lesser General Public
20 License along with this library. If not, see <http://www.gnu.org/licenses/>.
21*/
22
23#ifndef PHONON_STREAMINTERFACE_H
24#define PHONON_STREAMINTERFACE_H
25
26#include "phonon_export.h"
27#include <QObject>
28
29
30#ifndef QT_NO_PHONON_ABSTRACTMEDIASTREAM
31
32namespace Phonon
33{
34class StreamInterfacePrivate;
35class MediaSource;
36
37/** \class StreamInterface streaminterface.h phonon/StreamInterface
38 * \brief Backend interface to handle media streams (AbstractMediaStream).
39 *
40 * All functions relay their calls to the AbstractMediaStream using invokeMethod on the
41 * AbstractMediaStream's QMetaObject. This means that every function call will
42 * actually be executed in the thread context of the AbstractMediaStream (which
43 * usually is a thread Phonon also lives in, could however also be another one).
44 * This protectes the AbstractMediaStream against calls from different threads,
45 * such as a callback thread.
46 * This is very important as most IO implementations are by default not
47 * thread-safe.
48 *
49 * This protection is only established in one direction though, meaning that a
50 * backend implementation of this interface must be made thread-safe at all costs
51 * as it can get called from any thread.
52 *
53 * \author Matthias Kretz <kretz@kde.org>
54 */
55class PHONON_EXPORT StreamInterface
56{
57 friend class StreamInterfacePrivate;
58 friend class AbstractMediaStreamPrivate;
59 public:
60 virtual ~StreamInterface();
61
62 /**
63 * Called by the application to send a chunk of (encoded) media data.
64 *
65 * It is recommended to keep the QByteArray object until the data is consumed so that no
66 * memcopy is needed.
67 */
68 virtual void writeData(const QByteArray &data) = 0;
69
70 /**
71 * Called when no more media data is available and writeData will not be called anymore.
72 */
73 virtual void endOfData() = 0;
74
75 /**
76 * Called at the start of the stream to tell how many bytes will be sent through writeData
77 * (if no seeks happen, of course). If this value is negative the stream size cannot be
78 * determined (might be a "theoretically infinite" stream - like webradio).
79 */
80 virtual void setStreamSize(qint64 newSize) = 0;
81
82 /**
83 * Tells whether the stream is seekable.
84 */
85 virtual void setStreamSeekable(bool s) = 0;
86
87 /**
88 * Call this function from the constructor of your StreamInterface implementation (or as
89 * soon as you get the MediaSource object). This will connect your object to the
90 * AbstractMediaStream object. Only after the connection is done will the following
91 * functions have an effect.
92 */
93 void connectToSource(const MediaSource &mediaSource);
94
95 /**
96 * Call this function to tell the AbstractMediaStream that you need more data. The data will
97 * arrive through writeData.
98 * writeData() will not be called from needData() due to the thread protection of
99 * the AbstractMediaStream.
100 *
101 * Depending on the buffering you need you either treat needData as a replacement for a
102 * read call like QIODevice::read, or you start calling needData whenever your buffer
103 * reaches a certain lower threshold.
104 */
105 void needData();
106
107 /**
108 * Call this function to tell the AbstractMediaStream that you have enough data in your
109 * buffer and that it should pause calling writeData if possible.
110 */
111 void enoughData();
112
113 /**
114 * If the stream is seekable, calling this function will make the next call to writeData
115 * pass data that starts at the byte offset \p seekTo.
116 */
117 void seekStream(qint64 seekTo);
118
119 /**
120 * Resets the AbstractMediaStream. E.g. this can be useful for non-seekable streams to start
121 * over again.
122 */
123 void reset();
124
125 protected:
126 StreamInterface();
127
128 StreamInterfacePrivate *const d;
129};
130} // namespace Phonon
131
132Q_DECLARE_INTERFACE(Phonon::StreamInterface, "StreamInterface1.phonon.kde.org")
133
134#endif //QT_NO_PHONON_ABSTRACTMEDIASTREAM
135
136
137#endif // PHONON_STREAMINTERFACE_H
138

source code of phonon/phonon/streaminterface.h