runtime/phonon/libkaudiodevicelist/audiodevice.h

   1 /*  This file is part of the KDE project
   2     Copyright (C) 2006 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 Library General Public
   6     License version 2 as published by the Free Software Foundation.
   7
   8     This library is distributed in the hope that it will be useful,
   9     but WITHOUT ANY WARRANTY; without even the implied warranty of
  10     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  11     Library General Public License for more details.
  12
  13     You should have received a copy of the GNU Library General Public License
  14     along with this library; see the file COPYING.LIB.  If not, write to
  15     the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  16     Boston, MA 02110-1301, USA.
  17
  18 */
  19
  20 #ifndef PHONON_AUDIODEVICE_H
  21 #define PHONON_AUDIODEVICE_H
  22
  23 #include "kaudiodevicelist_export.h"
  24 #include <solid/audiointerface.h>
  25 #include <ksharedconfig.h>
  26 #include <QtCore/QDebug>
  27 #include <QtCore/QSharedData>
  28 #include <QtCore/QStringList>
  29
  30 class KConfigGroup;
  31
  32 namespace Solid
  33 {
  34     class AudioInterface;
  35 } // namespace Solid
  36
  37 namespace Phonon
  38 {
  39     class AudioDevicePrivate;
  40
  41     /** \class AudioDevice audiodevice.h Phonon/AudioDevice
  42      * \brief Information about a soundcard of the computer.
  43      *
  44      * This class encapsulates some useful information about a soundcard of the computer. Don't
  45      * instanciate this class in your code, use AudioDeviceEnumerator::availableDevices().
  46      *
  47      * \see AudioDeviceEnumerator
  48      * \ingroup Backend
  49      * \author Matthias Kretz <kretz@kde.org>
  50      */
  51     class KAUDIODEVICELIST_EXPORT AudioDevice
  52     {
  53         friend class AudioDevicePrivate;
  54         friend class AudioDeviceEnumerator;
  55         friend class AudioDeviceEnumeratorPrivate;
  56
  57         public:
  58             //static QStringList addSoftVolumeMixerControl(const AudioDevice &device, const QStringList &mixerControlNames);
  59
  60             /**
  61              * \internal
  62              * Creates an invalid and empty instance.
  63              */
  64             AudioDevice();
  65             /**
  66              * Copy constructor. The data is implicitly shared, so copying is cheap.
  67              */
  68             AudioDevice(const AudioDevice &rhs);
  69             /**
  70              * Destroys the object.
  71              */
  72             ~AudioDevice();
  73
  74             /**
  75              * Assignment operator. The data is implicitly shared, so copying is cheap.
  76              */
  77             AudioDevice &operator=(const AudioDevice &rhs);
  78             /**
  79              * Equality operator.
  80              */
  81             bool operator==(const AudioDevice &rhs) const;
  82             /**
  83              * Inequality operator.
  84              */
  85             bool operator!=(const AudioDevice &rhs) const { return !operator==(rhs); }
  86
  87             /**
  88              * Returns the name of the soundcard. This string
  89              * should be shown to the user to select from multiple soundcards.
  90              */
  91             QString cardName() const;
  92
  93             /**
  94              * Returns a list of device identifiers that your code can use in a snd_pcm_open call.
  95              * If the code wants to open the soundcard identified by this object it should try all
  96              * the device strings from start to end (they are sorted for preference).
  97              */
  98             QStringList deviceIds() const;
  99
 100             /**
 101              * Returns an icon name used to identify the type of soundcard. Simply use
 102              * \code
 103              * KIcon icon(audioDevice.iconName());
 104              * \endcode
 105              * to get the icon.
 106              */
 107             QString iconName() const;
 108
 109             /**
 110              * Retrieves the audio driver that should be used to access the device.
 111              *
 112              * @return the driver needed to access the device
 113              * @see Solid::AudioInterface::AudioDriver
 114              */
 115             Solid::AudioInterface::AudioDriver driver() const;
 116
 117             /**
 118              * Unique index to identify the device.
 119              */
 120             int index() const;
 121
 122             /**
 123              * Returns the initial preference for this device.
 124              *
 125              * The higher the number the more preferred the device is.
 126              */
 127             int initialPreference() const;
 128
 129             /**
 130              * Returns whether the device is available.
 131              *
 132              * An external device can be unavailable when it's unplugged. Every device can be
 133              * unavailable when its driver is not loaded.
 134              */
 135             bool isAvailable() const;
 136
 137             /**
 138              * Removes an unavailable device from the persistent store.
 139              *
 140              * \return \c true if the device was removed
 141              * \return \c false if the device could not be removed
 142              */
 143             bool ceaseToExist();
 144
 145             /**
 146              * Devices that ceased to exist are invalid.
 147              */
 148             bool isValid() const;
 149
 150             /**
 151              * Returns whether the device is a capture device.
 152              */
 153             bool isCaptureDevice() const;
 154
 155             /**
 156              * Returns whether the device is a playback device.
 157              */
 158             bool isPlaybackDevice() const;
 159
 160             /**
 161              * Returns whether the device is a non-standard device mostly only interesting for
 162              * advanced users.
 163              */
 164             bool isAdvancedDevice() const;
 165
 166         private:
 167             AudioDevice(Solid::Device audioHw, KSharedConfig::Ptr config);
 168             AudioDevice(KConfigGroup &deviceGroup);
 169             AudioDevice(const QString &alsaDeviceName, const QString &description, KSharedConfig::Ptr config);
 170
 171             QExplicitlySharedDataPointer<AudioDevicePrivate> d;
 172     };
 173 } // namespace Phonon
 174
 175 inline QDebug operator<<(QDebug &s, const Phonon::AudioDevice &dev)
 176 {
 177     s.space() << "\n-" << dev.cardName() << dev.driver() << dev.deviceIds() << "index:" << dev.index() << "preference:" << dev.initialPreference() << "avail:" << dev.isAvailable() << "advanced:" << dev.isAdvancedDevice();
 178     return s.space();
 179 }
 180
 181 #endif // PHONON_AUDIODEVICE_H