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
31QT_BEGIN_HEADER
32QT_BEGIN_NAMESPACE
33
34namespace 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 */
49class 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
91class 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
139namespace Phonon { typedef AudioOutputInterface42 AudioOutputInterface; }
140Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface40, "AudioOutputInterface2.phonon.kde.org")
141Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "3AudioOutputInterface.phonon.kde.org")
142#else
143namespace Phonon { typedef AudioOutputInterface40 AudioOutputInterface; }
144Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface, "AudioOutputInterface2.phonon.kde.org")
145Q_DECLARE_INTERFACE(Phonon::AudioOutputInterface42, "3AudioOutputInterface.phonon.kde.org")
146#endif
147
148QT_END_NAMESPACE
149QT_END_HEADER
150
151#endif // PHONON_AUDIOOUTPUTINTERFACE_H
152