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 <QtCore/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: ~AudioOutputInterface40()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 conjuction with PulseSupport 139 * to either get the property set for the associated PulseAudio straem or 140 * to automatically apply them to the envrionment. 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 envrionment 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