/****************************************************************************

**

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

** All rights reserved.

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

**

** This file is part of the Qt Mobility Components.

**

** $QT_BEGIN_LICENSE:LGPL$

** No Commercial Usage

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

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

** contained in the Technology Preview License Agreement accompanying

** this package.

**

** GNU Lesser General Public License Usage

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

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

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

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

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

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

**

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

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

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

**

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

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

**

**

**

**

**

**

**

**

** $QT_END_LICENSE$

**

****************************************************************************/

#include <QPair>

QTM_BEGIN_NAMESPACE

/*!

    \class QRadioTuner

    \brief The QRadioTuner class provides an interface to the systems analog radio device.

    \ingroup multimedia

    You can control the systems analog radio device using this interface, for example:

    \code

        radio = new QRadioTuner;

        connect(radio,SIGNAL(frequencyChanged(int)),this,SLOT(freqChanged(int)));

        if (radio->isBandSupported(QRadioTuner::FM)) {

            radio->setBand(QRadioTuner::FM);

            radio->setFrequency(yourRadioStationFrequency);

            radio->setVolume(100);

            radio->start();

        }

    \endcode

    The radio object will emit signals for any changes in state such as:

    bandChanged(), frequencyChanged(), stereoStatusChanged(), searchingChanged(),

    signalStrengthChanged(), volumeChanged(), mutedChanged().

    You can change between the frequency bands using setBand() however it is recommended

    that you check to make sure the band is available first using isBandSupported().

*/

class QRadioTunerPrivate : public QMediaObjectPrivate

{

public:

    QRadioTunerPrivate():provider(0), control(0) {}

    QMediaServiceProvider *provider;

    QRadioTunerControl* control;

};

/*!

    Constructs a radio tuner based on a media service allocated by a media service \a provider.

    The \a parent is passed to QMediaObject.

*/

QRadioTuner::QRadioTuner(QObject *parent, QMediaServiceProvider* provider):

    QMediaObject(*new QRadioTunerPrivate, parent, provider->requestService(Q_MEDIASERVICE_RADIO))

{

    Q_D(QRadioTuner);

    d->provider = provider;

    if (d->service != 0) {

        d->control = qobject_cast<QRadioTunerControl*>(d->service->control(QRadioTunerControl_iid));

        if (d->control != 0) {

            connect(d->control, SIGNAL(stateChanged(QRadioTuner::State)), SIGNAL(stateChanged(QRadioTuner::State)));

            connect(d->control, SIGNAL(bandChanged(QRadioTuner::Band)), SIGNAL(bandChanged(QRadioTuner::Band)));

            connect(d->control, SIGNAL(frequencyChanged(int)), SIGNAL(frequencyChanged(int)));

            connect(d->control, SIGNAL(stereoStatusChanged(bool)), SIGNAL(stereoStatusChanged(bool)));

            connect(d->control, SIGNAL(searchingChanged(bool)), SIGNAL(searchingChanged(bool)));

            connect(d->control, SIGNAL(signalStrengthChanged(int)), SIGNAL(signalStrengthChanged(int)));

            connect(d->control, SIGNAL(volumeChanged(int)), SIGNAL(volumeChanged(int)));

            connect(d->control, SIGNAL(mutedChanged(bool)), SIGNAL(mutedChanged(bool)));

        }

    }

}

/*!

    Destroys a radio tuner.

*/

QRadioTuner::~QRadioTuner()

{

    Q_D(QRadioTuner);

    d->provider->releaseService(d->service);

}

/*!

    Returns true if the radio tuner service is ready to use.

*/

bool QRadioTuner::isAvailable() const

{

    if (d_func()->control != NULL)

        return d_func()->control->isAvailable();

    else

        return false;

}

/*!

    Returns the availability error state.

*/

QtMedia::AvailabilityError QRadioTuner::availabilityError() const

{

    if (d_func()->control != NULL)

        return d_func()->control->availabilityError();

    else

        return QtMedia::ServiceMissingError;

}

/*!

    \property QRadioTuner::state

    Return the current radio tuner state.

    \sa QRadioTuner::State

*/

QRadioTuner::State QRadioTuner::state() const

{

    return d_func()->control ?

            d_func()->control->state() : QRadioTuner::StoppedState;

}

/*!

    \property QRadioTuner::band

    \brief the frequency band a radio tuner is tuned to.

    \sa QRadioTuner::Band

*/

QRadioTuner::Band QRadioTuner::band() const

{

    Q_D(const QRadioTuner);

    if (d->control != 0)

        return d->control->band();

    return QRadioTuner::FM;

}

/*!

    \property QRadioTuner::frequency

    \brief the frequency in Hertz a radio tuner is tuned to.

*/

int QRadioTuner::frequency() const

{

    Q_D(const QRadioTuner);

    if (d->control != 0)

        return d->control->frequency();

    return 0;

}

/*!

    Returns the number of Hertz to increment the frequency by when stepping through frequencies

    within a given \a band.

*/

int QRadioTuner::frequencyStep(QRadioTuner::Band band) const

{

    Q_D(const QRadioTuner);

    if(d->control != 0)

        return d->control->frequencyStep(band);

    return 0;

}

/*!

    Returns a frequency \a band's minimum and maximum frequency.

*/

QPair<int,int> QRadioTuner::frequencyRange(QRadioTuner::Band band) const

{

    Q_D(const QRadioTuner);

    if(d->control != 0)

        return d->control->frequencyRange(band);

    return qMakePair<int,int>(0,0);

}

/*!

    \property QRadioTuner::stereo

    \brief whether a radio tuner is receiving a stereo signal.

*/

bool QRadioTuner::isStereo() const

{

    Q_D(const QRadioTuner);

    if (d->control != 0)

        return d->control->isStereo();

    return false;

}

/*!

    \property QRadioTuner::stereoMode

    \brief the stereo mode of a radio tuner.

*/

QRadioTuner::StereoMode QRadioTuner::stereoMode() const

{

    Q_D(const QRadioTuner);

    if (d->control != 0)

        return d->control->stereoMode();

    return QRadioTuner::Auto;

}

void QRadioTuner::setStereoMode(QRadioTuner::StereoMode mode)

{

    Q_D(QRadioTuner);

    if (d->control != 0)

        return d->control->setStereoMode(mode);

}

/*!

    Identifies if a frequency \a band is supported by a radio tuner.

    Returns true if the band is supported, and false if it is not.

*/

bool QRadioTuner::isBandSupported(QRadioTuner::Band band) const

{

    Q_D(const QRadioTuner);

    if (d->control != 0)

        return d->control->isBandSupported(band);

    return false;

}

/*!

    Activate the radio device.

*/

void QRadioTuner::start()

{

    Q_D(const QRadioTuner);

    if (d->control != 0)

        d->control->start();

}

/*!

    Deactivate the radio device.

*/

void QRadioTuner::stop()

{

    Q_D(const QRadioTuner);

    if (d->control != 0)

        d->control->stop();

}

/*!

    \property QRadioTuner::signalStrength

    \brief the strength of the current radio signal as a percentage.

*/

int QRadioTuner::signalStrength() const

{

    Q_D(const QRadioTuner);

    if (d->control != 0)

        return d->control->signalStrength();

    return 0;

}

/*!

    \property QRadioTuner::volume

    \brief the volume of a radio tuner's audio output as a percentage.

*/

int QRadioTuner::volume() const

{

    Q_D(const QRadioTuner);

    if (d->control != 0)

        return d->control->volume();

    return 0;

}

/*!

    \property QRadioTuner::muted

    \brief whether a radio tuner's audio output is muted.

*/

bool QRadioTuner::isMuted() const

{

    Q_D(const QRadioTuner);

    if (d->control != 0)

        return d->control->isMuted();

    return false;

}

/*!

    Sets a radio tuner's frequency \a band.

    Changing the band will reset the \l frequency to the new band's minimum frequency.

*/

void QRadioTuner::setBand(QRadioTuner::Band band)

{

    Q_D(QRadioTuner);

    if (d->control != 0)

        d->control->setBand(band);

}

/*!

    Sets a radio tuner's \a frequency.

    If the tuner is set to a frequency outside the current \l band, the band will be changed to

    one occupied by the new frequency.

*/

void QRadioTuner::setFrequency(int frequency)

{

    Q_D(QRadioTuner);

    if (d->control != 0)

        d->control->setFrequency(frequency);

}

void QRadioTuner::setVolume(int volume)

{

    Q_D(QRadioTuner);

    if (d->control != 0)

        d->control->setVolume(volume);

}

void QRadioTuner::setMuted(bool muted)

{

    Q_D(QRadioTuner);

    if (d->control != 0)

        d->control->setMuted(muted);

}

/*!

    \property QRadioTuner::searching

    \brief whether a radio tuner is currently scanning for a signal.

    \sa searchForward(), searchBackward(), cancelSearch()

*/

bool QRadioTuner::isSearching() const

{

    Q_D(const QRadioTuner);

    if (d->control != 0)

        return d->control->isSearching();

    return false;

}

/*!

    Starts a forward scan for a signal, starting from the current \l frequency.

    \sa searchBackward(), cancelSearch(), searching

*/

void QRadioTuner::searchForward()

{

    Q_D(QRadioTuner);

    if (d->control != 0)

        d->control->searchForward();

}

/*!

    Starts a backwards scan for a signal, starting from the current \l frequency.

    \sa searchForward(), cancelSearch(), searching

*/

void QRadioTuner::searchBackward()

{

    Q_D(QRadioTuner);

    if (d->control != 0)

        d->control->searchBackward();

}

/*!

    Stops scanning for a signal.

    \sa searchForward(), searchBackward(), searching

*/

void QRadioTuner::cancelSearch()

{

    Q_D(QRadioTuner);

    if (d->control != 0)

        d->control->cancelSearch();

}

/*!

    Returns the error state of a radio tuner.

    \sa errorString()

*/

QRadioTuner::Error QRadioTuner::error() const

{

    Q_D(const QRadioTuner);

    if (d->control != 0)

        return d->control->error();

    return QRadioTuner::ResourceError;

}

/*!

    Returns a description of a radio tuner's error state.

    \sa error()

*/

QString QRadioTuner::errorString() const

{

    Q_D(const QRadioTuner);

    if (d->control != 0)

        return d->control->errorString();

    return QString();

}

/*!

    \fn void QRadioTuner::bandChanged(QRadioTuner::Band band)

    Signals a radio tuner's \a band has changed.

*/

/*!

    \fn void QRadioTuner::frequencyChanged(int frequency)

    Signals that the \a frequency a radio tuner is tuned to has changed.

*/

/*!

    \fn void QRadioTuner::mutedChanged(bool muted)

    Signals that the \a muted state of a radio tuner's audio output has changed.

*/

/*!

    \fn void QRadioTuner::volumeChanged(int volume)

    Signals that the \a volume of a radio tuner's audio output has changed.

*/

/*!

    \fn void QRadioTuner::searchingChanged(bool searching)

    Signals that the \a searching state of a radio tuner has changed.

*/

/*!

    \fn void QRadioTuner::stereoStatusChanged(bool stereo)

    Signals that the \a stereo state of a radio tuner has changed.

*/

/*!

    \fn void QRadioTuner::signalStrengthChanged(int strength)

    Signals that the \a strength of the signal received by a radio tuner has changed.

*/