1/* This file is part of the KDE project
2 Copyright (C) 2009 Colin Guthrie <cguthrie@mandriva.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_PULSESUPPORT_H
24#define PHONON_PULSESUPPORT_H
25
26#include "phonon_export.h"
27#include "phononnamespace.h"
28#include "objectdescription.h"
29
30#include <QtGlobal>
31#include <QSet>
32
33
34namespace Phonon
35{
36 class PulseStream;
37 class PHONON_EXPORT PulseSupport : public QObject
38 {
39 Q_OBJECT
40 public:
41 /**
42 * \returns the instance pointer or null, see note.
43 * \note If \param allowNull is \c true and the instance was already
44 * shut down this function instead returns to indicate that
45 * the instance was already shut down.
46 * If \param allowNull is \c false and the instance was already
47 * shut down a dummy instance is returned instead. This case
48 * will furthermore result in a qWarning being printed, so
49 * when possible and sensible null handling should be done
50 * to prevent this.
51 */
52 static PulseSupport *getInstanceOrNull(bool allowNull = false);
53 /** This function behaves like getInstanceOrNull(false). \see getInstanceOrNull */
54 static PulseSupport *getInstance();
55 static void shutdown();
56
57 /**
58 * Whether or not PulseSupport is actively able to intercept calls.
59 *
60 * This is:
61 * - isUsable()
62 * - isRequested()
63 * - has been enabled by the backend
64 *
65 * @return \c true if usable, requested and enabled
66 */
67 bool isActive();
68
69 /**
70 * Whether or not pulseaudio is used. This does not mean it is
71 * meant to intercept calls meant for the backend. It simply
72 * indicates that the backend is using pulseaudio.
73 *
74 * This is:
75 * - isUsable()
76 * - isRequested()
77 *
78 * @return \c true if pulesaudio can be used, \c false otherwise
79 *
80 * @since 4.9.0
81 */
82 bool isUsed();
83
84 /**
85 * Whether or not pulseaudio can be used.
86 *
87 * This is
88 * - pulseaudiod is running
89 * - pulseaudiod can be connected to
90 *
91 * @return \c true if pulseaudio can be used
92 */
93 bool isUsable() const;
94
95 /**
96 * Whether or not the backend has requested that it wants to use
97 * pulseaudio. This does *not* mean the backend wants pulseaudio
98 * support to intercept calls.
99 *
100 * @return \c true if the backend has requested to use pulseaudio.
101 *
102 * @since 4.9.0
103 */
104 bool isRequested() const;
105
106 /**
107 * Backends can use this to request pulseaudio usage, without
108 * enabling the interception.
109 *
110 * @see enable for requesting pulseaudio and forcing interception
111 *
112 * @param requested whether or not the backend would like the
113 * frontend to use pulseaudio (e.g. list devices)
114 *
115 * @since 4.9.0
116 */
117 void request(bool requested);
118
119 /**
120 * Enable pulse support. This implies a backend request.
121 * @param enabled
122 */
123 void enable(bool enabled = true);
124
125 QList<int> objectDescriptionIndexes(ObjectDescriptionType type) const;
126 QHash<QByteArray, QVariant> objectDescriptionProperties(ObjectDescriptionType type, int index) const;
127 QList<int> objectIndexesByCategory(ObjectDescriptionType type, Category category) const;
128 QList<int> objectIndexesByCategory(ObjectDescriptionType type, CaptureCategory category) const;
129
130 void setOutputDevicePriorityForCategory(Category category, QList<int> order);
131 void setCaptureDevicePriorityForCategory(CaptureCategory category, QList<int> order);
132
133 PHONON_DEPRECATED void setCaptureDevicePriorityForCategory(Category category, QList<int> order);
134
135 PulseStream *registerOutputStream(QString streamUuid, Category category);
136 PulseStream *registerCaptureStream(QString streamUuid, CaptureCategory category);
137 PHONON_DEPRECATED PulseStream *registerCaptureStream(QString streamUuid, Category category);
138
139 /**
140 * Whenever possible this function should be used to get Phonon
141 * specific PulseAudio stream properties and set them on specific
142 * streams. When precisely setting them per stream is not possible
143 * the environment setup function PulseSupport::setupStreamEnvironment
144 * should be called as close to stream creation as possible. The
145 * more time passes between setup and stream creation the more
146 * likely race conditions between setup of more than one AudioOutput
147 * will appear.
148 *
149 * \param streamUuid the AudioOutputs' stream UUID set by the frontend through
150 * AudioOutputInterface47::setStreamUuid
151 *
152 * \returns a hash of all properties set by setupStreamEnvironment
153 *
154 * \see setupStreamEnvironment
155 * \since 4.7.0
156 */
157 QHash<QString, QString> streamProperties(QString streamUuid) const;
158
159 /**
160 * Sets PulseAudio override properties in the process' environment.
161 * Manually setting the properties on a per-stream basis is
162 * preferred as environment overrides are subject to race conditions
163 * when creating more than one stream around the same time.
164 *
165 * \param streamUuid the AudioOutputs' stream UUID set by the frontend
166 * through AudioOutputInterface47::setStreamUuid
167 *
168 * \see streamProperties
169 * \since 4.7.0
170 */
171 void setupStreamEnvironment(QString streamUuid);
172
173 void emitObjectDescriptionChanged(ObjectDescriptionType);
174
175 bool setOutputName(QString streamUuid, QString name);
176 bool setOutputDevice(QString streamUuid, int device);
177 bool setOutputVolume(QString streamUuid, qreal volume);
178 bool setOutputMute(QString streamUuid, bool mute);
179 bool setCaptureDevice(QString streamUuid, int device);
180 // NB Capture Volume/Mute not set until PA supports per-source-output volumes/mutes
181 // or phonon supports capture properly... which ever comes first.
182 void clearStreamCache(QString streamUuid);
183
184 static void debug();
185 public Q_SLOTS:
186 void connectToDaemon();
187
188 Q_SIGNALS:
189 void objectDescriptionChanged(ObjectDescriptionType);
190
191 private:
192 PulseSupport();
193 ~PulseSupport() override;
194
195 bool mEnabled;
196 bool m_requested;
197 };
198} // namespace Phonon
199
200
201#endif // PHONON_PULSESUPPORT_H
202

source code of phonon/phonon/pulsesupport.h