File indexing completed on 2025-02-09 05:31:50
0001 /* 0002 Copyright (C) 2006-2007 Matthias Kretz <kretz@kde.org> 0003 Copyright (C) 2011 Harald Sitter <sitter@kde.org> 0004 0005 This library is free software; you can redistribute it and/or 0006 modify it under the terms of the GNU Lesser General Public 0007 License as published by the Free Software Foundation; either 0008 version 2.1 of the License, or (at your option) version 3, or any 0009 later version accepted by the membership of KDE e.V. (or its 0010 successor approved by the membership of KDE e.V.), Nokia Corporation 0011 (or its successors, if any) and the KDE Free Qt Foundation, which shall 0012 act as a proxy defined in Section 6 of version 3 of the license. 0013 0014 This library is distributed in the hope that it will be useful, 0015 but WITHOUT ANY WARRANTY; without even the implied warranty of 0016 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0017 Lesser General Public License for more details. 0018 0019 You should have received a copy of the GNU Lesser General Public 0020 License along with this library. If not, see <http://www.gnu.org/licenses/>. 0021 */ 0022 0023 #ifndef PHONON_OBJECTDESCRIPTION_H 0024 #define PHONON_OBJECTDESCRIPTION_H 0025 0026 #include "phonon_export.h" 0027 0028 #include <QExplicitlySharedDataPointer> 0029 #include <QtDebug> 0030 #include <QList> 0031 #include <QSharedData> 0032 #include <QString> 0033 #include <QVariant> 0034 0035 0036 namespace Phonon 0037 { 0038 class ObjectDescriptionPrivate; 0039 0040 /** 0041 * Defines the type of information that is contained in a ObjectDescription 0042 * object. 0043 * 0044 * \ingroup Backend 0045 */ 0046 enum ObjectDescriptionType : unsigned 0047 { 0048 /** 0049 * Audio output devices. This can be soundcards (with different drivers), soundservers or 0050 * other virtual outputs like playback on a different computer on the 0051 * network. 0052 * 0053 * For Hardware devices the backend should use libkaudiodevicelist 0054 * (AudioDevice and AudioDeviceEnumerator) which will list removable 0055 * devices even when they are unplugged and provide a unique identifier 0056 * that can make backends use the same identifiers. 0057 */ 0058 AudioOutputDeviceType, 0059 0060 /** 0061 * Lists all processing effects the backend supports. 0062 */ 0063 EffectType, 0064 AudioChannelType, 0065 SubtitleType, 0066 0067 /** 0068 * Audio capture devices. This can be soundcards (with different drivers), soundservers or 0069 * other virtual inputs like capture on a different computer on the 0070 * network. 0071 * 0072 * For Hardware devices the backend should use libkaudiodevicelist 0073 * (AudioDevice and AudioDeviceEnumerator) which will list removable 0074 * devices even when they are unplugged and provide a unique identifier 0075 * that can make backends use the same identifiers. 0076 */ 0077 AudioCaptureDeviceType, 0078 0079 /** 0080 * Video capture devices. Includes webcams. 0081 */ 0082 VideoCaptureDeviceType 0083 0084 //VideoOutputDeviceType, 0085 //AudioCodecType, 0086 //VideoCodecType, 0087 //ContainerFormatType, 0088 //VisualizationType, 0089 }; 0090 0091 /** \internal 0092 * \class ObjectDescriptionData objectdescription.h phonon/ObjectDescription 0093 * \brief Data class for objects describing devices or features of the backend. 0094 * 0095 * \author Matthias Kretz <kretz@kde.org> 0096 * \see BackendCapabilities 0097 */ 0098 class PHONON_EXPORT ObjectDescriptionData : public QSharedData //krazy:exclude=dpointer (it's protected, which should be fine for this type of class) 0099 { 0100 public: 0101 /** 0102 * Returns \c true if this ObjectDescription describes the same 0103 * as \p otherDescription; otherwise returns \c false. 0104 */ 0105 bool operator==(const ObjectDescriptionData &otherDescription) const; 0106 0107 /** 0108 * Returns the name of the capture source. 0109 * 0110 * \return A string that should be presented to the user to 0111 * choose the capture source. 0112 */ 0113 QString name() const; 0114 0115 /** 0116 * Returns a description of the capture source. This text should 0117 * make clear what sound source this is, which is sometimes hard 0118 * to describe or understand from just the name. 0119 * 0120 * \return A string describing the capture source. 0121 */ 0122 QString description() const; 0123 0124 /** 0125 * Returns a named property. 0126 * 0127 * If the property is not set an invalid value is returned. 0128 * 0129 * \see propertyNames() 0130 */ 0131 QVariant property(const char *name) const; 0132 0133 /** 0134 * Returns all names that return valid data when property() is called. 0135 * 0136 * \see property() 0137 */ 0138 QList<QByteArray> propertyNames() const; 0139 0140 /** 0141 * Returns \c true if the Tuple is valid (index != -1); otherwise returns 0142 * \c false. 0143 */ 0144 bool isValid() const; 0145 0146 /** 0147 * A unique identifier for this device/. Used internally 0148 * to distinguish between the devices/. 0149 * 0150 * \return An integer that uniquely identifies every device/ 0151 */ 0152 int index() const; 0153 0154 static ObjectDescriptionData *fromIndex(ObjectDescriptionType type, int index); 0155 0156 ~ObjectDescriptionData(); 0157 0158 ObjectDescriptionData(ObjectDescriptionPrivate * = nullptr); 0159 ObjectDescriptionData(int index, const QHash<QByteArray, QVariant> &properties); 0160 0161 protected: 0162 ObjectDescriptionPrivate *const d; 0163 0164 private: 0165 ObjectDescriptionData &operator=(const ObjectDescriptionData &rhs); 0166 }; 0167 0168 template<ObjectDescriptionType T> class ObjectDescriptionModel; 0169 0170 /** \class ObjectDescription objectdescription.h phonon/ObjectDescription 0171 * \short Provides a tuple of enduser visible name and description. 0172 * 0173 * Some parts give the enduser choices, e.g. what source to capture audio from. 0174 * These choices are described by the name and description methods of this class 0175 * and identified with the id method. Subclasses then define additional 0176 * information like which audio and video choices belong together. 0177 * 0178 * \ingroup Frontend 0179 * \author Matthias Kretz <kretz@kde.org> 0180 */ 0181 template<ObjectDescriptionType T> 0182 class ObjectDescription 0183 { 0184 public: 0185 /** 0186 * Returns a new description object that describes the 0187 * device/effect/codec/... with the given \p index. 0188 */ 0189 static inline ObjectDescription<T> fromIndex(int index) { //krazy:exclude=inline 0190 return ObjectDescription<T>(QExplicitlySharedDataPointer<ObjectDescriptionData>(ObjectDescriptionData::fromIndex(T, index))); 0191 } 0192 0193 /** 0194 * Returns \c true if this ObjectDescription describes the same 0195 * as \p otherDescription; otherwise returns \c false. 0196 */ 0197 inline bool operator==(const ObjectDescription &otherDescription) const { //krazy:exclude=inline 0198 return *d == *otherDescription.d; 0199 } 0200 0201 /** 0202 * Returns \c false if this ObjectDescription describes the same 0203 * as \p otherDescription; otherwise returns \c true. 0204 */ 0205 inline bool operator!=(const ObjectDescription &otherDescription) const { //krazy:exclude=inline 0206 return !operator==(otherDescription); 0207 } 0208 0209 /** 0210 * Returns the name of the capture source. 0211 * 0212 * \return A string that should be presented to the user to 0213 * choose the capture source. 0214 */ 0215 inline QString name() const { return d->name(); } //krazy:exclude=inline 0216 0217 /** 0218 * Returns a description of the capture source. This text should 0219 * make clear what sound source this is, which is sometimes hard 0220 * to describe or understand from just the name. 0221 * 0222 * \return A string describing the capture source. 0223 */ 0224 inline QString description() const { return d->description(); } //krazy:exclude=inline 0225 0226 /** 0227 * Returns a named property. 0228 * 0229 * If the property is not set an invalid value is returned. 0230 * 0231 * \see propertyNames() 0232 */ 0233 inline QVariant property(const char *name) const { return d->property(name); } //krazy:exclude=inline 0234 0235 /** 0236 * Returns all names that return valid data when property() is called. 0237 * 0238 * \see property() 0239 */ 0240 inline QList<QByteArray> propertyNames() const { return d->propertyNames(); } //krazy:exclude=inline 0241 0242 /** 0243 * Returns \c true if the Tuple is valid (index != -1); otherwise returns 0244 * \c false. 0245 */ 0246 inline bool isValid() const { return d->isValid(); } //krazy:exclude=inline 0247 0248 /** 0249 * A unique identifier for this device/. Used internally 0250 * to distinguish between the devices/. 0251 * 0252 * \return An integer that uniquely identifies every device/ 0253 */ 0254 inline int index() const { return d->index(); } //krazy:exclude=inline 0255 0256 ObjectDescription() : d(new ObjectDescriptionData(nullptr)) {} 0257 ObjectDescription(int index, const QHash<QByteArray, QVariant> &properties) : d(new ObjectDescriptionData(index, properties)) {} 0258 0259 protected: 0260 friend class ObjectDescriptionModel<T>; 0261 ObjectDescription(const QExplicitlySharedDataPointer<ObjectDescriptionData> &dd) : d(dd) {} 0262 QExplicitlySharedDataPointer<ObjectDescriptionData> d; 0263 }; 0264 0265 template<ObjectDescriptionType T> 0266 QDebug operator<<(QDebug dbg, const ObjectDescription<T> &d) 0267 { 0268 dbg.nospace() << "\n{\n"; 0269 dbg.nospace() << " index: " << d.index() << "\n"; 0270 const QList<QByteArray> propertyNames = d.propertyNames(); 0271 for (const QByteArray &propertyName : propertyNames) { 0272 dbg.nospace() << " " << propertyName << ": " << 0273 d.property(propertyName.constData()).toString() << "\n"; 0274 } 0275 dbg.nospace() << "}\n"; 0276 0277 return dbg.space(); 0278 } 0279 0280 /** 0281 * \ingroup BackendInformation 0282 */ 0283 typedef ObjectDescription<AudioOutputDeviceType> AudioOutputDevice; 0284 /** 0285 * \ingroup BackendInformation 0286 */ 0287 #ifndef PHONON_NO_AUDIOCAPTURE 0288 typedef ObjectDescription<AudioCaptureDeviceType> AudioCaptureDevice; 0289 #endif //PHONON_NO_AUDIOCAPTURE 0290 /** 0291 * \ingroup BackendInformation 0292 */ 0293 //typedef ObjectDescription<VideoOutputDeviceType> VideoOutputDevice; 0294 /** 0295 * \ingroup BackendInformation 0296 */ 0297 #ifndef PHONON_NO_VIDEOCAPTURE 0298 typedef ObjectDescription<VideoCaptureDeviceType> VideoCaptureDevice; 0299 #endif 0300 /** 0301 * \ingroup BackendInformation 0302 */ 0303 #ifndef QT_NO_PHONON_EFFECT 0304 typedef ObjectDescription<EffectType> EffectDescription; 0305 #endif //QT_NO_PHONON_EFFECT 0306 0307 /** 0308 * \ingroup BackendInformation 0309 */ 0310 //typedef ObjectDescription<AudioCodecType> AudioCodecDescription; 0311 /** 0312 * \ingroup BackendInformation 0313 */ 0314 //typedef ObjectDescription<VideoCodecType> VideoCodecDescription; 0315 /** 0316 * \ingroup BackendInformation 0317 */ 0318 //typedef ObjectDescription<ContainerFormatType> ContainerFormatDescription; 0319 /** 0320 * \ingroup BackendInformation 0321 */ 0322 //typedef ObjectDescription<VisualizationType> VisualizationDescription; 0323 #ifndef QT_NO_PHONON_MEDIACONTROLLER 0324 typedef ObjectDescription<AudioChannelType> AudioChannelDescription; 0325 typedef ObjectDescription<SubtitleType> SubtitleDescription; 0326 #endif //QT_NO_PHONON_MEDIACONTROLLER 0327 0328 /** 0329 * \short Information about how to access a device 0330 * \ingroup BackendInformation 0331 * 0332 * To access a device, one needs the driver name (alsa, oss, pulse for example), 0333 * and the device name (dependent on the driver name). This type is a pair of a 0334 * driver and a device name. 0335 * 0336 * \see DeviceAccessList 0337 */ 0338 typedef QPair<QByteArray, QString> DeviceAccess; 0339 0340 /** 0341 * \short Information about methods for accessing a device 0342 * \ingroup BackendInformation 0343 * 0344 * It is used by the platform plugin or the backend to provide information about how 0345 * to access a certain device. To access a device, one needs the driver name (alsa, oss, 0346 * pulse for example), and the device name (dependent on the driver name). This type 0347 * is essentially a list of pairs of driver and device names. 0348 * 0349 * It can be put in an ObjectDescriptionData property list. 0350 * 0351 * \see DeviceAccess 0352 * \see AudioCaptureDevice 0353 */ 0354 typedef QList<DeviceAccess> DeviceAccessList; 0355 0356 #if QT_VERSION < QT_VERSION_CHECK(6, 0, 0) 0357 void PHONON_EXPORT_DEPRECATED registerMetaTypes(); 0358 #endif 0359 0360 } //namespace Phonon 0361 0362 Q_DECLARE_METATYPE(Phonon::AudioOutputDevice) 0363 Q_DECLARE_METATYPE(QList<Phonon::AudioOutputDevice>) 0364 0365 #ifndef PHONON_NO_AUDIOCAPTURE 0366 Q_DECLARE_METATYPE(Phonon::AudioCaptureDevice) 0367 Q_DECLARE_METATYPE(QList<Phonon::AudioCaptureDevice>) 0368 #endif //PHONON_NO_AUDIOCAPTURE 0369 0370 #ifndef PHONON_NO_VIDEOCAPTURE 0371 Q_DECLARE_METATYPE(Phonon::VideoCaptureDevice) 0372 Q_DECLARE_METATYPE(QList<Phonon::VideoCaptureDevice>) 0373 #endif //PHONON_NO_VIDEOCAPTURE 0374 0375 #ifndef QT_NO_PHONON_EFFECT 0376 Q_DECLARE_METATYPE(QList<Phonon::EffectDescription>) 0377 Q_DECLARE_METATYPE(Phonon::EffectDescription) 0378 #endif //QT_NO_PHONON_EFFECT 0379 0380 0381 #ifndef QT_NO_PHONON_MEDIACONTROLLER 0382 Q_DECLARE_METATYPE(Phonon::AudioChannelDescription) 0383 Q_DECLARE_METATYPE(Phonon::SubtitleDescription) 0384 Q_DECLARE_METATYPE(QList<Phonon::AudioChannelDescription>) 0385 Q_DECLARE_METATYPE(QList<Phonon::SubtitleDescription>) 0386 #endif //QT_NO_PHONON_MEDIACONTROLLER 0387 0388 Q_DECLARE_METATYPE(Phonon::DeviceAccess) 0389 Q_DECLARE_METATYPE(Phonon::DeviceAccessList) 0390 0391 0392 0393 #endif // PHONON_OBJECTDESCRIPTION_H