File indexing completed on 2025-02-09 05:31:49
0001 /* This file is part of the KDE project 0002 Copyright (C) 2007 Matthias Kretz <kretz@kde.org> 0003 0004 This library is free software; you can redistribute it and/or 0005 modify it under the terms of the GNU Lesser General Public 0006 License as published by the Free Software Foundation; either 0007 version 2.1 of the License, or (at your option) version 3, or any 0008 later version accepted by the membership of KDE e.V. (or its 0009 successor approved by the membership of KDE e.V.), Nokia Corporation 0010 (or its successors, if any) and the KDE Free Qt Foundation, which shall 0011 act as a proxy defined in Section 6 of version 3 of the license. 0012 0013 This library is distributed in the hope that it will be useful, 0014 but WITHOUT ANY WARRANTY; without even the implied warranty of 0015 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0016 Lesser General Public License for more details. 0017 0018 You should have received a copy of the GNU Lesser General Public 0019 License along with this library. If not, see <http://www.gnu.org/licenses/>. 0020 0021 */ 0022 0023 #ifndef PHONON_MEDIASOURCE_H 0024 #define PHONON_MEDIASOURCE_H 0025 0026 #include "phonon_export.h" 0027 #include "phononnamespace.h" 0028 0029 #include "mrl.h" 0030 #include "objectdescription.h" 0031 0032 #include <QSharedData> 0033 #include <QString> 0034 0035 0036 class QUrl; 0037 class QIODevice; 0038 0039 namespace Phonon 0040 { 0041 0042 class MediaSourcePrivate; 0043 class AbstractMediaStream; 0044 0045 /** \class MediaSource mediasource.h phonon/MediaSource 0046 * Note that all constructors of this class are implicit, so that you can simply write 0047 * \code 0048 * MediaObject m; 0049 * QString fileName("/home/foo/bar.ogg"); 0050 * QUrl url("http://www.example.com/stream.mp3"); 0051 * QBuffer *someBuffer; 0052 * m.setCurrentSource(fileName); 0053 * m.setCurrentSource(url); 0054 * m.setCurrentSource(someBuffer); 0055 * m.setCurrentSource(Phonon::Cd); 0056 * \endcode 0057 * 0058 * \ingroup Playback 0059 * \ingroup Recording 0060 * \author Matthias Kretz <kretz@kde.org> 0061 */ 0062 class PHONON_EXPORT MediaSource 0063 { 0064 friend class StreamInterface; 0065 friend PHONON_EXPORT QDebug operator <<(QDebug dbg, const Phonon::MediaSource &); 0066 public: 0067 /** 0068 * Identifies the type of media described by the MediaSource object. 0069 * 0070 * \see MediaSource::type() 0071 */ 0072 enum Type { 0073 /** 0074 * The MediaSource object does not describe any valid source. 0075 */ 0076 Invalid = -1, 0077 /** 0078 * The MediaSource object describes a local file. 0079 */ 0080 LocalFile, 0081 /** 0082 * The MediaSource object describes a URL, which can be both a local file and a file on 0083 * the network. 0084 */ 0085 Url, 0086 /** 0087 * The MediaSource object describes a disc. 0088 */ 0089 Disc, 0090 /** 0091 * The MediaSource object describes a data stream. 0092 * 0093 * This is also the type used for QIODevices. 0094 * 0095 * \see AbstractMediaStream 0096 */ 0097 Stream, 0098 /** 0099 * The MediaSource object describes a single capture device. 0100 * This could be either audio or video. 0101 */ 0102 CaptureDevice, 0103 /** 0104 * An empty MediaSource. 0105 * 0106 * It can be used to unload the current media from a MediaObject. 0107 * 0108 * \see MediaSource() 0109 */ 0110 Empty, 0111 /** 0112 * The MediaSource object describes one device for video capture and one for audio 0113 * capture. Facilitates capturing both audio and video at the same time, from 0114 * different devices. 0115 * It's essentially like two CaptureDevice media sources (one of video type, one 0116 * of audio type) merged together. 0117 */ 0118 AudioVideoCapture 0119 /* post 4.0: 0120 / ** 0121 * Links multiple MediaSource objects together. 0122 * / 0123 Link 0124 */ 0125 }; 0126 0127 /** 0128 * Creates an empty MediaSource. 0129 * 0130 * An empty MediaSource is considered valid and can be set on a MediaObject to unload its 0131 * current media. 0132 * 0133 * \see Empty 0134 */ 0135 MediaSource(); 0136 0137 /** 0138 * Creates a MediaSource object for a local file or a Qt resource. 0139 * 0140 * \deprecated Use MediaSource(QUrl("qrc:///...")) for a Qt resource, MediaSource(QUrl::fromLocalFile("...")) for a local file, or MediaSource(QUrl("...")) for an URL. 0141 * 0142 * \param fileName file name of a local media file or a Qt resource that was compiled in. 0143 */ 0144 PHONON_DEPRECATED MediaSource(const QString &fileName); //krazy:exclude=explicit 0145 0146 /** 0147 * Creates a MediaSource object for a URL. 0148 * 0149 * A Qt resource can be specified by using an url with a qrc scheme. 0150 * 0151 * \param url URL to a media file or stream. 0152 */ 0153 MediaSource(const QUrl &url); //krazy:exclude=explicit 0154 0155 /** 0156 * Creates a MediaSource object for discs. 0157 * 0158 * \param discType See \ref DiscType 0159 * \param deviceName A platform dependent device name. This can be useful if the computer 0160 * has more than one CD drive. It is recommended to use Solid to retrieve the device name in 0161 * a portable way. 0162 */ 0163 MediaSource(DiscType discType, const QString &deviceName = QString()); //krazy:exclude=explicit 0164 0165 #ifndef PHONON_NO_AUDIOCAPTURE 0166 /** 0167 * Creates a MediaSource object for audio capture devices. 0168 * If the device is valid, this creates a 'CaptureDevice' type MediaSource. 0169 */ 0170 MediaSource(const AudioCaptureDevice& device); 0171 #endif 0172 0173 #ifndef PHONON_NO_VIDEOCAPTURE 0174 /** 0175 * Creates a MediaSource object for video capture devices. 0176 * If the device is valid, this creates a 'CaptureDevice' type MediaSource 0177 */ 0178 MediaSource(const VideoCaptureDevice& device); 0179 #endif 0180 0181 #if !defined(PHONON_NO_VIDEOCAPTURE) && !defined(PHONON_NO_AUDIOCAPTURE) 0182 /** 0183 * Sets the source to the preferred audio capture device for the specified category 0184 * If a valid device is found, this creates a 'CaptureDevice' type MediaSource 0185 */ 0186 MediaSource(Capture::DeviceType deviceType, CaptureCategory category = NoCaptureCategory); 0187 0188 /** 0189 * Creates a MediaSource object that tries to describe a video capture device and 0190 * an audio capture device, together. The devices are appropriate for the specified 0191 * category. 0192 * 0193 * If valid devices are found for both audio and video, then the resulting MediaSource 0194 * is of type 'AudioVideoCapture'. If only an audio or a video valid device is found, 0195 * the resulting type is 'CaptureDevice'. If no valid devices are found, the resulting 0196 * type is 'Invalid'. 0197 */ 0198 MediaSource(CaptureCategory category); 0199 #endif 0200 0201 #ifndef QT_NO_PHONON_ABSTRACTMEDIASTREAM 0202 /** 0203 * Creates a MediaSource object for a data stream. 0204 * 0205 * Your application can provide the media data by subclassing AbstractMediaStream and 0206 * passing a pointer to that object. %Phonon will never delete the \p stream. 0207 * 0208 * \param stream The AbstractMediaStream subclass to provide the media data. 0209 * 0210 * \see setAutoDelete 0211 */ 0212 MediaSource(AbstractMediaStream *stream); //krazy:exclude=explicit 0213 0214 /** 0215 * Creates a MediaSource object for a QIODevice. 0216 * 0217 * This constructor can be very handy in the combination of QByteArray and QBuffer. 0218 * 0219 * \param ioDevice An arbitrary readable QIODevice subclass. If the device is not opened 0220 * MediaSource will open it as QIODevice::ReadOnly. Sequential I/O devices are possible, 0221 * too. For those MediaObject::isSeekable() will have to return false obviously. 0222 * 0223 * \see setAutoDelete 0224 */ 0225 MediaSource(QIODevice *ioDevice); //krazy:exclude=explicit 0226 #endif 0227 0228 /** 0229 * Destroys the MediaSource object. 0230 */ 0231 ~MediaSource(); 0232 0233 /** 0234 * Constructs a copy of \p rhs. 0235 * 0236 * This constructor is fast thanks to explicit sharing. 0237 */ 0238 MediaSource(const MediaSource &rhs); 0239 0240 /** 0241 * Assigns \p rhs to this MediaSource and returns a reference to this MediaSource. 0242 * 0243 * This operation is fast thanks to explicit sharing. 0244 */ 0245 MediaSource &operator=(const MediaSource &rhs); 0246 0247 /** 0248 * Returns \p true if this MediaSource is equal to \p rhs; otherwise returns \p false. 0249 */ 0250 bool operator==(const MediaSource &rhs) const; 0251 0252 /** 0253 * Tell the MediaSource to take ownership of the AbstractMediaStream or QIODevice that was 0254 * passed in the constructor. 0255 * 0256 * The default setting is \p false, for safety. If you turn it on, you should only access 0257 * the AbstractMediaStream/QIODevice object as long as you yourself keep a MediaSource 0258 * object around. As long as you keep the MediaSource object wrapping the stream/device 0259 * the object will not get deleted. 0260 * 0261 * \see autoDelete 0262 */ 0263 void setAutoDelete(bool enable); 0264 0265 /** 0266 * Returns the setting of the auto-delete option. The default is \p false. 0267 * 0268 * \see setAutoDelete 0269 */ 0270 bool autoDelete() const; 0271 0272 /** 0273 * Returns the type of the MediaSource (depends on the constructor that was used). 0274 * 0275 * \see Type 0276 */ 0277 Type type() const; 0278 0279 /** 0280 * Returns the file name of the MediaSource if type() == LocalFile; otherwise returns 0281 * QString(). 0282 */ 0283 QString fileName() const; 0284 0285 /** 0286 * Returns the MRL of the MediaSource if type() == URL or type() == LocalFile; otherwise 0287 * returns Mrl(). 0288 * Phonon::Mrl is based on QUrl and adds some additional functionality that 0289 * is necessary to ensure proper encoding usage in the Phonon backends. 0290 * 0291 * Usually you will not have to use this in an application. 0292 * 0293 * \since 4.5 0294 * \ingroup Backend 0295 */ 0296 Mrl mrl() const; 0297 0298 /** 0299 * Returns the url of the MediaSource if type() == URL or type() == LocalFile; otherwise 0300 * returns QUrl(). 0301 */ 0302 QUrl url() const; 0303 0304 /** 0305 * Returns the disc type of the MediaSource if type() == Disc; otherwise returns \ref 0306 * NoDisc. 0307 */ 0308 DiscType discType() const; 0309 0310 /** 0311 * Returns the access list for the device of this media source. Valid for capture devices. 0312 * \warning use only with MediaSource with type() == CaptureDevice 0313 */ 0314 const DeviceAccessList& deviceAccessList() const; 0315 0316 /** 0317 * Returns the access list for the video device used for capture. 0318 * Valid for type() == CaptureDevice or type() == AudioVideoCapture. 0319 * If used with CaptureDevice, the kind of device should be Video, for a valid result. 0320 */ 0321 const DeviceAccessList& videoDeviceAccessList() const; 0322 0323 /** 0324 * Returns the access list for the audio device used for capture. 0325 * Valid for type() == CaptureDevice or type() == AudioVideoCapture. 0326 * If used with CaptureDevice, the kind of device should be Audio, for a valid result. 0327 */ 0328 const DeviceAccessList& audioDeviceAccessList() const; 0329 0330 /** 0331 * Returns the device name of the MediaSource if type() == Disc; otherwise returns 0332 * QString(). 0333 */ 0334 QString deviceName() const; 0335 0336 #ifndef QT_NO_PHONON_ABSTRACTMEDIASTREAM 0337 /** 0338 * Returns the media stream of the MediaSource if type() == Stream; otherwise returns 0. 0339 * QIODevices are handled as streams, too. 0340 */ 0341 AbstractMediaStream *stream() const; 0342 #endif 0343 0344 #ifndef PHONON_NO_AUDIOCAPTURE 0345 /** 0346 * Returns the audio capture device for the media source if applicable. 0347 */ 0348 AudioCaptureDevice audioCaptureDevice() const; 0349 #endif 0350 0351 #ifndef PHONON_NO_VIDEOCAPTURE 0352 /** 0353 * Returns the video capture device for the media source if applicable. 0354 */ 0355 VideoCaptureDevice videoCaptureDevice() const; 0356 #endif 0357 0358 /* post 4.0: 0359 MediaSource(const QList<MediaSource> &mediaList); 0360 QList<MediaSource> substreams() const; 0361 */ 0362 0363 protected: 0364 QExplicitlySharedDataPointer<MediaSourcePrivate> d; 0365 MediaSource(MediaSourcePrivate &); 0366 0367 PHONON_DEPRECATED MediaSource(const DeviceAccess &access); 0368 }; 0369 0370 PHONON_EXPORT QDebug operator <<(QDebug dbg, const Phonon::MediaSource &); 0371 0372 } // namespace Phonon 0373 0374 0375 #endif // PHONON_MEDIASOURCE_H