/*
* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
*
*/

#ifndef RADIOSTATION_H_
#define RADIOSTATION_H_

// System includes
#include <QString>
#include <QMetaType>
#include <QObject>

// User includes
#include "radiouiengineexport.h"
#include "radio_global.h"

// Constants
const int KLastCallSignCharCode = 25;
const uint KThreeLetterCallSignCount = 72;
const uint KKxxxCallSignPiFirst = 0x1000;
const uint KWxxxCallSignPiFirst = 0x54A8;
const uint KWxxxCallSignPiLast = 0x994F;
const uint KxxxCallSignPiFirst = 0x9950;
const uint KxxxCallSignPiLast = 0x99B9;

// Forward declarations
class RadioStationPrivate;

// Class declaration

/*!
 * RadioStation is a data container that holds all information of a radio station.
 * It is implicitly shared to make it cheap to copy and pass around as a signal parameter.
 * It uses the "shared null" idiom to initialize empty instances quickly and efficiently.
 *
 * Note! It is derived from QObject even though architecturally it shouldn't be.
 * It is done only to satisfy the WINSCW build which doesn't export the destructor in UREL
 * build. This causes mismatching def files and annoying warnings. Deriving from QObject fixes this
 */
class UI_ENGINE_DLL_EXPORT RadioStation : public QObject
{
    friend class RadioStationModel;
    friend class RadioStationModelPrivate;
    friend class TestRadioUiEngine;
    friend class TestRadioPresetStorage;
    
public:

    /**
     * Flags to indicate how the RadioStation has changed since last save or reset.
     * Declared to use QFlags<> to ease flag usage and to enforce type safety
     */
    enum ChangeFlag
    {
         NoChange               = 0
        ,PersistentDataChanged  = 1 << 0
        ,NameChanged            = 1 << 1
        ,FavoriteChanged        = 1 << 2
        ,GenreChanged           = 1 << 3
        ,UrlChanged             = 1 << 4
        ,TypeChanged            = 1 << 5
        ,PiCodeChanged          = 1 << 6
        ,PsTypeChanged          = 1 << 7
        ,RadioTextChanged       = 1 << 8
        ,DynamicPsChanged       = 1 << 9
    };
    Q_DECLARE_FLAGS( Change, ChangeFlag )

    /**
     * Flags ot indicate station type.
     * Declared to use QFlags<> to ease flag usage and to enforce type safety
     */
    enum TypeFlag
    {
       Favorite         = 1 << 0,
       LocalStation     = 1 << 1,
       PreDefined       = 1 << 2,
       Temporary        = 1 << 3
    };
    Q_DECLARE_FLAGS( Type, TypeFlag )

    /**
     * Flag to indiate whether or not station uses dynamic PS and if the check has been performed
     * Declared to use QFlags<> to ease flag usage and to enforce type safety
     */
    enum PsTypeFlag
    {
        Unknown,
        Dynamic,
        Static
    };
    Q_DECLARE_FLAGS( PsType, PsTypeFlag )

    /**
     * Magical values used as preset indexes to signify certain conditions.
     * NotFound means that a find function could not find a station
     * Invalid means that the station instance has not been initialized
     */
    enum PresetFlag { NotFound = -1, Invalid = -100, SharedNull = -200 };

    /**
     * Static convenience function to parse a frequency
     */
    static QString parseFrequency( uint frequency );

    RadioStation();
    RadioStation( const RadioStation& other );

    ~RadioStation();

    RadioStation& operator=( const RadioStation& other );

public:

    explicit RadioStation( int presetIndex, uint frequency );

    void reset();
    void setChangeFlags( Change flags );

    // Setters for persistent data
    void setPresetIndex( int presetIndex );
    void setFrequency( uint frequency );
    void setName( const QString& name );
    void setGenre( const int genre );
    void setUrl( const QString& url );
    bool setPiCode( int piCode, RadioRegion::Region region );

    // Setters for non-persistent data
    void setPsType( PsType psType );
    void setRadioText( const QString& radioText );
    void setRadioTextPlus( const int rtPlusClass, const QString& rtPlusItem );
    void setDynamicPsText( const QString& dynamicPsText );

public: // Getters and setters

    // Setters & Getters for persistent data

    bool isValid() const;

    QString name() const;
    void setUserDefinedName( const QString& name );
    bool isRenamed() const;

    int genre() const;

    QString frequencyMhz() const;
    uint frequency() const;
    int presetIndex() const;

    void setFavorite( bool favorite );
    bool isFavorite() const;

    QString url() const;

    bool hasPiCode() const;
    bool hasRds() const;

    void setType( RadioStation::Type type );
    void unsetType( RadioStation::Type type );
    bool isType( RadioStation::Type type ) const;

    // Getters for non-persistent data

    PsType psType() const;
    QString radioText() const;
    QString dynamicPsText() const;
    Change changeFlags() const;
    bool hasDataChanged( Change flags ) const;
    bool hasChanged() const;
    void resetChangeFlags();

private:

    /**
     * Decrements the reference count of the implicitly shared data.
     * Data is deleted if no instance uses it anymore.
     */
    void decrementReferenceCount();

    // Methods for converting PI code into call sign
    QString piCodeToCallSign( uint programmeIdentification );
    QString iterateCallSign( int piBase, int programmeIdentification );
    QString callSignString( uint programmeIdentification );
    char callSignChar( uint decimalValue );

private: // data

    /**
     * Pointer to the implicitly shared private implementation
     * Own.
     */
    class RadioStationPrivate* mData;

public:

    /**
     * Detach from the implicitly shared data
     */
    void detach();

    /**
     * Checks if the class is detached from implicitly shared data
     * Required by many QT convenience functions for implicitly shared classes
     */
    bool isDetached() const;

    typedef RadioStationPrivate* DataPtr;
    inline DataPtr &data_ptr() { return mData; }

};

Q_DECLARE_OPERATORS_FOR_FLAGS( RadioStation::Change )
Q_DECLARE_OPERATORS_FOR_FLAGS( RadioStation::Type )

Q_DECLARE_TYPEINFO( RadioStation, Q_MOVABLE_TYPE );  // Can be moved around in memory by containers if necessary
Q_DECLARE_SHARED( RadioStation )                     // Uses implicit sharing
Q_DECLARE_METATYPE( RadioStation )                   // To be usable in a QVariant

#endif // RADIOSTATION_H_