1 | /* |
2 | Copyright (C) 2006-2007 Matthias Kretz <kretz@kde.org> |
3 | Copyright (C) 2011 Harald Sitter <sitter@kde.org> |
4 | |
5 | This library is free software; you can redistribute it and/or |
6 | modify it under the terms of the GNU Lesser General Public |
7 | License as published by the Free Software Foundation; either |
8 | version 2.1 of the License, or (at your option) version 3, or any |
9 | later version accepted by the membership of KDE e.V. (or its |
10 | successor approved by the membership of KDE e.V.), Nokia Corporation |
11 | (or its successors, if any) and the KDE Free Qt Foundation, which shall |
12 | act as a proxy defined in Section 6 of version 3 of the license. |
13 | |
14 | This library is distributed in the hope that it will be useful, |
15 | but WITHOUT ANY WARRANTY; without even the implied warranty of |
16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
17 | Lesser General Public License for more details. |
18 | |
19 | You should have received a copy of the GNU Lesser General Public |
20 | License along with this library. If not, see <http://www.gnu.org/licenses/>. |
21 | */ |
22 | |
23 | #ifndef PHONON_OBJECTDESCRIPTION_H |
24 | #define PHONON_OBJECTDESCRIPTION_H |
25 | |
26 | #include "phonon_export.h" |
27 | |
28 | #include <QExplicitlySharedDataPointer> |
29 | #include <QtDebug> |
30 | #include <QList> |
31 | #include <QSharedData> |
32 | #include <QString> |
33 | #include <QVariant> |
34 | |
35 | |
36 | namespace Phonon |
37 | { |
38 | class ObjectDescriptionPrivate; |
39 | |
40 | /** |
41 | * Defines the type of information that is contained in a ObjectDescription |
42 | * object. |
43 | * |
44 | * \ingroup Backend |
45 | */ |
46 | enum ObjectDescriptionType : unsigned |
47 | { |
48 | /** |
49 | * Audio output devices. This can be soundcards (with different drivers), soundservers or |
50 | * other virtual outputs like playback on a different computer on the |
51 | * network. |
52 | * |
53 | * For Hardware devices the backend should use libkaudiodevicelist |
54 | * (AudioDevice and AudioDeviceEnumerator) which will list removable |
55 | * devices even when they are unplugged and provide a unique identifier |
56 | * that can make backends use the same identifiers. |
57 | */ |
58 | AudioOutputDeviceType, |
59 | |
60 | /** |
61 | * Lists all processing effects the backend supports. |
62 | */ |
63 | EffectType, |
64 | AudioChannelType, |
65 | SubtitleType, |
66 | |
67 | /** |
68 | * Audio capture devices. This can be soundcards (with different drivers), soundservers or |
69 | * other virtual inputs like capture on a different computer on the |
70 | * network. |
71 | * |
72 | * For Hardware devices the backend should use libkaudiodevicelist |
73 | * (AudioDevice and AudioDeviceEnumerator) which will list removable |
74 | * devices even when they are unplugged and provide a unique identifier |
75 | * that can make backends use the same identifiers. |
76 | */ |
77 | AudioCaptureDeviceType, |
78 | |
79 | /** |
80 | * Video capture devices. Includes webcams. |
81 | */ |
82 | VideoCaptureDeviceType |
83 | |
84 | //VideoOutputDeviceType, |
85 | //AudioCodecType, |
86 | //VideoCodecType, |
87 | //ContainerFormatType, |
88 | //VisualizationType, |
89 | }; |
90 | |
91 | /** \internal |
92 | * \class ObjectDescriptionData objectdescription.h phonon/ObjectDescription |
93 | * \brief Data class for objects describing devices or features of the backend. |
94 | * |
95 | * \author Matthias Kretz <kretz@kde.org> |
96 | * \see BackendCapabilities |
97 | */ |
98 | class PHONON_EXPORT ObjectDescriptionData : public QSharedData //krazy:exclude=dpointer (it's protected, which should be fine for this type of class) |
99 | { |
100 | public: |
101 | /** |
102 | * Returns \c true if this ObjectDescription describes the same |
103 | * as \p otherDescription; otherwise returns \c false. |
104 | */ |
105 | bool operator==(const ObjectDescriptionData &otherDescription) const; |
106 | |
107 | /** |
108 | * Returns the name of the capture source. |
109 | * |
110 | * \return A string that should be presented to the user to |
111 | * choose the capture source. |
112 | */ |
113 | QString name() const; |
114 | |
115 | /** |
116 | * Returns a description of the capture source. This text should |
117 | * make clear what sound source this is, which is sometimes hard |
118 | * to describe or understand from just the name. |
119 | * |
120 | * \return A string describing the capture source. |
121 | */ |
122 | QString description() const; |
123 | |
124 | /** |
125 | * Returns a named property. |
126 | * |
127 | * If the property is not set an invalid value is returned. |
128 | * |
129 | * \see propertyNames() |
130 | */ |
131 | QVariant property(const char *name) const; |
132 | |
133 | /** |
134 | * Returns all names that return valid data when property() is called. |
135 | * |
136 | * \see property() |
137 | */ |
138 | QList<QByteArray> propertyNames() const; |
139 | |
140 | /** |
141 | * Returns \c true if the Tuple is valid (index != -1); otherwise returns |
142 | * \c false. |
143 | */ |
144 | bool isValid() const; |
145 | |
146 | /** |
147 | * A unique identifier for this device/. Used internally |
148 | * to distinguish between the devices/. |
149 | * |
150 | * \return An integer that uniquely identifies every device/ |
151 | */ |
152 | int index() const; |
153 | |
154 | static ObjectDescriptionData *fromIndex(ObjectDescriptionType type, int index); |
155 | |
156 | ~ObjectDescriptionData(); |
157 | |
158 | ObjectDescriptionData(ObjectDescriptionPrivate * = nullptr); |
159 | ObjectDescriptionData(int index, const QHash<QByteArray, QVariant> &properties); |
160 | |
161 | protected: |
162 | ObjectDescriptionPrivate *const d; |
163 | |
164 | private: |
165 | ObjectDescriptionData &operator=(const ObjectDescriptionData &rhs); |
166 | }; |
167 | |
168 | template<ObjectDescriptionType T> class ObjectDescriptionModel; |
169 | |
170 | /** \class ObjectDescription objectdescription.h phonon/ObjectDescription |
171 | * \short Provides a tuple of enduser visible name and description. |
172 | * |
173 | * Some parts give the enduser choices, e.g. what source to capture audio from. |
174 | * These choices are described by the name and description methods of this class |
175 | * and identified with the id method. Subclasses then define additional |
176 | * information like which audio and video choices belong together. |
177 | * |
178 | * \ingroup Frontend |
179 | * \author Matthias Kretz <kretz@kde.org> |
180 | */ |
181 | template<ObjectDescriptionType T> |
182 | class ObjectDescription |
183 | { |
184 | public: |
185 | /** |
186 | * Returns a new description object that describes the |
187 | * device/effect/codec/... with the given \p index. |
188 | */ |
189 | static inline ObjectDescription<T> fromIndex(int index) { //krazy:exclude=inline |
190 | return ObjectDescription<T>(QExplicitlySharedDataPointer<ObjectDescriptionData>(ObjectDescriptionData::fromIndex(type: T, index))); |
191 | } |
192 | |
193 | /** |
194 | * Returns \c true if this ObjectDescription describes the same |
195 | * as \p otherDescription; otherwise returns \c false. |
196 | */ |
197 | inline bool operator==(const ObjectDescription &otherDescription) const { //krazy:exclude=inline |
198 | return *d == *otherDescription.d; |
199 | } |
200 | |
201 | /** |
202 | * Returns \c false if this ObjectDescription describes the same |
203 | * as \p otherDescription; otherwise returns \c true. |
204 | */ |
205 | inline bool operator!=(const ObjectDescription &otherDescription) const { //krazy:exclude=inline |
206 | return !operator==(otherDescription); |
207 | } |
208 | |
209 | /** |
210 | * Returns the name of the capture source. |
211 | * |
212 | * \return A string that should be presented to the user to |
213 | * choose the capture source. |
214 | */ |
215 | inline QString name() const { return d->name(); } //krazy:exclude=inline |
216 | |
217 | /** |
218 | * Returns a description of the capture source. This text should |
219 | * make clear what sound source this is, which is sometimes hard |
220 | * to describe or understand from just the name. |
221 | * |
222 | * \return A string describing the capture source. |
223 | */ |
224 | inline QString description() const { return d->description(); } //krazy:exclude=inline |
225 | |
226 | /** |
227 | * Returns a named property. |
228 | * |
229 | * If the property is not set an invalid value is returned. |
230 | * |
231 | * \see propertyNames() |
232 | */ |
233 | inline QVariant property(const char *name) const { return d->property(name); } //krazy:exclude=inline |
234 | |
235 | /** |
236 | * Returns all names that return valid data when property() is called. |
237 | * |
238 | * \see property() |
239 | */ |
240 | inline QList<QByteArray> propertyNames() const { return d->propertyNames(); } //krazy:exclude=inline |
241 | |
242 | /** |
243 | * Returns \c true if the Tuple is valid (index != -1); otherwise returns |
244 | * \c false. |
245 | */ |
246 | inline bool isValid() const { return d->isValid(); } //krazy:exclude=inline |
247 | |
248 | /** |
249 | * A unique identifier for this device/. Used internally |
250 | * to distinguish between the devices/. |
251 | * |
252 | * \return An integer that uniquely identifies every device/ |
253 | */ |
254 | inline int index() const { return d->index(); } //krazy:exclude=inline |
255 | |
256 | ObjectDescription() : d(new ObjectDescriptionData(nullptr)) {} |
257 | ObjectDescription(int index, const QHash<QByteArray, QVariant> &properties) : d(new ObjectDescriptionData(index, properties)) {} |
258 | |
259 | protected: |
260 | friend class ObjectDescriptionModel<T>; |
261 | ObjectDescription(const QExplicitlySharedDataPointer<ObjectDescriptionData> &dd) : d(dd) {} |
262 | QExplicitlySharedDataPointer<ObjectDescriptionData> d; |
263 | }; |
264 | |
265 | template<ObjectDescriptionType T> |
266 | QDebug operator<<(QDebug dbg, const ObjectDescription<T> &d) |
267 | { |
268 | dbg.nospace() << "\n{\n" ; |
269 | dbg.nospace() << " index: " << d.index() << "\n" ; |
270 | const QList<QByteArray> propertyNames = d.propertyNames(); |
271 | for (const QByteArray &propertyName : propertyNames) { |
272 | dbg.nospace() << " " << propertyName << ": " << |
273 | d.property(propertyName.constData()).toString() << "\n" ; |
274 | } |
275 | dbg.nospace() << "}\n" ; |
276 | |
277 | return dbg.space(); |
278 | } |
279 | |
280 | /** |
281 | * \ingroup BackendInformation |
282 | */ |
283 | typedef ObjectDescription<AudioOutputDeviceType> AudioOutputDevice; |
284 | /** |
285 | * \ingroup BackendInformation |
286 | */ |
287 | #ifndef PHONON_NO_AUDIOCAPTURE |
288 | typedef ObjectDescription<AudioCaptureDeviceType> AudioCaptureDevice; |
289 | #endif //PHONON_NO_AUDIOCAPTURE |
290 | /** |
291 | * \ingroup BackendInformation |
292 | */ |
293 | //typedef ObjectDescription<VideoOutputDeviceType> VideoOutputDevice; |
294 | /** |
295 | * \ingroup BackendInformation |
296 | */ |
297 | #ifndef PHONON_NO_VIDEOCAPTURE |
298 | typedef ObjectDescription<VideoCaptureDeviceType> VideoCaptureDevice; |
299 | #endif |
300 | /** |
301 | * \ingroup BackendInformation |
302 | */ |
303 | #ifndef QT_NO_PHONON_EFFECT |
304 | typedef ObjectDescription<EffectType> EffectDescription; |
305 | #endif //QT_NO_PHONON_EFFECT |
306 | |
307 | /** |
308 | * \ingroup BackendInformation |
309 | */ |
310 | //typedef ObjectDescription<AudioCodecType> AudioCodecDescription; |
311 | /** |
312 | * \ingroup BackendInformation |
313 | */ |
314 | //typedef ObjectDescription<VideoCodecType> VideoCodecDescription; |
315 | /** |
316 | * \ingroup BackendInformation |
317 | */ |
318 | //typedef ObjectDescription<ContainerFormatType> ContainerFormatDescription; |
319 | /** |
320 | * \ingroup BackendInformation |
321 | */ |
322 | //typedef ObjectDescription<VisualizationType> VisualizationDescription; |
323 | #ifndef QT_NO_PHONON_MEDIACONTROLLER |
324 | typedef ObjectDescription<AudioChannelType> AudioChannelDescription; |
325 | typedef ObjectDescription<SubtitleType> SubtitleDescription; |
326 | #endif //QT_NO_PHONON_MEDIACONTROLLER |
327 | |
328 | /** |
329 | * \short Information about how to access a device |
330 | * \ingroup BackendInformation |
331 | * |
332 | * To access a device, one needs the driver name (alsa, oss, pulse for example), |
333 | * and the device name (dependent on the driver name). This type is a pair of a |
334 | * driver and a device name. |
335 | * |
336 | * \see DeviceAccessList |
337 | */ |
338 | typedef QPair<QByteArray, QString> DeviceAccess; |
339 | |
340 | /** |
341 | * \short Information about methods for accessing a device |
342 | * \ingroup BackendInformation |
343 | * |
344 | * It is used by the platform plugin or the backend to provide information about how |
345 | * to access a certain device. To access a device, one needs the driver name (alsa, oss, |
346 | * pulse for example), and the device name (dependent on the driver name). This type |
347 | * is essentially a list of pairs of driver and device names. |
348 | * |
349 | * It can be put in an ObjectDescriptionData property list. |
350 | * |
351 | * \see DeviceAccess |
352 | * \see AudioCaptureDevice |
353 | */ |
354 | typedef QList<DeviceAccess> DeviceAccessList; |
355 | |
356 | #if QT_VERSION < QT_VERSION_CHECK(6, 0, 0) |
357 | void PHONON_EXPORT_DEPRECATED registerMetaTypes(); |
358 | #endif |
359 | |
360 | } //namespace Phonon |
361 | |
362 | Q_DECLARE_METATYPE(Phonon::AudioOutputDevice) |
363 | Q_DECLARE_METATYPE(QList<Phonon::AudioOutputDevice>) |
364 | |
365 | #ifndef PHONON_NO_AUDIOCAPTURE |
366 | Q_DECLARE_METATYPE(Phonon::AudioCaptureDevice) |
367 | Q_DECLARE_METATYPE(QList<Phonon::AudioCaptureDevice>) |
368 | #endif //PHONON_NO_AUDIOCAPTURE |
369 | |
370 | #ifndef PHONON_NO_VIDEOCAPTURE |
371 | Q_DECLARE_METATYPE(Phonon::VideoCaptureDevice) |
372 | Q_DECLARE_METATYPE(QList<Phonon::VideoCaptureDevice>) |
373 | #endif //PHONON_NO_VIDEOCAPTURE |
374 | |
375 | #ifndef QT_NO_PHONON_EFFECT |
376 | Q_DECLARE_METATYPE(QList<Phonon::EffectDescription>) |
377 | Q_DECLARE_METATYPE(Phonon::EffectDescription) |
378 | #endif //QT_NO_PHONON_EFFECT |
379 | |
380 | |
381 | #ifndef QT_NO_PHONON_MEDIACONTROLLER |
382 | Q_DECLARE_METATYPE(Phonon::AudioChannelDescription) |
383 | Q_DECLARE_METATYPE(Phonon::SubtitleDescription) |
384 | Q_DECLARE_METATYPE(QList<Phonon::AudioChannelDescription>) |
385 | Q_DECLARE_METATYPE(QList<Phonon::SubtitleDescription>) |
386 | #endif //QT_NO_PHONON_MEDIACONTROLLER |
387 | |
388 | Q_DECLARE_METATYPE(Phonon::DeviceAccess) |
389 | Q_DECLARE_METATYPE(Phonon::DeviceAccessList) |
390 | |
391 | |
392 | |
393 | #endif // PHONON_OBJECTDESCRIPTION_H |
394 | |