1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtMultimedia module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 #include "qaudiodevicefactory_p.h"

    43 #include <QtMultimedia/qaudioengine.h>

    44 #include <QtMultimedia/qaudiodeviceinfo.h>

    45 

    46 

    47 QT_BEGIN_NAMESPACE

    48 

    49 class QAudioDeviceInfoPrivate : public QSharedData

    50 {

    51 public:

    52     QAudioDeviceInfoPrivate():info(0) {}

    53     QAudioDeviceInfoPrivate(const QString &r, const QByteArray &h, QAudio::Mode m):

    54         realm(r), handle(h), mode(m)

    55     {

    56         info = QAudioDeviceFactory::audioDeviceInfo(realm, handle, mode);

    57     }

    58 

    59     QAudioDeviceInfoPrivate(const QAudioDeviceInfoPrivate &other):

    60         QSharedData(other),

    61         realm(other.realm), handle(other.handle), mode(other.mode)

    62     {

    63         info = QAudioDeviceFactory::audioDeviceInfo(realm, handle, mode);

    64     }

    65 

    66     QAudioDeviceInfoPrivate& operator=(const QAudioDeviceInfoPrivate &other)

    67     {

    68         delete info;

    69 

    70         realm = other.realm;

    71         handle = other.handle;

    72         mode = other.mode;

    73         info = QAudioDeviceFactory::audioDeviceInfo(realm, handle, mode);

    74         return *this;

    75     }

    76 

    77     ~QAudioDeviceInfoPrivate()

    78     {

    79         delete info;

    80     }

    81 

    82     QString     realm;

    83     QByteArray  handle;

    84     QAudio::Mode mode;

    85     QAbstractAudioDeviceInfo*   info;

    86 };

    87 

    88 

    89 /*!

    90     \class QAudioDeviceInfo

    91     \brief The QAudioDeviceInfo class provides an interface to query audio devices and their functionality.

    92     \inmodule QtMultimedia

    93     \ingroup multimedia

    94 

    95     \since 4.6

    96 

    97     QAudioDeviceInfo lets you query for audio devices--such as sound

    98     cards and USB headsets--that are currently available on the system.

    99     The audio devices available are dependent on the platform or audio plugins installed.

   100 

   101     You can also query each device for the formats it supports. A

   102     format in this context is a set consisting of a specific byte

   103     order, channel, codec, frequency, sample rate, and sample type.  A

   104     format is represented by the QAudioFormat class.

   105 

   106     The values supported by the the device for each of these

   107     parameters can be fetched with

   108     supportedByteOrders(), supportedChannels(), supportedCodecs(),

   109     supportedFrequencies(), supportedSampleSizes(), and

   110     supportedSampleTypes(). The combinations supported are dependent on the platform,

   111     audio plugins installed and the audio device capabilities. If you need a specific format, you can check if

   112     the device supports it with isFormatSupported(), or fetch a

   113     supported format that is as close as possible to the format with

   114     nearestFormat(). For instance:

   115 

   116     \snippet doc/src/snippets/audio/main.cpp 1

   117     \dots 8

   118     \snippet doc/src/snippets/audio/main.cpp 2

   119 

   120     A QAudioDeviceInfo is used by Qt to construct

   121     classes that communicate with the device--such as

   122     QAudioInput, and QAudioOutput. The static

   123     functions defaultInputDevice(), defaultOutputDevice(), and

   124     deviceList() let you get a list of all available

   125     devices. Devices are fetch according to the value of mode

   126     this is specified by the QAudio::Mode enum.

   127     The QAudioDeviceInfo returned are only valid for the QAudio::Mode.

   128 

   129     For instance:

   130 

   131     \code

   132     foreach(const QAudioDeviceInfo &deviceInfo, QAudioDeviceInfo::deviceList(QAudio::AudioOutput))

   133         qDebug() << "Device name: " << deviceInfo.deviceName();

   134     \endcode

   135 

   136     In this code sample, we loop through all devices that are able to output

   137     sound, i.e., play an audio stream in a supported format. For each device we

   138     find, we simply print the deviceName().

   139 

   140     \sa QAudioOutput, QAudioInput

   141 */

   142 

   143 /*!

   144     Constructs an empty QAudioDeviceInfo object.

   145 */

   146 

   147 QAudioDeviceInfo::QAudioDeviceInfo():

   148     d(new QAudioDeviceInfoPrivate)

   149 {

   150 }

   151 

   152 /*!

   153     Constructs a copy of \a other.

   154 */

   155 

   156 QAudioDeviceInfo::QAudioDeviceInfo(const QAudioDeviceInfo& other):

   157     d(other.d)

   158 {

   159 }

   160 

   161 /*!

   162     Destroy this audio device info.

   163 */

   164 

   165 QAudioDeviceInfo::~QAudioDeviceInfo()

   166 {

   167 }

   168 

   169 /*!

   170     Sets the QAudioDeviceInfo object to be equal to \a other.

   171 */

   172 

   173 QAudioDeviceInfo& QAudioDeviceInfo::operator=(const QAudioDeviceInfo &other)

   174 {

   175     d = other.d;

   176     return *this;

   177 }

   178 

   179 /*!

   180     Returns whether this QAudioDeviceInfo object holds a device definition.

   181 */

   182 

   183 bool QAudioDeviceInfo::isNull() const

   184 {

   185     return d->info == 0;

   186 }

   187 

   188 /*!

   189     Returns human readable name of audio device.

   190 

   191     Device names vary depending on platform/audio plugin being used.

   192 

   193     They are a unique string identifiers for the audio device.

   194 

   195     eg. default, Intel, U0x46d0x9a4

   196 */

   197 

   198 QString QAudioDeviceInfo::deviceName() const

   199 {

   200     return isNull() ? QString() : d->info->deviceName();

   201 }

   202 

   203 /*!

   204     Returns true if \a settings are supported by the audio device of this QAudioDeviceInfo.

   205 */

   206 

   207 bool QAudioDeviceInfo::isFormatSupported(const QAudioFormat &settings) const

   208 {

   209     return isNull() ? false : d->info->isFormatSupported(settings);

   210 }

   211 

   212 /*!

   213     Returns QAudioFormat of default settings.

   214 

   215     These settings are provided by the platform/audio plugin being used.

   216 

   217     They also are dependent on the QAudio::Mode being used.

   218 

   219     A typical audio system would provide something like:

   220     \list

   221     \o Input settings: 8000Hz mono 8 bit.

   222     \o Output settings: 44100Hz stereo 16 bit little endian.

   223     \endlist

   224 */

   225 

   226 QAudioFormat QAudioDeviceInfo::preferredFormat() const

   227 {

   228     return isNull() ? QAudioFormat() : d->info->preferredFormat();

   229 }

   230 

   231 /*!

   232     Returns closest QAudioFormat to \a settings that system audio supports.

   233 

   234     These settings are provided by the platform/audio plugin being used.

   235 

   236     They also are dependent on the QAudio::Mode being used.

   237 */

   238 

   239 QAudioFormat QAudioDeviceInfo::nearestFormat(const QAudioFormat &settings) const

   240 {

   241     return isNull() ? QAudioFormat() : d->info->nearestFormat(settings);

   242 }

   243 

   244 /*!

   245     Returns a list of supported codecs.

   246 

   247     All platform and plugin implementations should provide support for:

   248 

   249     "audio/pcm" - Linear PCM

   250 

   251     For writing plugins to support additional codecs refer to:

   252 

   253     http://www.iana.org/assignments/media-types/audio/

   254 */

   255 

   256 QStringList QAudioDeviceInfo::supportedCodecs() const

   257 {

   258     return isNull() ? QStringList() : d->info->codecList();

   259 }

   260 

   261 /*!

   262     Returns a list of supported frequencies.

   263 */

   264 

   265 QList<int> QAudioDeviceInfo::supportedFrequencies() const

   266 {

   267     return isNull() ? QList<int>() : d->info->frequencyList();

   268 }

   269 

   270 /*!

   271     Returns a list of supported channels.

   272 */

   273 

   274 QList<int> QAudioDeviceInfo::supportedChannels() const

   275 {

   276     return isNull() ? QList<int>() : d->info->channelsList();

   277 }

   278 

   279 /*!

   280     Returns a list of supported sample sizes.

   281 */

   282 

   283 QList<int> QAudioDeviceInfo::supportedSampleSizes() const

   284 {

   285     return isNull() ? QList<int>() : d->info->sampleSizeList();

   286 }

   287 

   288 /*!

   289     Returns a list of supported byte orders.

   290 */

   291 

   292 QList<QAudioFormat::Endian> QAudioDeviceInfo::supportedByteOrders() const

   293 {

   294     return isNull() ? QList<QAudioFormat::Endian>() : d->info->byteOrderList();

   295 }

   296 

   297 /*!

   298     Returns a list of supported sample types.

   299 */

   300 

   301 QList<QAudioFormat::SampleType> QAudioDeviceInfo::supportedSampleTypes() const

   302 {

   303     return isNull() ? QList<QAudioFormat::SampleType>() : d->info->sampleTypeList();

   304 }

   305 

   306 /*!

   307     Returns the name of the default input audio device.

   308     All platform and audio plugin implementations provide a default audio device to use.

   309 */

   310 

   311 QAudioDeviceInfo QAudioDeviceInfo::defaultInputDevice()

   312 {

   313     return QAudioDeviceFactory::defaultInputDevice();

   314 }

   315 

   316 /*!

   317     Returns the name of the default output audio device.

   318     All platform and audio plugin implementations provide a default audio device to use.

   319 */

   320 

   321 QAudioDeviceInfo QAudioDeviceInfo::defaultOutputDevice()

   322 {

   323     return QAudioDeviceFactory::defaultOutputDevice();

   324 }

   325 

   326 /*!

   327     Returns a list of audio devices that support \a mode.

   328 */

   329 

   330 QList<QAudioDeviceInfo> QAudioDeviceInfo::deviceList(QAudio::Mode mode)

   331 {

   332     return QAudioDeviceFactory::deviceList(mode);

   333 }

   334 

   335 

   336 /*!

   337     \internal

   338 */

   339 

   340 QAudioDeviceInfo::QAudioDeviceInfo(const QString &realm, const QByteArray &handle, QAudio::Mode mode):

   341     d(new QAudioDeviceInfoPrivate(realm, handle, mode))

   342 {

   343 }

   344 

   345 /*!

   346     \internal

   347 */

   348 

   349 QString QAudioDeviceInfo::realm() const

   350 {

   351     return d->realm;

   352 }

   353 

   354 /*!

   355     \internal

   356 */

   357 

   358 QByteArray QAudioDeviceInfo::handle() const

   359 {

   360     return d->handle;

   361 }

   362 

   363 

   364 /*!

   365     \internal

   366 */

   367 

   368 QAudio::Mode QAudioDeviceInfo::mode() const

   369 {

   370     return d->mode;

   371 }

   372 

   373 QT_END_NAMESPACE

   374