File indexing completed on 2025-02-09 05:31:53
0001 /* This file is part of the KDE project 0002 Copyright (C) 2009 Colin Guthrie <cguthrie@mandriva.org> 0003 0004 This library is free software; you can redistribute it and/or 0005 modify it under the terms of the GNU Lesser General Public 0006 License as published by the Free Software Foundation; either 0007 version 2.1 of the License, or (at your option) version 3, or any 0008 later version accepted by the membership of KDE e.V. (or its 0009 successor approved by the membership of KDE e.V.), Nokia Corporation 0010 (or its successors, if any) and the KDE Free Qt Foundation, which shall 0011 act as a proxy defined in Section 6 of version 3 of the license. 0012 0013 This library is distributed in the hope that it will be useful, 0014 but WITHOUT ANY WARRANTY; without even the implied warranty of 0015 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0016 Lesser General Public License for more details. 0017 0018 You should have received a copy of the GNU Lesser General Public 0019 License along with this library. If not, see <http://www.gnu.org/licenses/>. 0020 0021 */ 0022 0023 #ifndef PHONON_PULSESUPPORT_H 0024 #define PHONON_PULSESUPPORT_H 0025 0026 #include "phonon_export.h" 0027 #include "phononnamespace.h" 0028 #include "objectdescription.h" 0029 0030 #include <QtGlobal> 0031 #include <QSet> 0032 0033 0034 namespace Phonon 0035 { 0036 class PulseStream; 0037 class PHONON_EXPORT PulseSupport : public QObject 0038 { 0039 Q_OBJECT 0040 public: 0041 /** 0042 * \returns the instance pointer or null, see note. 0043 * \note If \param allowNull is \c true and the instance was already 0044 * shut down this function instead returns to indicate that 0045 * the instance was already shut down. 0046 * If \param allowNull is \c false and the instance was already 0047 * shut down a dummy instance is returned instead. This case 0048 * will furthermore result in a qWarning being printed, so 0049 * when possible and sensible null handling should be done 0050 * to prevent this. 0051 */ 0052 static PulseSupport *getInstanceOrNull(bool allowNull = false); 0053 /** This function behaves like getInstanceOrNull(false). \see getInstanceOrNull */ 0054 static PulseSupport *getInstance(); 0055 static void shutdown(); 0056 0057 /** 0058 * Whether or not PulseSupport is actively able to intercept calls. 0059 * 0060 * This is: 0061 * - isUsable() 0062 * - isRequested() 0063 * - has been enabled by the backend 0064 * 0065 * @return \c true if usable, requested and enabled 0066 */ 0067 bool isActive(); 0068 0069 /** 0070 * Whether or not pulseaudio is used. This does not mean it is 0071 * meant to intercept calls meant for the backend. It simply 0072 * indicates that the backend is using pulseaudio. 0073 * 0074 * This is: 0075 * - isUsable() 0076 * - isRequested() 0077 * 0078 * @return \c true if pulesaudio can be used, \c false otherwise 0079 * 0080 * @since 4.9.0 0081 */ 0082 bool isUsed(); 0083 0084 /** 0085 * Whether or not pulseaudio can be used. 0086 * 0087 * This is 0088 * - pulseaudiod is running 0089 * - pulseaudiod can be connected to 0090 * 0091 * @return \c true if pulseaudio can be used 0092 */ 0093 bool isUsable() const; 0094 0095 /** 0096 * Whether or not the backend has requested that it wants to use 0097 * pulseaudio. This does *not* mean the backend wants pulseaudio 0098 * support to intercept calls. 0099 * 0100 * @return \c true if the backend has requested to use pulseaudio. 0101 * 0102 * @since 4.9.0 0103 */ 0104 bool isRequested() const; 0105 0106 /** 0107 * Backends can use this to request pulseaudio usage, without 0108 * enabling the interception. 0109 * 0110 * @see enable for requesting pulseaudio and forcing interception 0111 * 0112 * @param requested whether or not the backend would like the 0113 * frontend to use pulseaudio (e.g. list devices) 0114 * 0115 * @since 4.9.0 0116 */ 0117 void request(bool requested); 0118 0119 /** 0120 * Enable pulse support. This implies a backend request. 0121 * @param enabled 0122 */ 0123 void enable(bool enabled = true); 0124 0125 QList<int> objectDescriptionIndexes(ObjectDescriptionType type) const; 0126 QHash<QByteArray, QVariant> objectDescriptionProperties(ObjectDescriptionType type, int index) const; 0127 QList<int> objectIndexesByCategory(ObjectDescriptionType type, Category category) const; 0128 QList<int> objectIndexesByCategory(ObjectDescriptionType type, CaptureCategory category) const; 0129 0130 void setOutputDevicePriorityForCategory(Category category, QList<int> order); 0131 void setCaptureDevicePriorityForCategory(CaptureCategory category, QList<int> order); 0132 0133 PHONON_DEPRECATED void setCaptureDevicePriorityForCategory(Category category, QList<int> order); 0134 0135 PulseStream *registerOutputStream(QString streamUuid, Category category); 0136 PulseStream *registerCaptureStream(QString streamUuid, CaptureCategory category); 0137 PHONON_DEPRECATED PulseStream *registerCaptureStream(QString streamUuid, Category category); 0138 0139 /** 0140 * Whenever possible this function should be used to get Phonon 0141 * specific PulseAudio stream properties and set them on specific 0142 * streams. When precisely setting them per stream is not possible 0143 * the environment setup function PulseSupport::setupStreamEnvironment 0144 * should be called as close to stream creation as possible. The 0145 * more time passes between setup and stream creation the more 0146 * likely race conditions between setup of more than one AudioOutput 0147 * will appear. 0148 * 0149 * \param streamUuid the AudioOutputs' stream UUID set by the frontend through 0150 * AudioOutputInterface47::setStreamUuid 0151 * 0152 * \returns a hash of all properties set by setupStreamEnvironment 0153 * 0154 * \see setupStreamEnvironment 0155 * \since 4.7.0 0156 */ 0157 QHash<QString, QString> streamProperties(QString streamUuid) const; 0158 0159 /** 0160 * Sets PulseAudio override properties in the process' environment. 0161 * Manually setting the properties on a per-stream basis is 0162 * preferred as environment overrides are subject to race conditions 0163 * when creating more than one stream around the same time. 0164 * 0165 * \param streamUuid the AudioOutputs' stream UUID set by the frontend 0166 * through AudioOutputInterface47::setStreamUuid 0167 * 0168 * \see streamProperties 0169 * \since 4.7.0 0170 */ 0171 void setupStreamEnvironment(QString streamUuid); 0172 0173 void emitObjectDescriptionChanged(ObjectDescriptionType); 0174 0175 bool setOutputName(QString streamUuid, QString name); 0176 bool setOutputDevice(QString streamUuid, int device); 0177 bool setOutputVolume(QString streamUuid, qreal volume); 0178 bool setOutputMute(QString streamUuid, bool mute); 0179 bool setCaptureDevice(QString streamUuid, int device); 0180 // NB Capture Volume/Mute not set until PA supports per-source-output volumes/mutes 0181 // or phonon supports capture properly... which ever comes first. 0182 void clearStreamCache(QString streamUuid); 0183 0184 static void debug(); 0185 public Q_SLOTS: 0186 void connectToDaemon(); 0187 0188 Q_SIGNALS: 0189 void objectDescriptionChanged(ObjectDescriptionType); 0190 0191 private: 0192 PulseSupport(); 0193 ~PulseSupport() override; 0194 0195 bool mEnabled; 0196 bool m_requested; 0197 }; 0198 } // namespace Phonon 0199 0200 0201 #endif // PHONON_PULSESUPPORT_H