1 | /* This file is part of the KDE project |
2 | Copyright (C) 2007-2008 Matthias Kretz <kretz@kde.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_AUDIOOUTPUTINTERFACE_H |
24 | #define PHONON_AUDIOOUTPUTINTERFACE_H |
25 | |
26 | #include "phononnamespace.h" |
27 | #include "objectdescription.h" |
28 | #include "phonondefs.h" |
29 | #include <QtCore/QtGlobal> |
30 | |
31 | QT_BEGIN_HEADER |
32 | QT_BEGIN_NAMESPACE |
33 | |
34 | namespace Phonon |
35 | { |
36 | /** \class AudioOutputInterface audiooutputinterface.h Phonon/AudioOutputInterface |
37 | * \short Interface for AudioOutput objects |
38 | * |
39 | * The implementation can make use of the signals |
40 | * \code |
41 | void volumeChanged(qreal newVolume); |
42 | void audioDeviceFailed(); |
43 | * \endcode |
44 | * to notify the frontend whenever the volume has changed or when an audioDeviceFailed (e.g. USB |
45 | * unplug or sound server failure). |
46 | * |
47 | * \author Matthias Kretz <kretz@kde.org> |
48 | */ |
49 | class AudioOutputInterface40 |
50 | { |
51 | public: |
52 | virtual ~AudioOutputInterface40() {} |
53 | |
54 | /** |
55 | * Returns the current software volume. |
56 | * |
57 | * A value of 0.0 means muted, 1.0 means unchanged, 2.0 means double voltage (i.e. all |
58 | * samples are multiplied by 2). |
59 | */ |
60 | virtual qreal volume() const = 0; |
61 | /** |
62 | * Sets the new current software volume. |
63 | * |
64 | * A value of 0.0 means muted, 1.0 means unchanged, 2.0 means double voltage (i.e. all |
65 | * samples are multiplied by 2). |
66 | * |
67 | * Every time the volume in the backend changes it should emit volumeChanged(qreal), also |
68 | * inside this function. |
69 | */ |
70 | virtual void setVolume(qreal) = 0; |
71 | |
72 | /** |
73 | * Returns the index of the device that is used. The index is the number returned from |
74 | * BackendInterface::objectDescriptionIndexes(AudioOutputDeviceType). |
75 | */ |
76 | virtual int outputDevice() const = 0; |
77 | /** |
78 | * \deprecated |
79 | * |
80 | * Requests to change the current output device to the one identified by the passed index. |
81 | * |
82 | * The index is the number returned from |
83 | * BackendInterface::objectDescriptionIndexes(AudioOutputDeviceType). |
84 | * |
85 | * \returns \c true if the requested device works and is used after this call. |
86 | * \returns \c false if something failed and the device is not used after this call. |
87 | */ |
88 | virtual bool setOutputDevice(int) = 0; |
89 | }; |
90 | |
91 | class AudioOutputInterface42 : public AudioOutputInterface40 |
92 | { |
93 | public: |
94 | /** |
95 | * Requests to change the current output device. |
96 | * |
97 | * \returns \c true if the requested device works and is used after this call. |
98 | * \returns \c false if something failed and the device is not used after this call. |
99 | */ |
100 | virtual bool setOutputDevice(const Phonon::AudioOutputDevice &) = 0; |
101 | |
102 | using AudioOutputInterface40::setOutputDevice; |
103 | |
104 | /** |
105 | * Helper function for backends to get a list of (driver, handle) pairs for |
106 | * AudioOutputDevice objects that are listed by the platform plugin. |
107 | * |
108 | * Example: |
109 | * \code |
110 | typedef QPair<QByteArray, QString> PhononDeviceAccess; |
111 | const QList<PhononDeviceAccess> &deviceAccessList = deviceAccessListFor(deviceDesc); |
112 | foreach (const PhononDeviceAccess &access, deviceAccessList) { |
113 | const QByteArray &driver = access.first; |
114 | const QString &handle = access.second; |
115 | if (openDevice(driver, handle)) { |
116 | // we found the first pair in the list that works. done. |
117 | return; |
118 | } |
119 | // continue trying the other (driver, handle) pairs |
120 | } |
121 | // none of the (driver, handle) pairs worked, that means the whole AudioOutputDevice is |
122 | // inaccessible and the frontend needs to know (either by emitting audioDeviceFailed or |
123 | // returning false when called from setOutputDevice) |
124 | * \endcode |
125 | * |
126 | * At the time of this writing the following driver strings are known to be in use: |
127 | * \li \c alsa: The handle is the string to pass to snd_pcm_open (e.g. "dmix:CARD=0,DEV=1") |
128 | * \li \c oss: The handle is the device file (e.g. "/dev/dsp") |
129 | * \li \c pulseaudio: The handle contains the server string and the sink/source name |
130 | * separated by a newline character. |
131 | * (e.g. unix:/tmp/pulse-mkretz/native\nalsa_output.pci_8086_293e_sound_card_0_alsa_playback_0) |
132 | */ |
133 | PHONON_EXPORT QList<QPair<QByteArray, QString> > deviceAccessListFor(const Phonon::AudioOutputDevice &) const; |
134 | }; |
135 | |
136 | } // namespace Phonon |
137 | |
138 | #ifdef PHONON_BACKEND_VERSION_4_2 |
139 | namespace Phonon { typedef AudioOutputInterface42 AudioOutputInterface; } |
140 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org" ) |
141 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "3AudioOutputInterface.phonon.kde.org" ) |
142 | #else |
143 | namespace Phonon { typedef AudioOutputInterface40 AudioOutputInterface; } |
144 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "AudioOutputInterface2.phonon.kde.org" ) |
145 | Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org" ) |
146 | #endif |
147 | |
148 | QT_END_NAMESPACE |
149 | QT_END_HEADER |
150 | |
151 | #endif // PHONON_AUDIOOUTPUTINTERFACE_H |
152 | |