1/* This file is part of the KDE project
2 Copyright (C) 2006-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_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
35QT_BEGIN_HEADER
36QT_BEGIN_NAMESPACE
37
38namespace Phonon
39{
40 class ObjectDescriptionPrivate;
41
42 /**
43 * Defines the type of information that is contained in a ObjectDescription
44 * object.
45 *
46 * \ingroup Backend
47 */
48 enum ObjectDescriptionType
49 {
50 /**
51 * Audio output devices. This can be soundcards (with different drivers), soundservers or
52 * other virtual outputs like playback on a different computer on the
53 * network.
54 *
55 * For Hardware devices the backend should use libkaudiodevicelist
56 * (AudioDevice and AudioDeviceEnumerator) which will list removable
57 * devices even when they are unplugged and provide a unique identifier
58 * that can make backends use the same identifiers.
59 */
60 AudioOutputDeviceType,
61
62 /**
63 * Lists all processing effects the backend supports.
64 */
65 EffectType,
66 AudioChannelType,
67 SubtitleType,
68
69 /**
70 * Audio capture devices. This can be soundcards (with different drivers), soundservers or
71 * other virtual inputs like capture on a different computer on the
72 * network.
73 *
74 * For Hardware devices the backend should use libkaudiodevicelist
75 * (AudioDevice and AudioDeviceEnumerator) which will list removable
76 * devices even when they are unplugged and provide a unique identifier
77 * that can make backends use the same identifiers.
78 */
79 AudioCaptureDeviceType
80
81 //VideoOutputDeviceType,
82 //VideoCaptureDeviceType,
83 //AudioCodecType,
84 //VideoCodecType,
85 //ContainerFormatType,
86 //VisualizationType,
87 };
88
89/** \internal
90 * \class ObjectDescriptionData objectdescription.h Phonon/ObjectDescription
91 * \brief Data class for objects describing devices or features of the backend.
92 *
93 * \author Matthias Kretz <kretz@kde.org>
94 * \see BackendCapabilities
95 */
96class PHONON_EXPORT ObjectDescriptionData : public QSharedData //krazy:exclude=dpointer (it's protected, which should be fine for this type of class)
97{
98 public:
99 /**
100 * Returns \c true if this ObjectDescription describes the same
101 * as \p otherDescription; otherwise returns \c false.
102 */
103 bool operator==(const ObjectDescriptionData &otherDescription) const;
104
105 /**
106 * Returns the name of the capture source.
107 *
108 * \return A string that should be presented to the user to
109 * choose the capture source.
110 */
111 QString name() const;
112
113 /**
114 * Returns a description of the capture source. This text should
115 * make clear what sound source this is, which is sometimes hard
116 * to describe or understand from just the name.
117 *
118 * \return A string describing the capture source.
119 */
120 QString description() const;
121
122 /**
123 * Returns a named property.
124 *
125 * If the property is not set an invalid value is returned.
126 *
127 * \see propertyNames()
128 */
129 QVariant property(const char *name) const;
130
131 /**
132 * Returns all names that return valid data when property() is called.
133 *
134 * \see property()
135 */
136 QList<QByteArray> propertyNames() const;
137
138 /**
139 * Returns \c true if the Tuple is valid (index != -1); otherwise returns
140 * \c false.
141 */
142 bool isValid() const;
143
144 /**
145 * A unique identifier for this device/. Used internally
146 * to distinguish between the devices/.
147 *
148 * \return An integer that uniquely identifies every device/
149 */
150 int index() const;
151
152 static ObjectDescriptionData *fromIndex(ObjectDescriptionType type, int index);
153
154 ~ObjectDescriptionData();
155
156 ObjectDescriptionData(ObjectDescriptionPrivate * = 0);
157 ObjectDescriptionData(int index, const QHash<QByteArray, QVariant> &properties);
158
159 protected:
160 ObjectDescriptionPrivate *const d;
161
162 private:
163 ObjectDescriptionData &operator=(const ObjectDescriptionData &rhs);
164};
165
166template<ObjectDescriptionType T> class ObjectDescriptionModel;
167
168/** \class ObjectDescription objectdescription.h Phonon/ObjectDescription
169 * \short Provides a tuple of enduser visible name and description.
170 *
171 * Some parts give the enduser choices, e.g. what source to capture audio from.
172 * These choices are described by the name and description methods of this class
173 * and identified with the id method. Subclasses then define additional
174 * information like which audio and video choices belong together.
175 *
176 * \ingroup Frontend
177 * \author Matthias Kretz <kretz@kde.org>
178 */
179template<ObjectDescriptionType T>
180class ObjectDescription
181{
182 public:
183 /**
184 * Returns a new description object that describes the
185 * device/effect/codec/... with the given \p index.
186 */
187 static inline ObjectDescription<T> fromIndex(int index) { //krazy:exclude=inline
188 return ObjectDescription<T>(QExplicitlySharedDataPointer<ObjectDescriptionData>(ObjectDescriptionData::fromIndex(T, index)));
189 }
190
191 /**
192 * Returns \c true if this ObjectDescription describes the same
193 * as \p otherDescription; otherwise returns \c false.
194 */
195 inline bool operator==(const ObjectDescription &otherDescription) const { //krazy:exclude=inline
196 return *d == *otherDescription.d;
197 }
198
199 /**
200 * Returns \c false if this ObjectDescription describes the same
201 * as \p otherDescription; otherwise returns \c true.
202 */
203 inline bool operator!=(const ObjectDescription &otherDescription) const { //krazy:exclude=inline
204 return !operator==(otherDescription);
205 }
206
207 /**
208 * Returns the name of the capture source.
209 *
210 * \return A string that should be presented to the user to
211 * choose the capture source.
212 */
213 inline QString name() const { return d->name(); } //krazy:exclude=inline
214
215 /**
216 * Returns a description of the capture source. This text should
217 * make clear what sound source this is, which is sometimes hard
218 * to describe or understand from just the name.
219 *
220 * \return A string describing the capture source.
221 */
222 inline QString description() const { return d->description(); } //krazy:exclude=inline
223
224 /**
225 * Returns a named property.
226 *
227 * If the property is not set an invalid value is returned.
228 *
229 * \see propertyNames()
230 */
231 inline QVariant property(const char *name) const { return d->property(name); } //krazy:exclude=inline
232
233 /**
234 * Returns all names that return valid data when property() is called.
235 *
236 * \see property()
237 */
238 inline QList<QByteArray> propertyNames() const { return d->propertyNames(); } //krazy:exclude=inline
239
240 /**
241 * Returns \c true if the Tuple is valid (index != -1); otherwise returns
242 * \c false.
243 */
244 inline bool isValid() const { return d->isValid(); } //krazy:exclude=inline
245
246 /**
247 * A unique identifier for this device/. Used internally
248 * to distinguish between the devices/.
249 *
250 * \return An integer that uniquely identifies every device/
251 */
252 inline int index() const { return d->index(); } //krazy:exclude=inline
253
254 ObjectDescription() : d(new ObjectDescriptionData(0)) {}
255 ObjectDescription(int index, const QHash<QByteArray, QVariant> &properties) : d(new ObjectDescriptionData(index, properties)) {}
256
257 protected:
258 friend class ObjectDescriptionModel<T>;
259 ObjectDescription(const QExplicitlySharedDataPointer<ObjectDescriptionData> &dd) : d(dd) {}
260 QExplicitlySharedDataPointer<ObjectDescriptionData> d;
261};
262
263template<ObjectDescriptionType T>
264inline QDebug operator<<(QDebug s, const ObjectDescription<T> &o) //krazy:exclude=inline
265{
266 return s << o.name();
267}
268
269/**
270 * \ingroup BackendInformation
271 */
272typedef ObjectDescription<AudioOutputDeviceType> AudioOutputDevice;
273/**
274 * \ingroup BackendInformation
275 */
276#ifndef QT_NO_PHONON_AUDIOCAPTURE
277typedef ObjectDescription<AudioCaptureDeviceType> AudioCaptureDevice;
278#endif //QT_NO_PHONON_AUDIOCAPTURE
279/**
280 * \ingroup BackendInformation
281 */
282//typedef ObjectDescription<VideoOutputDeviceType> VideoOutputDevice;
283/**
284 * \ingroup BackendInformation
285 */
286//typedef ObjectDescription<VideoCaptureDeviceType> VideoCaptureDevice;
287/**
288 * \ingroup BackendInformation
289 */
290#ifndef QT_NO_PHONON_EFFECT
291typedef ObjectDescription<EffectType> EffectDescription;
292#endif //QT_NO_PHONON_EFFECT
293
294/**
295 * \ingroup BackendInformation
296 */
297//typedef ObjectDescription<AudioCodecType> AudioCodecDescription;
298/**
299 * \ingroup BackendInformation
300 */
301//typedef ObjectDescription<VideoCodecType> VideoCodecDescription;
302/**
303 * \ingroup BackendInformation
304 */
305//typedef ObjectDescription<ContainerFormatType> ContainerFormatDescription;
306/**
307 * \ingroup BackendInformation
308 */
309//typedef ObjectDescription<VisualizationType> VisualizationDescription;
310#ifndef QT_NO_PHONON_MEDIACONTROLLER
311typedef ObjectDescription<AudioChannelType> AudioChannelDescription;
312typedef ObjectDescription<SubtitleType> SubtitleDescription;
313#endif //QT_NO_PHONON_MEDIACONTROLLER
314
315} //namespace Phonon
316
317QT_END_NAMESPACE
318
319Q_DECLARE_METATYPE(Phonon::AudioOutputDevice)
320Q_DECLARE_METATYPE(QList<Phonon::AudioOutputDevice>)
321
322#ifndef QT_NO_PHONON_AUDIOCAPTURE
323Q_DECLARE_METATYPE(Phonon::AudioCaptureDevice)
324Q_DECLARE_METATYPE(QList<Phonon::AudioCaptureDevice>)
325#endif //QT_NO_PHONON_AUDIOCAPTURE
326
327#ifndef QT_NO_PHONON_EFFECT
328Q_DECLARE_METATYPE(QList<Phonon::EffectDescription>)
329Q_DECLARE_METATYPE(Phonon::EffectDescription)
330#endif //QT_NO_PHONON_EFFECT
331
332
333#ifndef QT_NO_PHONON_MEDIACONTROLLER
334Q_DECLARE_METATYPE(Phonon::AudioChannelDescription)
335Q_DECLARE_METATYPE(Phonon::SubtitleDescription)
336Q_DECLARE_METATYPE(QList<Phonon::AudioChannelDescription>)
337Q_DECLARE_METATYPE(QList<Phonon::SubtitleDescription>)
338#endif //QT_NO_PHONON_MEDIACONTROLLER
339
340QT_END_HEADER
341
342#endif // PHONON_OBJECTDESCRIPTION_H
343