/*

* Copyright (c) 2002-2004 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:  This class is the main interface to the RadioServer. It implements

*				 the client-side session. It also contains M-observer classes that

*				 the client must implement to receive completion notification for

*				 asynchronous requests and spontaneous event notifications.

*

*/

#ifndef RADIOSESSION_H

#define RADIOSESSION_H

//  INCLUDES

#include <mmf/common/mmfbase.h>

#include <mmf/common/mmfcontrollerframework.h>

#include <MCustomCommand.h>

#include "RadioServerData.h"

// FORWARD DECLARATIONS

class CRadioRequest;

class CRadioEventHandler;

// CLASS DECLARATION

/**

*  Defines functions that client must implement in order to receive

*  events from the radio server.

*

*  @lib RadioSession.lib

*  @since S60 3.0

*/

class MRadioObserver

    {

public: // New functions

//********** Tuner related

	/**

     * Completion message for RequestTunerControl request.

     *

     * @since S60 3.2

     * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

     */

	virtual void RequestTunerControlComplete( TRadioServerError aError ) = 0;

	/**

     * Completion message for SetFrequencyRange request.

     *

     * @since S60 3.2

     * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

     */

	virtual void SetFrequencyRangeComplete( TRadioServerError aError ) = 0;

	/**

     * Completion message for SetFrequency request.

     *

     * @since S60 3.0

     * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

     */

	virtual void SetFrequencyComplete( TRadioServerError aError ) = 0;

	/**

     * Completion message for StationSeek request.

     *

     * @since S60 3.0

     * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

     * @param aFrequency Valid only if aError is KErrNone. Contains the new frequency in Hz.

     */

	virtual void StationSeekComplete( TRadioServerError aError, TInt aFrequency ) = 0;

	/**

     * Event notification indicating FM transmitter status change. Radio receiver

     * is turned off when FM transmitter is active.

     *

     * @since S60 3.2

     * @param aActive ETrue if FM transmitter is active; EFalse otherwise.

     */

	virtual void RadioEventTransmitterStatusChange( TBool aActive ) = 0;

	/**

     * Event notification indicating antenna status change.

     *

     * @since S60 3.0

     * @param aAttached ETrue if antenna is attached.

     */

	virtual void RadioEventAntennaStatusChange( TBool aAttached ) = 0;

	/**

     * Event notification indicating offline mode change.

     *

     * @since S60 3.0

     * @param aOfflineMode ETrue if device is in offline mode.

     */

	virtual void RadioEventOfflineModeChange( TBool aOfflineMode ) = 0;

	/**

     * Event notification indicating frequency range change. This may be caused by

     * other applications.

     *

     * @since S60 3.2

     * @param aNewRange New frequency range.

     */

	virtual void RadioEventFrequencyRangeChanged( TRsFrequencyRange aNewRange ) = 0;

	/**

     * Event notification indicating frequency(Hz) change. This may be caused by

     * other applications or RDS if AF/TA is enabled.

     *

     * @since S60 3.2

     * @param aFrequency New frequency where tuner is currently tuned.

     */

	virtual void RadioEventFrequencyChange( TInt aFrequency ) = 0;

	/**

     * Event notification indicating forced mono status change.

     *

     * @since S60 3.2

     * @param aForcedMono ETrue if forced mode is enabled; EFalse otherwise.

     */

	virtual void RadioEventForcedMonoChanged( TBool aForcedMono ) = 0;

	/**

     * Event notification indicating squelch (muting the frequencies without broadcast) status change.

     *

     * @since S60 3.2

     * @param aSquelch ETrue if squelch is enabled; EFalse otherwise.

     */

	virtual void RadioEventSquelchChanged( TBool aSquelch ) = 0;

//********** Player related

	/**

     * Event notification indicating radio player state change. This may be caused by

     * other applications.

     *

     * @since S60 3.0

     * @param aRadioOn ETrue if radio is playing, otherwise radio is off.

     * @param aError Valid only if aRadioOn is EFalse. Contains the reason why radio is off.

     */

	virtual void RadioEventStateChange( TBool aRadioOn, TRadioServerError aError ) = 0;

	/**

     * Event notification indicating volume change.

     *

     * @since S60 3.2

     * @param aVolume New volume.

     */

	virtual void RadioEventVolumeChange( TInt aVolume ) = 0;

	/**

     * Event notification indicating mute setting change.

     *

     * @since S60 3.2

     * @param aMute ETrue indicates audio is muted.

     */

	virtual void RadioEventMuteChange( TBool aMute ) = 0;

	/**

     * Event notification indicating balance setting change.

     *

     * @since S60 3.2

     * @param aLeftPercentage Left speaker volume percentage. This value ranges from 0 to 100.

     * @param aRightPercentage Right speaker volume percentage. This value ranges from 0 to 100.

     */

	virtual void RadioEventBalanceChange( TInt aLeftPercentage, TInt aRightPercentage ) = 0;

//********** RDS related

	/**

     * Completion message for StationSeekByPTY request.

     *

     * @since S60 3.2

     * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

     * @param aFrequency The frequency(Hz) of the radio station that was found.

     */

	virtual void StationSeekByPTYComplete( TRadioServerError aError, TInt aFrequency ) = 0;

	/**

     * Completion message for StationSeekByTA request.

     *

     * @since S60 3.2

     * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

     * @param aFrequency The frequency(Hz) of the radio station that was found.

     */

	virtual void StationSeekByTAComplete( TRadioServerError aError, TInt aFrequency ) = 0;

	/**

     * Completion message for StationSeekByTP request.

     *

     * @since S60 3.2

     * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

     * @param aFrequency The frequency(Hz) of the radio station that was found.

     */

	virtual void StationSeekByTPComplete( TRadioServerError aError, TInt aFrequency ) = 0;

	/**

     * Completion message for GetFreqByPTY request.

     *

     * @since S60 3.2

     * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

     * @param aFreqList Array of frequencies (Hz), valid only if aError is KErrNone.

     */

	virtual void GetFreqByPTYComplete( TRadioServerError aError, RArray<TInt>& aFreqList ) = 0;

	/**

     * Completion message for GetFreqByTA request.

     *

     * @since S60 3.2

     * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

     * @param aFreqList Array of frequencies (Hz), valid only if aError is KErrNone.

     */

	virtual void GetFreqByTAComplete( TRadioServerError aError, RArray<TInt>& aFreqList ) = 0;

	/**

     * Completion message for StatGetPSByPTY request.

     *

     * @since S60 3.2

     * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

     * @param aPsList Array of programme service names, valid only if aError is KErrNone.

     */

	virtual void GetPSByPTYComplete( TRadioServerError aError, RArray<TRsRdsPSName>& aPsList ) = 0;

	/**

     * Completion message for GetPSByTA request.

     *

     * @since S60 3.2

     * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

     * @param aPsList Array of programme service names, valid only if aError is KErrNone.

     */

	virtual void GetPSByTAComplete( TRadioServerError aError, RArray<TRsRdsPSName>& aPsList ) = 0;

	/**

     * Event notification indicating new Programme Identification(PI) is available.

     *

     * @since S60 3.2

     * @param aPi Programme identification

     */

	virtual void RadioEventRdsDataPI( TInt aPi ) = 0;

	/**

     * Event notification indicating new Programme Type(PTY) is available.

     *

     * @since S60 3.2

     * @param aPty Programme type

     */

	virtual void RadioEventRdsDataPTY( TRsRdsProgrammeType aPty ) = 0;

	/**

     * Event notification indicating new Programme Service(PS) is available.

     *

     * @since S60 3.2

     * @param aPs Programme service

     */

	virtual void RadioEventRdsDataPS( TRsRdsPSName& aPs ) = 0;

	/**

     * Event notification indicating new Radio Text(RT) is available.

     *

     * @since S60 3.2

     * @param aRt Radio text

     */

	virtual void RadioEventRdsDataRT( TRsRdsRadioText& aRt ) = 0;

	/**

     * Event notification indicating new Clock Time(CT) is available.

     *

     * @since S60 3.2

     * @param aCt Clock time

     */

	virtual void RadioEventRdsDataCT( TDateTime& aCt ) = 0;

	/**

     * Event notification indicating Traffice Announcement(TA) status change.

     *

     * @since S60 3.2

     * @param aTaOn ETrue indicates that Traffic Announcement is on.

     */

	virtual void RadioEventRdsDataTA( TBool aTaOn ) = 0;

	/**

     * Event notification indicating new Radio Text+(RT+) is available.

     *

     * @since S60 3.2

	 * @param aRtPlusClass Radio text plus class

	 * @param aRtPlusData Radio text plus data

	 */

	virtual void RadioEventRdsDataRTplus( TRsRdsRTplusClass aRtPlusClass, TRsRdsRadioText& aRtPlusData ) = 0;

	/**

     * Event notification indicating the beginning of Alternate Frequency(AF) search.

     *

     * @since S60 3.2

     */

	virtual void RadioEventRdsSearchBeginAF() = 0;

	/**

     * Event notification indicating the end of Alternate Frequency(AF) search.

     *

     * @since S60 3.2

     * @param aError KErrNone if successful, otherwise one of the system/RadioServer errors.

     * @param aFrequency The frequency(Hz) of the radio station that was found.

     */

	virtual void RadioEventRdsSearchEndAF( TRadioServerError aError, TInt aFrequency ) = 0;

	/**

     * Event notification indicating station change to another frequency(Hz) that is

     * broadcasting Traffic Announcement(TA).

     *

     * @since S60 3.2

     * @param aFrequency The frequency(Hz) of the radio station that was found.

     */

	virtual void RadioEventRdsStationChangeTA( TInt aFrequency ) = 0;

	/**

     * Event notification indicating automatic switching (AF) setting change.

     *

     * @since S60 3.2

     * @param aAuto ETrue indicates that automatic switching is on.

     */

	virtual void RadioEventRdsAutomaticSwitchingChange( TBool aAuto ) = 0;

	/**

     * Event notification indicating automatic traffic announcement setting change.

     *

     * @since S60 3.2

     * @param aAuto ETrue indicates that automatic traffic announcement is on.

     */

	virtual void RadioEventRdsAutomaticTrafficAnnouncement( TBool aAuto ) = 0;

	/**

     * Event notification indicating RDS signal status change (i.e. signal is lost/restored).

     *

     * @since S60 3.2

     * @param aSignal ETrue indicates that RDS signal is available in the tuned frequency.

     */

	virtual void RadioEventRdsSignalChange( TBool aSignal ) = 0;

    };

/**

*  Main interface to the Radio Server.

*  Implements the client-side session.

*

*  @lib RadioSession.lib

*  @since S60 3.0

*/

class RRadioSession : public RSessionBase,

					  public MCustomCommand

    {

public:  // Constructors and destructor

	/**

     * C++ default constructor.

     */

	IMPORT_C RRadioSession();

public: // New functions

	/**

     * Connects a client to the radio server.

     * @since S60 3.0

     *

     * @param aObserver The observer object for receiving async completion callbacks.

     * @param aPrimaryClient Indicates whether the client is a primary client. Primary

     * clients are clients that can control the radio tuner such as FM Radio Application,

     * Visual Radio, or a Java Radio App.  Non-primary clients are observers of the tuner,

     * player, and RDS utilities and cannot exist without a primary client such as Active

     * Idle, Cover UI, or a smart accessory driver.

     * @return A standard system error code.

     */

	IMPORT_C TInt Connect( MRadioObserver& aObserver, TBool aPrimaryClient );

	/**

     * Gets the client side version number.

     *

     * @since S60 3.0

     * @return The client side version number.

     */

	IMPORT_C TVersion Version() const;

	/**

     * Closes connection to the radio server.

     *

     * @since S60 3.0

     */

	IMPORT_C void Close();

//********** TunerUtility control begins

	/**

     * Request for control of a tuner. If this method returns KErrNone, control of

     * the tuner has been granted. Control to the tuner must be granted before any

     * other request can be made.

     *

     * @since S60 3.2

     * @param Tuner type (e.g. FM, AM)

     * @return A standard system error code.

     * @see MRadioObserver::RequestTunerControlComplete

     */

	IMPORT_C void RequestTunerControl( TRsTuner aTuner );

	/**

     * Get the capabilities of the radio on the device.

     *

     * @since S60 3.2

     * @param aCaps The capabilities object to fill

     * @return A standard system error code.

     */

	IMPORT_C TInt GetTunerCapabilities( TRsTunerCapabilities& aCaps ) const;

	/**

     * EnableTunerInOfflineMode on the device.

     *

     * @since S60 3.2

     * @param aEnable ETrue to enable tuner functions in offline mode, EFalse to disable.

     * @return A standard system/RadioServer error code.

     */

	IMPORT_C TInt EnableTunerInOfflineMode( TBool aEnable );

	/**

     * Asynchronous request to set the frequency range. If the frequency range is not set,

     * it will be defaulted to ERsTunerFM.

     *

     * @since S60 3.2

     * @param aRange Frequency range

     * @see MRadioObserver::SetFrequencyRangeComplete

     */

	IMPORT_C void SetFrequencyRange( TRsFrequencyRange aRange );

	/**

     * Cancels an outstanding SetFrequencyRange request. Note that SetFrequencyRange may

     * complete before cancel can occur and a callback may occur.

     *

     * @since S60 3.2

     * @return A standard system error code.

     */

	IMPORT_C void CancelSetFrequencyRange();

	/**

     * Get the current frequency range. It also returns the minimum and maximum frequencies(Hz)

     * for the returned range.

     *

     * @since S60 3.2

     * @param aRange On return contains the current frequency range.

     * @param aMinFreq On return contains the minimum frequency for the current frequency range.

     * @param aMaxFreq On return contains the maximum frequency for the current frequency range.

     * @return A standard system/RadioServer error code.

     */

	IMPORT_C TInt GetFrequencyRange( TRsFrequencyRange& aRange, TInt& aMinFreq, TInt& aMaxFreq ) const;

	/**

     * Asynchronous request to tune the tuner to the specified frequency.

     *

     * @since S60 3.2

     * @param aFrequency The frequency (Hz) to tune to

     * @see MRadioObserver::SetFrequecyComplete

     */

	IMPORT_C void SetFrequency( TInt aFrequency );

	/**

     * Cancels an outstanding SetFrequency request. Note that SetFrequency may complete before

     * cancel can occur and a callback to MRadioObserver::SetFrequencyComplete may occur.

     *

     * @since S60 3.0

     * @return A standard system/RadioServer error code.

     */

	IMPORT_C void CancelSetFrequency();

	/**

     * Get the current frequency.

     *

     * @since S60 3.2

     * @param aFrequency On return contains the current frequency(Hz).

     * @return A standard system/RadioServer error code.

     */

	IMPORT_C TInt GetFrequency( TInt& aFrequency ) const;

	/**

     * Asynchronous request to find a radio station, starting from current frequency and

     * seaching in the direction specified (i.e. up or down).

     *

     * @since S60 3.0

     * @param aSeekUp Search direction

     * @see MRadioObserver::StationSeekComplete

     */

	IMPORT_C void StationSeek( TBool aUpwards );

	/**

     * Cancels an outstanding StationSeek request. Note that StationSeek may complete before

     * cancel can occur and a callback to MRadioObserver::StationSeekComplete may occur.

     *

     * @since S60 3.0

     * @return A standard system/RadioServer error code.

     */

	IMPORT_C void CancelStationSeek();

	/**

     * Gets the signal strength of the currently tuned signal.

     *

     * @since S60 3.2

     * @param aStrength On return contains the current signal strength.

     * @return A standard system/RadioServer error code.

     */

	IMPORT_C TInt GetSignalStrength( TInt& aSignalStrength ) const;

	/**

     * Gets the maximum possible signal strength of a tuned signal.

     *

     * @since S60 3.2

     * @param aMaxStrength On return contains the maximum signal strength.

     * @return A standard system/RadioServer error code.

     */

	IMPORT_C TInt GetMaxSignalStrength( TInt& aMaxSignalStrength ) const;