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 <QtCore/QExplicitlySharedDataPointer>
29#include <QtCore/QtDebug>
30#include <QtCore/QList>
31#include <QtCore/QSharedData>
32#include <QtCore/QString>
33#include <QtCore/QVariant>
34
35
36namespace 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
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 */
98class 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 * = 0);
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
168template<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 */
181template<ObjectDescriptionType T>
182class 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(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(0)) {}
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
265template<ObjectDescriptionType T>
266QDebug operator<<(QDebug dbg, const ObjectDescription<T> &d)
267{
268 dbg.nospace() << "\n{\n";
269 dbg.nospace() << " index: " << d.index() << "\n";
270 Q_FOREACH (const QByteArray &propertyName, d.propertyNames()) {
271 dbg.nospace() << " " << propertyName << ": " <<
272 d.property(propertyName).toString() << "\n";
273 }
274 dbg.nospace() << "}\n";
275
276 return dbg.space();
277}
278
279/**
280 * \ingroup BackendInformation
281 */
282typedef ObjectDescription<AudioOutputDeviceType> AudioOutputDevice;
283/**
284 * \ingroup BackendInformation
285 */
286#ifndef PHONON_NO_AUDIOCAPTURE
287typedef ObjectDescription<AudioCaptureDeviceType> AudioCaptureDevice;
288#endif //PHONON_NO_AUDIOCAPTURE
289/**
290 * \ingroup BackendInformation
291 */
292//typedef ObjectDescription<VideoOutputDeviceType> VideoOutputDevice;
293/**
294 * \ingroup BackendInformation
295 */
296#ifndef PHONON_NO_VIDEOCAPTURE
297typedef ObjectDescription<VideoCaptureDeviceType> VideoCaptureDevice;
298#endif
299/**
300 * \ingroup BackendInformation
301 */
302#ifndef QT_NO_PHONON_EFFECT
303typedef ObjectDescription<EffectType> EffectDescription;
304#endif //QT_NO_PHONON_EFFECT
305
306/**
307 * \ingroup BackendInformation
308 */
309//typedef ObjectDescription<AudioCodecType> AudioCodecDescription;
310/**
311 * \ingroup BackendInformation
312 */
313//typedef ObjectDescription<VideoCodecType> VideoCodecDescription;
314/**
315 * \ingroup BackendInformation
316 */
317//typedef ObjectDescription<ContainerFormatType> ContainerFormatDescription;
318/**
319 * \ingroup BackendInformation
320 */
321//typedef ObjectDescription<VisualizationType> VisualizationDescription;
322#ifndef QT_NO_PHONON_MEDIACONTROLLER
323typedef ObjectDescription<AudioChannelType> AudioChannelDescription;
324typedef ObjectDescription<SubtitleType> SubtitleDescription;
325#endif //QT_NO_PHONON_MEDIACONTROLLER
326
327/**
328 * \short Information about how to access a device
329 * \ingroup BackendInformation
330 *
331 * To access a device, one needs the driver name (alsa, oss, pulse for example),
332 * and the device name (dependent on the driver name). This type is a pair of a
333 * driver and a device name.
334 *
335 * \see DeviceAccessList
336 */
337typedef QPair<QByteArray, QString> DeviceAccess;
338
339/**
340 * \short Information about methods for accessing a device
341 * \ingroup BackendInformation
342 *
343 * It is used by the platform plugin or the backend to provide information about how
344 * to access a certain device. To access a device, one needs the driver name (alsa, oss,
345 * pulse for example), and the device name (dependent on the driver name). This type
346 * is essentialy a list of pairs of driver and device names.
347 *
348 * It can be put in an ObjectDescriptionData property list.
349 *
350 * \see DeviceAccess
351 * \see AudioCaptureDevice
352 */
353typedef QList<DeviceAccess> DeviceAccessList;
354
355void PHONON_EXPORT_DEPRECATED registerMetaTypes();
356
357} //namespace Phonon
358
359Q_DECLARE_METATYPE(Phonon::AudioOutputDevice)
360Q_DECLARE_METATYPE(QList<Phonon::AudioOutputDevice>)
361
362#ifndef PHONON_NO_AUDIOCAPTURE
363Q_DECLARE_METATYPE(Phonon::AudioCaptureDevice)
364Q_DECLARE_METATYPE(QList<Phonon::AudioCaptureDevice>)
365#endif //PHONON_NO_AUDIOCAPTURE
366
367#ifndef PHONON_NO_VIDEOCAPTURE
368Q_DECLARE_METATYPE(Phonon::VideoCaptureDevice)
369Q_DECLARE_METATYPE(QList<Phonon::VideoCaptureDevice>)
370#endif //PHONON_NO_VIDEOCAPTURE
371
372#ifndef QT_NO_PHONON_EFFECT
373Q_DECLARE_METATYPE(QList<Phonon::EffectDescription>)
374Q_DECLARE_METATYPE(Phonon::EffectDescription)
375#endif //QT_NO_PHONON_EFFECT
376
377
378#ifndef QT_NO_PHONON_MEDIACONTROLLER
379Q_DECLARE_METATYPE(Phonon::AudioChannelDescription)
380Q_DECLARE_METATYPE(Phonon::SubtitleDescription)
381Q_DECLARE_METATYPE(QList<Phonon::AudioChannelDescription>)
382Q_DECLARE_METATYPE(QList<Phonon::SubtitleDescription>)
383#endif //QT_NO_PHONON_MEDIACONTROLLER
384
385Q_DECLARE_METATYPE(Phonon::DeviceAccess)
386Q_DECLARE_METATYPE(Phonon::DeviceAccessList)
387
388
389
390#endif // PHONON_OBJECTDESCRIPTION_H
391