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
36class QUrl;
37class QIODevice;
38
39namespace Phonon
40{
41
42class MediaSourcePrivate;
43class 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 */
62class 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
370PHONON_EXPORT QDebug operator <<(QDebug dbg, const Phonon::MediaSource &);
371
372} // namespace Phonon
373
374
375#endif // PHONON_MEDIASOURCE_H
376

source code of phonon/phonon/mediasource.h