1 | /* |
2 | Copyright (C) 2015-2016 Harald Sitter <sitter@kde.org> |
3 | Copyright (C) 2007-2008 Matthias Kretz <kretz@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 | |
24 | #ifndef PHONON_AUDIOOUTPUTINTERFACE_H |
25 | #define PHONON_AUDIOOUTPUTINTERFACE_H |
26 | |
27 | #include "phononnamespace.h" |
28 | #include "objectdescription.h" |
29 | #include "phonondefs.h" |
30 | #include <QtGlobal> |
31 | |
32 | namespace Phonon |
33 | { |
34 | /** \class AudioOutputInterface audiooutputinterface.h phonon/AudioOutputInterface |
35 | * \short Interface for AudioOutput objects |
36 | * |
37 | * The implementation can make use of the signals |
38 | * \code |
39 | void volumeChanged(qreal newVolume); |
40 | void audioDeviceFailed(); |
41 | * \endcode |
42 | * to notify the frontend whenever the volume has changed or when an audioDeviceFailed (e.g. USB |
43 | * unplug or sound server failure). |
44 | * |
45 | * \author Matthias Kretz <kretz@kde.org> |
46 | */ |
47 | class AudioOutputInterface40 |
48 | { |
49 | public: |
50 | virtual ~AudioOutputInterface40() {} |
51 | |
52 | /** |
53 | * Returns the current software volume. |
54 | * |
55 | * A value of 0.0 means muted, 1.0 means unchanged, 2.0 means double voltage (i.e. all |
56 | * samples are multiplied by 2). |
57 | */ |
58 | virtual qreal volume() const = 0; |
59 | /** |
60 | * Sets the new current software volume. |
61 | * |
62 | * A value of 0.0 means muted, 1.0 means unchanged, 2.0 means double voltage (i.e. all |
63 | * samples are multiplied by 2). |
64 | * |
65 | * Every time the volume in the backend changes it should emit volumeChanged(qreal), also |
66 | * inside this function. |
67 | */ |
68 | virtual void setVolume(qreal) = 0; |
69 | |
70 | /** |
71 | * Returns the index of the device that is used. The index is the number returned from |
72 | * BackendInterface::objectDescriptionIndexes(AudioOutputDeviceType). |
73 | */ |
74 | virtual int outputDevice() const = 0; |
75 | /** |
76 | * \deprecated |
77 | * |
78 | * Requests to change the current output device to the one identified by the passed index. |
79 | * |
80 | * The index is the number returned from |
81 | * BackendInterface::objectDescriptionIndexes(AudioOutputDeviceType). |
82 | * |
83 | * \returns \c true if the requested device works and is used after this call. |
84 | * \returns \c false if something failed and the device is not used after this call. |
85 | */ |
86 | virtual bool setOutputDevice(int) = 0; |
87 | }; |
88 | |
89 | class AudioOutputInterface42 : public AudioOutputInterface40 |
90 | { |
91 | public: |
92 | /** |
93 | * Requests to change the current output device. |
94 | * |
95 | * \returns \c true if the requested device works and is used after this call. |
96 | * \returns \c false if something failed and the device is not used after this call. |
97 | */ |
98 | virtual bool setOutputDevice(const Phonon::AudioOutputDevice &) = 0; |
99 | |
100 | using AudioOutputInterface40::setOutputDevice; |
101 | |
102 | /** |
103 | * Helper function for backends to get a list of (driver, handle) pairs for |
104 | * AudioOutputDevice objects that are listed by the platform plugin. |
105 | * |
106 | * Example: |
107 | * \code |
108 | typedef QPair<QByteArray, QString> PhononDeviceAccess; |
109 | const QList<PhononDeviceAccess> &deviceAccessList = deviceAccessListFor(deviceDesc); |
110 | foreach (const PhononDeviceAccess &access, deviceAccessList) { |
111 | const QByteArray &driver = access.first; |
112 | const QString &handle = access.second; |
113 | if (openDevice(driver, handle)) { |
114 | // we found the first pair in the list that works. done. |
115 | return; |
116 | } |
117 | // continue trying the other (driver, handle) pairs |
118 | } |
119 | // none of the (driver, handle) pairs worked, that means the whole AudioOutputDevice is |
120 | // inaccessible and the frontend needs to know (either by emitting audioDeviceFailed or |
121 | // returning false when called from setOutputDevice) |
122 | * \endcode |
123 | * |
124 | * At the time of this writing the following driver strings are known to be in use: |
125 | * \li \c alsa: The handle is the string to pass to snd_pcm_open (e.g. "dmix:CARD=0,DEV=1") |
126 | * \li \c oss: The handle is the device file (e.g. "/dev/dsp") |
127 | * \li \c pulseaudio: The handle contains the server string and the sink/source name |
128 | * separated by a newline character. |
129 | * (e.g. unix:/tmp/pulse-mkretz/native\nalsa_output.pci_8086_293e_sound_card_0_alsa_playback_0) |
130 | */ |
131 | PHONON_EXPORT QList<QPair<QByteArray, QString> > deviceAccessListFor(const Phonon::AudioOutputDevice &) const; |
132 | }; |
133 | |
134 | class AudioOutputInterface47 : public AudioOutputInterface42 |
135 | { |
136 | public: |
137 | /** |
138 | * This function is meant to be used in conjunction with PulseSupport |
139 | * to either get the property set for the associated PulseAudio straem or |
140 | * to automatically apply them to the environment. |
141 | * |
142 | * If a backend subsystem supports actively setting arbitrary properties |
143 | * this method should be preferred and PulseSupport::streamProperties() |
144 | * should be used. |
145 | * If a backend subsystem does not support setting arbitrary properties |
146 | * PulseSupport::setupStreamEnvironment() should be called as close to |
147 | * stream creation as possible to manipulate the process environment |
148 | * such that PulseAudio will pick up the properties. |
149 | * |
150 | * \param uuid the UUID used by PulseSupport to identify the associated stream |
151 | * |
152 | * \since 4.7.0 |
153 | */ |
154 | virtual void setStreamUuid(QString uuid) = 0; |
155 | }; |
156 | |
157 | class AudioOutputInterface49 : public AudioOutputInterface47 |
158 | { |
159 | public: |
160 | /** |
161 | * Mutes the output. |
162 | * |
163 | * \param mute \c true if it is supposed to get muted \c false if not |
164 | * |
165 | * \since 4.9.0 |
166 | */ |
167 | virtual void setMuted(bool mute) = 0; |
168 | |
169 | /** |
170 | * SIGNAL emitted when the muteness of the output changes. |
171 | * |
172 | * \warning When implementing the 4.9 interface this signal MUST be emitted |
173 | * from all relevant sources. |
174 | * |
175 | * This signal must be emitted whenever muteness is reached. |
176 | * The signal must only be emitted if setMuted was called, reaching mutness |
177 | * through other means (such as volume==0.0) does not count as muteness. |
178 | * |
179 | * \param mute \c true when the output is mute, \c false if it is not mute |
180 | * |
181 | * \since 4.9.0 |
182 | */ |
183 | virtual void mutedChanged(bool mute) = 0; |
184 | }; |
185 | |
186 | class AudioOutputInterface410 : public AudioOutputInterface49 |
187 | { |
188 | public: |
189 | /** |
190 | * Forwards the output category to the backend after construction. |
191 | * The category is immutable so this is only called once, it is also never |
192 | * read from the backend (hence the lack of a getter) as the backend gets |
193 | * no choice in this matter. |
194 | * @param category the category that was set on the output. |
195 | */ |
196 | virtual void setCategory(Phonon::Category category) = 0; |
197 | }; |
198 | |
199 | } // namespace Phonon |
200 | |
201 | #ifdef PHONON_BACKEND_VERSION_4_10 |
202 | namespace Phonon { typedef AudioOutputInterface410 AudioOutputInterface; } |
203 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org" ) |
204 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org" ) |
205 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface47, "4AudioOutputInterface.phonon.kde.org" ) |
206 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface49, "5AudioOutputInterface.phonon.kde.org" ) |
207 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "6AudioOutputInterface.phonon.kde.org" ) |
208 | #elif defined PHONON_BACKEND_VERSION_4_9 |
209 | namespace Phonon { typedef AudioOutputInterface49 AudioOutputInterface; } |
210 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org" ) |
211 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org" ) |
212 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface47, "4AudioOutputInterface.phonon.kde.org" ) |
213 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "5AudioOutputInterface.phonon.kde.org" ) |
214 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface410, "6AudioOutputInterface.phonon.kde.org" ) |
215 | #elif defined PHONON_BACKEND_VERSION_4_7 |
216 | namespace Phonon { typedef AudioOutputInterface47 AudioOutputInterface; } |
217 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org" ) |
218 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org" ) |
219 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "4AudioOutputInterface.phonon.kde.org" ) |
220 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface49, "5AudioOutputInterface.phonon.kde.org" ) |
221 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface410, "6AudioOutputInterface.phonon.kde.org" ) |
222 | #elif defined PHONON_BACKEND_VERSION_4_2 |
223 | namespace Phonon { typedef AudioOutputInterface42 AudioOutputInterface; } |
224 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org" ) |
225 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "3AudioOutputInterface.phonon.kde.org" ) |
226 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface47, "4AudioOutputInterface.phonon.kde.org" ) |
227 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface49, "5AudioOutputInterface.phonon.kde.org" ) |
228 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface410, "6AudioOutputInterface.phonon.kde.org" ) |
229 | #else |
230 | namespace Phonon { typedef AudioOutputInterface40 AudioOutputInterface; } |
231 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "AudioOutputInterface2.phonon.kde.org" ) |
232 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org" ) |
233 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface47, "4AudioOutputInterface.phonon.kde.org" ) |
234 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface49, "5AudioOutputInterface.phonon.kde.org" ) |
235 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface410, "6AudioOutputInterface.phonon.kde.org" ) |
236 | #endif |
237 | |
238 | |
239 | #endif // PHONON_AUDIOOUTPUTINTERFACE_H |
240 | |