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 | |
32 | namespace Phonon |
33 | { |
34 | class StreamInterfacePrivate; |
35 | class 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 | */ |
55 | class 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 | |
132 | Q_DECLARE_INTERFACE(Phonon::StreamInterface, "StreamInterface1.phonon.kde.org" ) |
133 | |
134 | #endif //QT_NO_PHONON_ABSTRACTMEDIASTREAM |
135 | |
136 | |
137 | #endif // PHONON_STREAMINTERFACE_H |
138 | |