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_MEDIASOURCE_H |
24 | #define PHONON_MEDIASOURCE_H |
25 | |
26 | #include "phonon_export.h" |
27 | #include "phononnamespace.h" |
28 | |
29 | #include "mrl.h" |
30 | #include "objectdescription.h" |
31 | |
32 | #include <QSharedData> |
33 | #include <QString> |
34 | |
35 | |
36 | class QUrl; |
37 | class QIODevice; |
38 | |
39 | namespace Phonon |
40 | { |
41 | |
42 | class MediaSourcePrivate; |
43 | class AbstractMediaStream; |
44 | |
45 | /** \class MediaSource mediasource.h phonon/MediaSource |
46 | * Note that all constructors of this class are implicit, so that you can simply write |
47 | * \code |
48 | * MediaObject m; |
49 | * QString fileName("/home/foo/bar.ogg"); |
50 | * QUrl url("http://www.example.com/stream.mp3"); |
51 | * QBuffer *someBuffer; |
52 | * m.setCurrentSource(fileName); |
53 | * m.setCurrentSource(url); |
54 | * m.setCurrentSource(someBuffer); |
55 | * m.setCurrentSource(Phonon::Cd); |
56 | * \endcode |
57 | * |
58 | * \ingroup Playback |
59 | * \ingroup Recording |
60 | * \author Matthias Kretz <kretz@kde.org> |
61 | */ |
62 | class PHONON_EXPORT MediaSource |
63 | { |
64 | friend class StreamInterface; |
65 | friend PHONON_EXPORT QDebug operator <<(QDebug dbg, const Phonon::MediaSource &); |
66 | public: |
67 | /** |
68 | * Identifies the type of media described by the MediaSource object. |
69 | * |
70 | * \see MediaSource::type() |
71 | */ |
72 | enum Type { |
73 | /** |
74 | * The MediaSource object does not describe any valid source. |
75 | */ |
76 | Invalid = -1, |
77 | /** |
78 | * The MediaSource object describes a local file. |
79 | */ |
80 | LocalFile, |
81 | /** |
82 | * The MediaSource object describes a URL, which can be both a local file and a file on |
83 | * the network. |
84 | */ |
85 | Url, |
86 | /** |
87 | * The MediaSource object describes a disc. |
88 | */ |
89 | Disc, |
90 | /** |
91 | * The MediaSource object describes a data stream. |
92 | * |
93 | * This is also the type used for QIODevices. |
94 | * |
95 | * \see AbstractMediaStream |
96 | */ |
97 | Stream, |
98 | /** |
99 | * The MediaSource object describes a single capture device. |
100 | * This could be either audio or video. |
101 | */ |
102 | CaptureDevice, |
103 | /** |
104 | * An empty MediaSource. |
105 | * |
106 | * It can be used to unload the current media from a MediaObject. |
107 | * |
108 | * \see MediaSource() |
109 | */ |
110 | Empty, |
111 | /** |
112 | * The MediaSource object describes one device for video capture and one for audio |
113 | * capture. Facilitates capturing both audio and video at the same time, from |
114 | * different devices. |
115 | * It's essentially like two CaptureDevice media sources (one of video type, one |
116 | * of audio type) merged together. |
117 | */ |
118 | AudioVideoCapture |
119 | /* post 4.0: |
120 | / ** |
121 | * Links multiple MediaSource objects together. |
122 | * / |
123 | Link |
124 | */ |
125 | }; |
126 | |
127 | /** |
128 | * Creates an empty MediaSource. |
129 | * |
130 | * An empty MediaSource is considered valid and can be set on a MediaObject to unload its |
131 | * current media. |
132 | * |
133 | * \see Empty |
134 | */ |
135 | MediaSource(); |
136 | |
137 | /** |
138 | * Creates a MediaSource object for a local file or a Qt resource. |
139 | * |
140 | * \deprecated Use MediaSource(QUrl("qrc:///...")) for a Qt resource, MediaSource(QUrl::fromLocalFile("...")) for a local file, or MediaSource(QUrl("...")) for an URL. |
141 | * |
142 | * \param fileName file name of a local media file or a Qt resource that was compiled in. |
143 | */ |
144 | PHONON_DEPRECATED MediaSource(const QString &fileName); //krazy:exclude=explicit |
145 | |
146 | /** |
147 | * Creates a MediaSource object for a URL. |
148 | * |
149 | * A Qt resource can be specified by using an url with a qrc scheme. |
150 | * |
151 | * \param url URL to a media file or stream. |
152 | */ |
153 | MediaSource(const QUrl &url); //krazy:exclude=explicit |
154 | |
155 | /** |
156 | * Creates a MediaSource object for discs. |
157 | * |
158 | * \param discType See \ref DiscType |
159 | * \param deviceName A platform dependent device name. This can be useful if the computer |
160 | * has more than one CD drive. It is recommended to use Solid to retrieve the device name in |
161 | * a portable way. |
162 | */ |
163 | MediaSource(DiscType discType, const QString &deviceName = QString()); //krazy:exclude=explicit |
164 | |
165 | #ifndef PHONON_NO_AUDIOCAPTURE |
166 | /** |
167 | * Creates a MediaSource object for audio capture devices. |
168 | * If the device is valid, this creates a 'CaptureDevice' type MediaSource. |
169 | */ |
170 | MediaSource(const AudioCaptureDevice& device); |
171 | #endif |
172 | |
173 | #ifndef PHONON_NO_VIDEOCAPTURE |
174 | /** |
175 | * Creates a MediaSource object for video capture devices. |
176 | * If the device is valid, this creates a 'CaptureDevice' type MediaSource |
177 | */ |
178 | MediaSource(const VideoCaptureDevice& device); |
179 | #endif |
180 | |
181 | #if !defined(PHONON_NO_VIDEOCAPTURE) && !defined(PHONON_NO_AUDIOCAPTURE) |
182 | /** |
183 | * Sets the source to the preferred audio capture device for the specified category |
184 | * If a valid device is found, this creates a 'CaptureDevice' type MediaSource |
185 | */ |
186 | MediaSource(Capture::DeviceType deviceType, CaptureCategory category = NoCaptureCategory); |
187 | |
188 | /** |
189 | * Creates a MediaSource object that tries to describe a video capture device and |
190 | * an audio capture device, together. The devices are appropriate for the specified |
191 | * category. |
192 | * |
193 | * If valid devices are found for both audio and video, then the resulting MediaSource |
194 | * is of type 'AudioVideoCapture'. If only an audio or a video valid device is found, |
195 | * the resulting type is 'CaptureDevice'. If no valid devices are found, the resulting |
196 | * type is 'Invalid'. |
197 | */ |
198 | MediaSource(CaptureCategory category); |
199 | #endif |
200 | |
201 | #ifndef QT_NO_PHONON_ABSTRACTMEDIASTREAM |
202 | /** |
203 | * Creates a MediaSource object for a data stream. |
204 | * |
205 | * Your application can provide the media data by subclassing AbstractMediaStream and |
206 | * passing a pointer to that object. %Phonon will never delete the \p stream. |
207 | * |
208 | * \param stream The AbstractMediaStream subclass to provide the media data. |
209 | * |
210 | * \see setAutoDelete |
211 | */ |
212 | MediaSource(AbstractMediaStream *stream); //krazy:exclude=explicit |
213 | |
214 | /** |
215 | * Creates a MediaSource object for a QIODevice. |
216 | * |
217 | * This constructor can be very handy in the combination of QByteArray and QBuffer. |
218 | * |
219 | * \param ioDevice An arbitrary readable QIODevice subclass. If the device is not opened |
220 | * MediaSource will open it as QIODevice::ReadOnly. Sequential I/O devices are possible, |
221 | * too. For those MediaObject::isSeekable() will have to return false obviously. |
222 | * |
223 | * \see setAutoDelete |
224 | */ |
225 | MediaSource(QIODevice *ioDevice); //krazy:exclude=explicit |
226 | #endif |
227 | |
228 | /** |
229 | * Destroys the MediaSource object. |
230 | */ |
231 | ~MediaSource(); |
232 | |
233 | /** |
234 | * Constructs a copy of \p rhs. |
235 | * |
236 | * This constructor is fast thanks to explicit sharing. |
237 | */ |
238 | MediaSource(const MediaSource &rhs); |
239 | |
240 | /** |
241 | * Assigns \p rhs to this MediaSource and returns a reference to this MediaSource. |
242 | * |
243 | * This operation is fast thanks to explicit sharing. |
244 | */ |
245 | MediaSource &operator=(const MediaSource &rhs); |
246 | |
247 | /** |
248 | * Returns \p true if this MediaSource is equal to \p rhs; otherwise returns \p false. |
249 | */ |
250 | bool operator==(const MediaSource &rhs) const; |
251 | |
252 | /** |
253 | * Tell the MediaSource to take ownership of the AbstractMediaStream or QIODevice that was |
254 | * passed in the constructor. |
255 | * |
256 | * The default setting is \p false, for safety. If you turn it on, you should only access |
257 | * the AbstractMediaStream/QIODevice object as long as you yourself keep a MediaSource |
258 | * object around. As long as you keep the MediaSource object wrapping the stream/device |
259 | * the object will not get deleted. |
260 | * |
261 | * \see autoDelete |
262 | */ |
263 | void setAutoDelete(bool enable); |
264 | |
265 | /** |
266 | * Returns the setting of the auto-delete option. The default is \p false. |
267 | * |
268 | * \see setAutoDelete |
269 | */ |
270 | bool autoDelete() const; |
271 | |
272 | /** |
273 | * Returns the type of the MediaSource (depends on the constructor that was used). |
274 | * |
275 | * \see Type |
276 | */ |
277 | Type type() const; |
278 | |
279 | /** |
280 | * Returns the file name of the MediaSource if type() == LocalFile; otherwise returns |
281 | * QString(). |
282 | */ |
283 | QString fileName() const; |
284 | |
285 | /** |
286 | * Returns the MRL of the MediaSource if type() == URL or type() == LocalFile; otherwise |
287 | * returns Mrl(). |
288 | * Phonon::Mrl is based on QUrl and adds some additional functionality that |
289 | * is necessary to ensure proper encoding usage in the Phonon backends. |
290 | * |
291 | * Usually you will not have to use this in an application. |
292 | * |
293 | * \since 4.5 |
294 | * \ingroup Backend |
295 | */ |
296 | Mrl mrl() const; |
297 | |
298 | /** |
299 | * Returns the url of the MediaSource if type() == URL or type() == LocalFile; otherwise |
300 | * returns QUrl(). |
301 | */ |
302 | QUrl url() const; |
303 | |
304 | /** |
305 | * Returns the disc type of the MediaSource if type() == Disc; otherwise returns \ref |
306 | * NoDisc. |
307 | */ |
308 | DiscType discType() const; |
309 | |
310 | /** |
311 | * Returns the access list for the device of this media source. Valid for capture devices. |
312 | * \warning use only with MediaSource with type() == CaptureDevice |
313 | */ |
314 | const DeviceAccessList& deviceAccessList() const; |
315 | |
316 | /** |
317 | * Returns the access list for the video device used for capture. |
318 | * Valid for type() == CaptureDevice or type() == AudioVideoCapture. |
319 | * If used with CaptureDevice, the kind of device should be Video, for a valid result. |
320 | */ |
321 | const DeviceAccessList& videoDeviceAccessList() const; |
322 | |
323 | /** |
324 | * Returns the access list for the audio device used for capture. |
325 | * Valid for type() == CaptureDevice or type() == AudioVideoCapture. |
326 | * If used with CaptureDevice, the kind of device should be Audio, for a valid result. |
327 | */ |
328 | const DeviceAccessList& audioDeviceAccessList() const; |
329 | |
330 | /** |
331 | * Returns the device name of the MediaSource if type() == Disc; otherwise returns |
332 | * QString(). |
333 | */ |
334 | QString deviceName() const; |
335 | |
336 | #ifndef QT_NO_PHONON_ABSTRACTMEDIASTREAM |
337 | /** |
338 | * Returns the media stream of the MediaSource if type() == Stream; otherwise returns 0. |
339 | * QIODevices are handled as streams, too. |
340 | */ |
341 | AbstractMediaStream *stream() const; |
342 | #endif |
343 | |
344 | #ifndef PHONON_NO_AUDIOCAPTURE |
345 | /** |
346 | * Returns the audio capture device for the media source if applicable. |
347 | */ |
348 | AudioCaptureDevice audioCaptureDevice() const; |
349 | #endif |
350 | |
351 | #ifndef PHONON_NO_VIDEOCAPTURE |
352 | /** |
353 | * Returns the video capture device for the media source if applicable. |
354 | */ |
355 | VideoCaptureDevice videoCaptureDevice() const; |
356 | #endif |
357 | |
358 | /* post 4.0: |
359 | MediaSource(const QList<MediaSource> &mediaList); |
360 | QList<MediaSource> substreams() const; |
361 | */ |
362 | |
363 | protected: |
364 | QExplicitlySharedDataPointer<MediaSourcePrivate> d; |
365 | MediaSource(MediaSourcePrivate &); |
366 | |
367 | PHONON_DEPRECATED MediaSource(const DeviceAccess &access); |
368 | }; |
369 | |
370 | PHONON_EXPORT QDebug operator <<(QDebug dbg, const Phonon::MediaSource &); |
371 | |
372 | } // namespace Phonon |
373 | |
374 | |
375 | #endif // PHONON_MEDIASOURCE_H |
376 | |