File indexing completed on 2025-02-09 05:31:46
0001 /* 0002 Copyright (C) 2015-2016 Harald Sitter <sitter@kde.org> 0003 Copyright (C) 2007-2008 Matthias Kretz <kretz@kde.org> 0004 0005 This library is free software; you can redistribute it and/or 0006 modify it under the terms of the GNU Lesser General Public 0007 License as published by the Free Software Foundation; either 0008 version 2.1 of the License, or (at your option) version 3, or any 0009 later version accepted by the membership of KDE e.V. (or its 0010 successor approved by the membership of KDE e.V.), Nokia Corporation 0011 (or its successors, if any) and the KDE Free Qt Foundation, which shall 0012 act as a proxy defined in Section 6 of version 3 of the license. 0013 0014 This library is distributed in the hope that it will be useful, 0015 but WITHOUT ANY WARRANTY; without even the implied warranty of 0016 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0017 Lesser General Public License for more details. 0018 0019 You should have received a copy of the GNU Lesser General Public 0020 License along with this library. If not, see <http://www.gnu.org/licenses/>. 0021 0022 */ 0023 0024 #ifndef PHONON_AUDIOOUTPUTINTERFACE_H 0025 #define PHONON_AUDIOOUTPUTINTERFACE_H 0026 0027 #include "phononnamespace.h" 0028 #include "objectdescription.h" 0029 #include "phonondefs.h" 0030 #include <QtGlobal> 0031 0032 namespace Phonon 0033 { 0034 /** \class AudioOutputInterface audiooutputinterface.h phonon/AudioOutputInterface 0035 * \short Interface for AudioOutput objects 0036 * 0037 * The implementation can make use of the signals 0038 * \code 0039 void volumeChanged(qreal newVolume); 0040 void audioDeviceFailed(); 0041 * \endcode 0042 * to notify the frontend whenever the volume has changed or when an audioDeviceFailed (e.g. USB 0043 * unplug or sound server failure). 0044 * 0045 * \author Matthias Kretz <kretz@kde.org> 0046 */ 0047 class AudioOutputInterface40 0048 { 0049 public: 0050 virtual ~AudioOutputInterface40() {} 0051 0052 /** 0053 * Returns the current software volume. 0054 * 0055 * A value of 0.0 means muted, 1.0 means unchanged, 2.0 means double voltage (i.e. all 0056 * samples are multiplied by 2). 0057 */ 0058 virtual qreal volume() const = 0; 0059 /** 0060 * Sets the new current software volume. 0061 * 0062 * A value of 0.0 means muted, 1.0 means unchanged, 2.0 means double voltage (i.e. all 0063 * samples are multiplied by 2). 0064 * 0065 * Every time the volume in the backend changes it should emit volumeChanged(qreal), also 0066 * inside this function. 0067 */ 0068 virtual void setVolume(qreal) = 0; 0069 0070 /** 0071 * Returns the index of the device that is used. The index is the number returned from 0072 * BackendInterface::objectDescriptionIndexes(AudioOutputDeviceType). 0073 */ 0074 virtual int outputDevice() const = 0; 0075 /** 0076 * \deprecated 0077 * 0078 * Requests to change the current output device to the one identified by the passed index. 0079 * 0080 * The index is the number returned from 0081 * BackendInterface::objectDescriptionIndexes(AudioOutputDeviceType). 0082 * 0083 * \returns \c true if the requested device works and is used after this call. 0084 * \returns \c false if something failed and the device is not used after this call. 0085 */ 0086 virtual bool setOutputDevice(int) = 0; 0087 }; 0088 0089 class AudioOutputInterface42 : public AudioOutputInterface40 0090 { 0091 public: 0092 /** 0093 * Requests to change the current output device. 0094 * 0095 * \returns \c true if the requested device works and is used after this call. 0096 * \returns \c false if something failed and the device is not used after this call. 0097 */ 0098 virtual bool setOutputDevice(const Phonon::AudioOutputDevice &) = 0; 0099 0100 using AudioOutputInterface40::setOutputDevice; 0101 0102 /** 0103 * Helper function for backends to get a list of (driver, handle) pairs for 0104 * AudioOutputDevice objects that are listed by the platform plugin. 0105 * 0106 * Example: 0107 * \code 0108 typedef QPair<QByteArray, QString> PhononDeviceAccess; 0109 const QList<PhononDeviceAccess> &deviceAccessList = deviceAccessListFor(deviceDesc); 0110 foreach (const PhononDeviceAccess &access, deviceAccessList) { 0111 const QByteArray &driver = access.first; 0112 const QString &handle = access.second; 0113 if (openDevice(driver, handle)) { 0114 // we found the first pair in the list that works. done. 0115 return; 0116 } 0117 // continue trying the other (driver, handle) pairs 0118 } 0119 // none of the (driver, handle) pairs worked, that means the whole AudioOutputDevice is 0120 // inaccessible and the frontend needs to know (either by emitting audioDeviceFailed or 0121 // returning false when called from setOutputDevice) 0122 * \endcode 0123 * 0124 * At the time of this writing the following driver strings are known to be in use: 0125 * \li \c alsa: The handle is the string to pass to snd_pcm_open (e.g. "dmix:CARD=0,DEV=1") 0126 * \li \c oss: The handle is the device file (e.g. "/dev/dsp") 0127 * \li \c pulseaudio: The handle contains the server string and the sink/source name 0128 * separated by a newline character. 0129 * (e.g. unix:/tmp/pulse-mkretz/native\nalsa_output.pci_8086_293e_sound_card_0_alsa_playback_0) 0130 */ 0131 PHONON_EXPORT QList<QPair<QByteArray, QString> > deviceAccessListFor(const Phonon::AudioOutputDevice &) const; 0132 }; 0133 0134 class AudioOutputInterface47 : public AudioOutputInterface42 0135 { 0136 public: 0137 /** 0138 * This function is meant to be used in conjunction with PulseSupport 0139 * to either get the property set for the associated PulseAudio straem or 0140 * to automatically apply them to the environment. 0141 * 0142 * If a backend subsystem supports actively setting arbitrary properties 0143 * this method should be preferred and PulseSupport::streamProperties() 0144 * should be used. 0145 * If a backend subsystem does not support setting arbitrary properties 0146 * PulseSupport::setupStreamEnvironment() should be called as close to 0147 * stream creation as possible to manipulate the process environment 0148 * such that PulseAudio will pick up the properties. 0149 * 0150 * \param uuid the UUID used by PulseSupport to identify the associated stream 0151 * 0152 * \since 4.7.0 0153 */ 0154 virtual void setStreamUuid(QString uuid) = 0; 0155 }; 0156 0157 class AudioOutputInterface49 : public AudioOutputInterface47 0158 { 0159 public: 0160 /** 0161 * Mutes the output. 0162 * 0163 * \param mute \c true if it is supposed to get muted \c false if not 0164 * 0165 * \since 4.9.0 0166 */ 0167 virtual void setMuted(bool mute) = 0; 0168 0169 /** 0170 * SIGNAL emitted when the muteness of the output changes. 0171 * 0172 * \warning When implementing the 4.9 interface this signal MUST be emitted 0173 * from all relevant sources. 0174 * 0175 * This signal must be emitted whenever muteness is reached. 0176 * The signal must only be emitted if setMuted was called, reaching mutness 0177 * through other means (such as volume==0.0) does not count as muteness. 0178 * 0179 * \param mute \c true when the output is mute, \c false if it is not mute 0180 * 0181 * \since 4.9.0 0182 */ 0183 virtual void mutedChanged(bool mute) = 0; 0184 }; 0185 0186 class AudioOutputInterface410 : public AudioOutputInterface49 0187 { 0188 public: 0189 /** 0190 * Forwards the output category to the backend after construction. 0191 * The category is immutable so this is only called once, it is also never 0192 * read from the backend (hence the lack of a getter) as the backend gets 0193 * no choice in this matter. 0194 * @param category the category that was set on the output. 0195 */ 0196 virtual void setCategory(Phonon::Category category) = 0; 0197 }; 0198 0199 } // namespace Phonon 0200 0201 #ifdef PHONON_BACKEND_VERSION_4_10 0202 namespace Phonon { typedef AudioOutputInterface410 AudioOutputInterface; } 0203 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org") 0204 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org") 0205 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface47, "4AudioOutputInterface.phonon.kde.org") 0206 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface49, "5AudioOutputInterface.phonon.kde.org") 0207 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "6AudioOutputInterface.phonon.kde.org") 0208 #elif defined PHONON_BACKEND_VERSION_4_9 0209 namespace Phonon { typedef AudioOutputInterface49 AudioOutputInterface; } 0210 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org") 0211 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org") 0212 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface47, "4AudioOutputInterface.phonon.kde.org") 0213 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "5AudioOutputInterface.phonon.kde.org") 0214 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface410, "6AudioOutputInterface.phonon.kde.org") 0215 #elif defined PHONON_BACKEND_VERSION_4_7 0216 namespace Phonon { typedef AudioOutputInterface47 AudioOutputInterface; } 0217 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org") 0218 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org") 0219 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "4AudioOutputInterface.phonon.kde.org") 0220 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface49, "5AudioOutputInterface.phonon.kde.org") 0221 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface410, "6AudioOutputInterface.phonon.kde.org") 0222 #elif defined PHONON_BACKEND_VERSION_4_2 0223 namespace Phonon { typedef AudioOutputInterface42 AudioOutputInterface; } 0224 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org") 0225 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "3AudioOutputInterface.phonon.kde.org") 0226 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface47, "4AudioOutputInterface.phonon.kde.org") 0227 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface49, "5AudioOutputInterface.phonon.kde.org") 0228 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface410, "6AudioOutputInterface.phonon.kde.org") 0229 #else 0230 namespace Phonon { typedef AudioOutputInterface40 AudioOutputInterface; } 0231 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "AudioOutputInterface2.phonon.kde.org") 0232 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org") 0233 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface47, "4AudioOutputInterface.phonon.kde.org") 0234 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface49, "5AudioOutputInterface.phonon.kde.org") 0235 Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface410, "6AudioOutputInterface.phonon.kde.org") 0236 #endif 0237 0238 0239 #endif // PHONON_AUDIOOUTPUTINTERFACE_H