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_BACKENDINTERFACE_H |
24 | #define PHONON_BACKENDINTERFACE_H |
25 | |
26 | #include "phonon_export.h" |
27 | #include "objectdescription.h" |
28 | |
29 | #include <QtGlobal> |
30 | #include <QSet> |
31 | |
32 | |
33 | class QVariant; |
34 | |
35 | namespace Phonon |
36 | { |
37 | |
38 | /** \class BackendInterface backendinterface.h phonon/BackendInterface |
39 | * \short Main Backend class interface |
40 | * |
41 | * This interface defines the main factory of the backend. The createObject function creates all the |
42 | * objects needed by the frontend. |
43 | * |
44 | * The objectDescriptionIndexes and objectDescriptionProperties functions return information about |
45 | * available devices, effects and codecs. |
46 | * |
47 | * An implementation could look like this: |
48 | * \code |
49 | * QObject *Backend::createObject(BackendInterface::Class c, QObject *parent, const QList<QVariant> &args) |
50 | * { |
51 | * switch (c) { |
52 | * case MediaObjectClass: |
53 | * return new MediaObject(parent); |
54 | * case VolumeFaderEffectClass: |
55 | * return new VolumeFaderEffect(parent); |
56 | * case AudioOutputClass: |
57 | * return new AudioOutput(parent); |
58 | * case AudioDataOutputClass: |
59 | * return new AudioDataOutput(parent); |
60 | * case VisualizationClass: |
61 | * return new Visualization(parent); |
62 | * case VideoDataOutputClass: |
63 | * return new VideoDataOutput(parent); |
64 | * case EffectClass: |
65 | * return new Effect(args[0].toInt(), parent); |
66 | * case VideoWidgetClass: |
67 | * return new VideoWidget(qobject_cast<QWidget *>(parent)); |
68 | * } |
69 | * return 0; |
70 | * } |
71 | * |
72 | * QSet<int> Backend::objectDescriptionIndexes(ObjectDescriptionType type) const |
73 | * { |
74 | * QSet<int> set; |
75 | * switch(type) |
76 | * { |
77 | * case Phonon::AudioOutputDeviceType: |
78 | * // use AudioDeviceEnumerator to list ALSA and OSS devices |
79 | * set << 10000 << 10001; |
80 | * break; |
81 | * case Phonon::AudioCaptureDeviceType: |
82 | * set << 20000 << 20001; |
83 | * break; |
84 | * case Phonon::VideoOutputDeviceType: |
85 | * break; |
86 | * case Phonon::VideoCaptureDeviceType: |
87 | * set << 30000 << 30001; |
88 | * break; |
89 | * case Phonon::VisualizationType: |
90 | * case Phonon::AudioCodecType: |
91 | * case Phonon::VideoCodecType: |
92 | * case Phonon::ContainerFormatType: |
93 | * break; |
94 | * case Phonon::EffectType: |
95 | * set << 0x7F000001; |
96 | * break; |
97 | * } |
98 | * return set; |
99 | * } |
100 | * |
101 | * QHash<QByteArray, QVariant> Backend::objectDescriptionProperties(ObjectDescriptionType type, int index) const |
102 | * { |
103 | * QHash<QByteArray, QVariant> ret; |
104 | * switch (type) { |
105 | * case Phonon::AudioOutputDeviceType: |
106 | * switch (index) { |
107 | * case 10000: |
108 | * ret.insert("name", QLatin1String("internal Soundcard")); |
109 | * break; |
110 | * case 10001: |
111 | * ret.insert("name", QLatin1String("USB Headset")); |
112 | * ret.insert("icon", KIcon("usb-headset")); |
113 | * ret.insert("available", false); |
114 | * break; |
115 | * } |
116 | * break; |
117 | * case Phonon::AudioCaptureDeviceType: |
118 | * switch (index) { |
119 | * case 20000: |
120 | * ret.insert("name", QLatin1String("Soundcard")); |
121 | * ret.insert("description", QLatin1String("first description")); |
122 | * break; |
123 | * case 20001: |
124 | * ret.insert("name", QLatin1String("DV")); |
125 | * ret.insert("description", QLatin1String("second description")); |
126 | * break; |
127 | * } |
128 | * break; |
129 | * case Phonon::VideoOutputDeviceType: |
130 | * break; |
131 | * case Phonon::VideoCaptureDeviceType: |
132 | * switch (index) { |
133 | * case 30000: |
134 | * ret.insert("name", QLatin1String("USB Webcam")); |
135 | * ret.insert("description", QLatin1String("first description")); |
136 | * break; |
137 | * case 30001: |
138 | * ret.insert("name", QLatin1String("DV")); |
139 | * ret.insert("description", QLatin1String("second description")); |
140 | * break; |
141 | * } |
142 | * break; |
143 | * case Phonon::VisualizationType: |
144 | * break; |
145 | * case Phonon::AudioCodecType: |
146 | * break; |
147 | * case Phonon::VideoCodecType: |
148 | * break; |
149 | * case Phonon::ContainerFormatType: |
150 | * break; |
151 | * case Phonon::EffectType: |
152 | * switch (index) { |
153 | * case 0x7F000001: |
154 | * ret.insert("name", QLatin1String("Delay")); |
155 | * ret.insert("description", QLatin1String("Simple delay effect with time, feedback and level controls.")); |
156 | * break; |
157 | * } |
158 | * break; |
159 | * } |
160 | * return ret; |
161 | * } |
162 | * \endcode |
163 | * |
164 | * \author Matthias Kretz <kretz@kde.org> |
165 | */ |
166 | class BackendInterface |
167 | { |
168 | public: |
169 | /** |
170 | * \internal |
171 | * |
172 | * Silence gcc's warning. |
173 | */ |
174 | virtual ~BackendInterface() {} |
175 | |
176 | /** |
177 | * Classes that the createObject function has to handle. |
178 | */ |
179 | enum Class { |
180 | /** |
181 | * Request to return a %MediaObject object. |
182 | */ |
183 | MediaObjectClass, |
184 | /** |
185 | * Request to return a %VolumeFaderEffect object. |
186 | */ |
187 | VolumeFaderEffectClass, |
188 | /** |
189 | * Request to return a %AudioOutput object. |
190 | */ |
191 | AudioOutputClass, |
192 | /** |
193 | * Request to return a %AudioDataOutput object. |
194 | */ |
195 | AudioDataOutputClass, |
196 | /** |
197 | * Request to return a %Visualization object. |
198 | */ |
199 | VisualizationClass, |
200 | /** |
201 | * Request to return a %VideoDataOutput object. |
202 | */ |
203 | VideoDataOutputClass, |
204 | /** |
205 | * Request to return a %Effect object. |
206 | * |
207 | * Takes an additional int that specifies the effect Id. |
208 | */ |
209 | EffectClass, |
210 | /** |
211 | * Request to return a %VideoWidget object. |
212 | */ |
213 | VideoWidgetClass, |
214 | VideoGraphicsObjectClass /* < No longer needs implementing; legacy */ |
215 | }; |
216 | |
217 | /** |
218 | * Returns a new instance of the requested class. |
219 | * |
220 | * \param c The requested class. |
221 | * \param parent The parent object. |
222 | * \param args Additional arguments (documented in \ref Class). |
223 | */ |
224 | virtual QObject *createObject(Class c, QObject *parent, const QList<QVariant> &args = QList<QVariant>()) = 0; |
225 | |
226 | /** |
227 | * Returns the unique identifiers for the devices/effects/codecs of the given \p type. |
228 | * |
229 | * \param type see \ref ObjectDescriptionType |
230 | */ |
231 | virtual QList<int> objectDescriptionIndexes(ObjectDescriptionType type) const = 0; |
232 | |
233 | /** |
234 | * Given a unique identifier that was returned from objectDescriptionIndexes this function |
235 | * returns a hash mapping property names to values. |
236 | * |
237 | * The property "name" must always be present. All other properties are optional. |
238 | * |
239 | * List of possible properties: |
240 | * \li \c \b name: The name of the device/effect/codec/... |
241 | * \li \c \b description: A text explaining what this device/effect/codec/... is/can do |
242 | * \li \c \b icon: An icon name (using the freedesktop naming scheme) or a QIcon for this |
243 | * device/effect/codec/... |
244 | * \li \c \b available: A bool telling whether the device is present or unplugged. |
245 | * |
246 | * \param type see \ref ObjectDescriptionType |
247 | * \param index The unique identifier that is returned from objectDescriptionIndexes |
248 | */ |
249 | virtual QHash<QByteArray, QVariant> objectDescriptionProperties(ObjectDescriptionType type, int index) const = 0; |
250 | |
251 | /** |
252 | * When this function is called the nodes given in the parameter list should not lose any |
253 | * signal data when connections are changed. |
254 | */ |
255 | virtual bool startConnectionChange(QSet<QObject *>) = 0; |
256 | |
257 | /** |
258 | * Defines a signal connection between the two given nodes. |
259 | */ |
260 | virtual bool connectNodes(QObject *, QObject *) = 0; |
261 | |
262 | /** |
263 | * Cuts a signal connection between the two given nodes. |
264 | */ |
265 | virtual bool disconnectNodes(QObject *, QObject *) = 0; |
266 | |
267 | /** |
268 | * When this function is called the nodes given in the parameter list may lose |
269 | * signal data when a port is not connected. |
270 | */ |
271 | virtual bool endConnectionChange(QSet<QObject *>) = 0; |
272 | |
273 | /** |
274 | * gets all available mime types |
275 | */ |
276 | virtual QStringList availableMimeTypes() const = 0; |
277 | |
278 | }; |
279 | } // namespace Phonon |
280 | |
281 | Q_DECLARE_INTERFACE(Phonon::BackendInterface, "BackendInterface3.phonon.kde.org" ) |
282 | |
283 | |
284 | #endif // PHONON_BACKENDINTERFACE_H |
285 | |