Phonon

mediasource.h
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 */
81 /**
82 * The MediaSource object describes a URL, which can be both a local file and a file on
83 * the network.
84 */
86 /**
87 * The MediaSource object describes a disc.
88 */
90 /**
91 * The MediaSource object describes a data stream.
92 *
93 * This is also the type used for QIODevices.
94 *
95 * \see AbstractMediaStream
96 */
98 /**
99 * The MediaSource object describes a single capture device.
100 * This could be either audio or video.
101 */
103 /**
104 * An empty MediaSource.
105 *
106 * It can be used to unload the current media from a MediaObject.
107 *
108 * \see MediaSource()
109 */
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:
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
Base class for custom media data streams.
Note that all constructors of this class are implicit, so that you can simply write.
Type
Identifies the type of media described by the MediaSource object.
Definition mediasource.h:72
@ Url
The MediaSource object describes a URL, which can be both a local file and a file on the network.
Definition mediasource.h:85
@ Stream
The MediaSource object describes a data stream.
Definition mediasource.h:97
@ Disc
The MediaSource object describes a disc.
Definition mediasource.h:89
@ CaptureDevice
The MediaSource object describes a single capture device.
@ Empty
An empty MediaSource.
@ LocalFile
The MediaSource object describes a local file.
Definition mediasource.h:80
Media Resource Locator - A QUrl particularly for MediaSources.
Definition mrl.h:47
Provides a tuple of enduser visible name and description.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Oct 11 2024 12:10:22 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.