MCL/sf/mw/mmmw: comparison mmmw_plat/radio_utilities

equal deleted inserted replaced

--1:000000000000
+:71ca22bcf22a
+/*
+* Copyright (c) 2006 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 provides an interface for accessing the Radio Data System (RDS)
+*                for FM sound broadcasting. CRadioRdsUtility can also be used with
+*                Radio Broadcast Data System (RDBS). Client must first instantiate
+*                CRadioFmTunerUtility before this utility can be used.
+*
+*
+*/
+#ifndef C_RADIORDSUTILITY_H
+#define C_RADIORDSUTILITY_H
+#include <RadioUtility.h>
+class RRadioSession;
+/**
+*  RDS control error definitions.
+*  In addition to the standard system error code, the following error codes may
+*  be returned.
+*/
+typedef TInt TRdsControlError;
+const TRdsControlError KRdsErrHardwareFaulty                = -13050;
+const TRdsControlError KRdsErrNotPermittedInCurrentState    = -13051;
+const TRdsControlError KRdsErrDuplicateRequest              = -13052;
+/**
+* RDS Programme Type.
+*
+* The interpretation of values of this type depends on the origin of the RDS
+* broadcast: in North America, a slightly different standard, RBDS, is used.
+* These PTY codes are defined by static values KRbdsPtyXxxxx, for example
+* KRbdsPtySoftRock.
+*
+* Elsewhere, including Europe, the RDS standard is used. In these areas, the
+* PTY codes are defined by static values KRdsPtyXxxxx, for example
+* KRdsPtyChildrensProgrammes.
+*
+* In all other important aspects, the European RDS and North American RBDS
+* standards are identical.
+*/
+typedef TInt TRdsProgrammeType;
+const TRdsProgrammeType KRdsPtyNone                = 0;
+const TRdsProgrammeType KRdsPtyNews                = 1;
+const TRdsProgrammeType KRdsPtyCurrentAffairs      = 2;
+const TRdsProgrammeType KRdsPtyInformation         = 3;
+const TRdsProgrammeType KRdsPtySport               = 4;
+const TRdsProgrammeType KRdsPtyEducation           = 5;
+const TRdsProgrammeType KRdsPtyDrama               = 6;
+const TRdsProgrammeType KRdsPtyCulture             = 7;
+const TRdsProgrammeType KRdsPtyScience             = 8;
+const TRdsProgrammeType KRdsPtyVariedSpeech        = 9;
+const TRdsProgrammeType KRdsPtyPopMusic            = 10;
+const TRdsProgrammeType KRdsPtyRockMusic           = 11;
+const TRdsProgrammeType KRdsPtyEasyListening       = 12;
+const TRdsProgrammeType KRdsPtyLightClassical      = 13;
+const TRdsProgrammeType KRdsPtySeriousClassical    = 14;
+const TRdsProgrammeType KRdsPtyOtherMusic          = 15;
+const TRdsProgrammeType KRdsPtyWeather             = 16;
+const TRdsProgrammeType KRdsPtyFinance             = 17;
+const TRdsProgrammeType KRdsPtyChildrensProgrammes = 18;
+const TRdsProgrammeType KRdsPtySocialAffairs       = 19;
+const TRdsProgrammeType KRdsPtyReligion            = 20;
+const TRdsProgrammeType KRdsPtyPhoneIn             = 21;
+const TRdsProgrammeType KRdsPtyTravel              = 22;
+const TRdsProgrammeType KRdsPtyLeisure             = 23;
+const TRdsProgrammeType KRdsPtyJazzMusic           = 24;
+const TRdsProgrammeType KRdsPtyCountryMusic        = 25;
+const TRdsProgrammeType KRdsPtyNationalMusic       = 26;
+const TRdsProgrammeType KRdsPtyOldiesMusic         = 27;
+const TRdsProgrammeType KRdsPtyFolkMusic           = 28;
+const TRdsProgrammeType KRdsPtyDocumentary         = 29;
+const TRdsProgrammeType KRdsPtyAlarmTest           = 30;
+const TRdsProgrammeType KRdsPtyAlarm               = 31;
+const TRdsProgrammeType KRbdsPtyNone               = 0;
+const TRdsProgrammeType KRbdsPtyNews               = 1;
+const TRdsProgrammeType KRbdsPtyInformation        = 2;
+const TRdsProgrammeType KRbdsPtySports             = 3;
+const TRdsProgrammeType KRbdsPtyTalk               = 4;
+const TRdsProgrammeType KRbdsPtyRock               = 5;
+const TRdsProgrammeType KRbdsPtyClassicRock        = 6;
+const TRdsProgrammeType KRbdsPtyAdultHits          = 7;
+const TRdsProgrammeType KRbdsPtySoftRock           = 8;
+const TRdsProgrammeType KRbdsPtyTop40              = 9;
+const TRdsProgrammeType KRbdsPtyCountry            = 10;
+const TRdsProgrammeType KRbdsPtyOldies             = 11;
+const TRdsProgrammeType KRbdsPtySoft               = 12;
+const TRdsProgrammeType KRbdsPtyNostalgia          = 13;
+const TRdsProgrammeType KRbdsPtyJazz               = 14;
+const TRdsProgrammeType KRbdsPtyClassical          = 15;
+const TRdsProgrammeType KRbdsPtyRhythmAndBlues     = 16;
+const TRdsProgrammeType KRbdsPtySoftRhythmAndBlues = 17;
+const TRdsProgrammeType KRbdsPtyLanguage           = 18;
+const TRdsProgrammeType KRbdsPtyReligiousMusic     = 19;
+const TRdsProgrammeType KRbdsPtyReligiousTalk      = 20;
+const TRdsProgrammeType KRbdsPtyPersonality        = 21;
+const TRdsProgrammeType KRbdsPtyPublic             = 22;
+const TRdsProgrammeType KRbdsPtyCollege            = 23;
+const TRdsProgrammeType KRbdsPtyUnassigned1        = 24;
+const TRdsProgrammeType KRbdsPtyUnassigned2        = 25;
+const TRdsProgrammeType KRbdsPtyUnassigned3        = 26;
+const TRdsProgrammeType KRbdsPtyUnassigned4        = 27;
+const TRdsProgrammeType KRbdsPtyUnassigned5        = 28;
+const TRdsProgrammeType KRbdsPtyWeather            = 29;
+const TRdsProgrammeType KRbdsPtyEmergencyTest      = 30;
+const TRdsProgrammeType KRbdsPtyEmergency          = 31;
+/**
+*  Table 1: Class codes for RTplus content types
+*  Defined in Radiotext plus (RTplus) Specification Version 2.1
+*  RDS Forum 2006-07-21 - R06/040_1
+*/
+enum TRdsRTplusClass
+{
+// Category: Item (0 - 10)
+ERTplusItemDummy = 0,
+ERTplusItemTitle,
+ERTplusItemAlbum,
+ERTplusItemTrackNumber,
+ERTplusItemArtist,
+ERTplusItemComposition,
+ERTplusItemMovement,
+ERTplusItemConductor,
+ERTplusItemComposer,
+ERTplusItemBand,
+ERTplusItemComment,
+ERTplusItemGenre,
+// Category: Info (12 - 30)
+ERTplusInfoNews,
+ERTplusInfoNewsLocal,
+ERTplusInfoStockMarket,
+ERTplusInfoSport,
+ERTplusInfoLottery,
+ERTplusInfoHoroscope,
+ERTplusInfoDailyDiversion,
+ERTplusInfoHealth,
+ERTplusInfoEvent,
+ERTplusInfoSzene,
+ERTplusInfoCinema,
+ERTplusInfoTV,
+ERTplusInfoDateTime,
+ERTplusInfoWeather,
+ERTplusInfoTraffic,
+ERTplusInfoAlarm,
+ERTplusInfoAdvisertisement,
+ERTplusInfoURL,
+ERTplusInfoOther,
+// Category: Programme (31 - 40)
+ERTplusStationNameShort,
+ERTplusStationNameLong,
+ERTplusProgramNow,
+ERTplusProgramNext,
+ERTplusProgramPart,
+ERTplusProgramHost,
+ERTplusProgramEditorialStaff,
+ERTplusStationFrequency,
+ERTplusProgramHomepage,
+ERTplusProgramSubChannel,
+// Category: Interactivity (41 - 53)
+ERTplusPhoneHotline,
+ERTplusPhoneStudio,
+ERTplusPhoneOther,
+ERTplusSmsStudio,
+ERTplusSmsOther,
+ERTplusEmailHotline,
+ERTplusEmailStudio,
+ERTplusEmailOther,
+ERTplusMmsOther,
+ERTplusChat,
+ERTplusChatCenter,
+ERTplusVoteQuestion,
+ERTplusVoteCenter,
+// Category: Reserved for future (54 - 55)
+ERTplusRfuClass54,
+ERTplusRfuClass55,
+// Category: Private classes (56 - 58)
+ERTplusPrivateClass56,
+ERTplusPrivateClass57,
+ERTplusPrivateClass58,
+// Category: Descriptor (59 - 63)
+ERTplusPlace,
+ERTplusAppointment,
+ERTplusIdentifier,
+ERTplusPurchase,
+ERTplusGetData
+};
+/**
+*  RDS Function Bit Flags used by TRdsCapabilities and TRdsData.
+*
+*  @since S60 3.2
+*/
+enum TRdsFeatures
+{
+ERdsProgrammeIdentification  = 0x001,
+ERdsProgrammeType            = 0x002,
+ERdsProgrammeService         = 0x004,
+ERdsRadioText                = 0x008,
+ERdsRadioTextPlus            = 0x010,
+ERdsClockTime                = 0x020,
+ERdsTrafficProgramme         = 0x040,
+ERdsTrafficAnnouncement      = 0x080,
+ERdsAlternateFrequency       = 0x100
+};
+/**
+*  The RDS Capabilities class defines the capabilities of the RDS control on the
+*  device, as retrieved using the function GetCapabilities.
+*
+*  @lib RadioUtility.lib
+*  @since S60 3.2
+*/
+class TRdsCapabilities
+{
+public:
+// Bitfield as defined by TRdsFeatures with the bits of the supported functions set
+// Valid bitfieds are:
+//    ERdsProgrammeIdentification | ERdsProgrammeType | ERdsProgrammeService |
+//    ERdsRadioText | ERdsRadioTextPlus | ERdsClockTime | ERdsTrafficProgramme |
+//    ERdsTrafficAnnouncement | ERdsAlternateFrequency
+TUint32 iRdsFunctions;
+// Reserved for future
+TUint32 iAdditionalFunctions1;
+// Reserved for future
+TUint32 iAdditionalFunctions2;
+};
+/**
+*  This class provides RDS features that can be enabled or disabled. Used in
+*  function NotifyRdsDataChange.
+*
+*  @lib RadioUtility.lib
+*  @since S60 3.2
+*/
+class TRdsData
+{
+public:
+// A value indicating a set containing all RDS data encapsulated by class TRdsData.
+static const TUint32 KAllRdsData = ( ERdsProgrammeIdentification | ERdsProgrammeType | ERdsProgrammeService
+| ERdsRadioText | ERdsClockTime | ERdsTrafficAnnouncement );
+public:
+// Bitfield as defined by TRdsFeatures with the bits of the supported functions set
+// Valid bitfieds are:
+//    ERdsProgrammeIdentification | ERdsProgrammeType | ERdsProgrammeService |
+//    ERdsRadioText | ERdsClockTime | ERdsTrafficAnnouncement
+TUint32 iRdsFunctions;
+// Reserved for future
+TUint32 iAdditionalFunctions1;
+// Reserved for future
+TUint32 iAdditionalFunctions2;
+};
+/** Programme Service name, 8 characters */
+typedef TBuf16<8> TRdsPSName;
+/** Radio Text, 64 characters */
+typedef TBuf16<64> TRdsRadioText;
+/**
+*  This class provides the interface class to be implemented by object receiving request
+*  complete notification from RDS control. These functions are called once the asynchronous
+*  request completes successfully or with an error.
+*
+*  In addition, this class provides the interface for receiving events from FM tuner control.
+*
+*  @since S60 3.2
+*/
+class MRadioRdsObserver
+{
+public:
+/**
+* Station seek by Programme Type(PTY) complete event. This event is asynchronous and
+* is received after a call to CRadioRdsUtility::StationSeekByPTY.
+*
+* @since S60 3.2
+* @param aError A standard system error code or RDS control error (TRdsControlError).
+* @param aFrequency The frequency(Hz) of the radio station that was found.
+*/
+virtual void MrroStationSeekByPTYComplete( TInt aError, TInt aFrequency ) = 0;
+/**
+* Station seek by Traffic Announcement(TA) complete event. This event is asynchronous
+* and is received after a call to CRadioRdsUtility::StationSeekByTA.
+*
+* @since S60 3.2
+* @param aError A standard system error code or RDS control error (TRdsControlError).
+* @param aFrequency The frequency(Hz) of the radio station that was found.
+*/
+virtual void MrroStationSeekByTAComplete( TInt aError, TInt aFrequency ) = 0;
+/**
+* Station seek by Traffic Programme(TP) complete event. This event is asynchronous and
+* is received after a call to CRadioRdsUtility::StationSeekByTP.
+*
+* @since S60 3.2
+* @param aError A standard system error code or RDS control error (TRdsControlError).
+* @param aFrequency The frequency(Hz) of the radio station that was found.
+*/
+virtual void MrroStationSeekByTPComplete( TInt aError, TInt aFrequency ) = 0;
+/**
+* Get frequencies by Programme Type(PTY) complete event. This event is asynchronous
+* and is received after a call to CRadioRdsUtility::GetFreqByPTY.
+*
+* Client takes ownership of the array and therefore is responsible for deallocating it.
+*
+* @since S60 3.2
+* @param aError A standard system error code or RDS control error (TRdsControlError).
+* @param aFreqList Array of frequencies (Hz), valid only if aError is KErrNone.
+*/
+virtual void MrroGetFreqByPTYComplete( TInt aError, RArray<TInt>& aFreqList ) = 0;
+/**
+* Get frequencies by Traffic Announcement(TA) complete event. This event is asynchronous
+* and is received after a call to CRadioRdsUtility::GetFreqByTA.
+*
+* Client takes ownership of the array and therefore is responsible for deallocating it.
+*
+* @since S60 3.2
+* @param aError A standard system error code or RDS control error (TRdsControlError).
+* @param aFreqList Array of frequencies (Hz), valid only if aError is KErrNone.
+*/
+virtual void MrroGetFreqByTAComplete( TInt aError, RArray<TInt>& aFreqList ) = 0;
+/**
+* Get Programme Service names (PS) by Programme Type(PTY) complete event. This event is
+* asynchronous and is received after a call to CRadioRdsUtility::GetPSByPTY.
+*
+* Client takes ownership of the array and therefore is responsible for deallocating it.
+*
+* @since S60 3.2
+* @param aError A standard system error code or RDS control error (TRdsControlError).
+* @param aPsList Array of programme service names, valid only if aError is KErrNone.
+*/
+virtual void MrroGetPSByPTYComplete( TInt aError, RArray<TRdsPSName>& aPsList ) = 0;
+/**
+* Get Programme Service names (PS) by Traffic Announcement(TA) complete event. This event is
+* asynchronous and is received after a call to CRadioRdsUtility::GetPSByTA.
+*
+* Client takes ownership of the array and therefore is responsible for deallocating it.
+*
+* @since S60 3.2
+* @param aError A standard system error code or RDS control error (TRdsControlError).
+* @param aPsList Array of programme service names, valid only if aError is KErrNone.
+*/
+virtual void MrroGetPSByTAComplete( TInt aError, RArray<TRdsPSName>& aPsList ) = 0;
+/**
+* New Programme Identification(PI) is available. This event is asynchronous and is
+* received after a call to CRadioRdsUtility::NotifyRdsDataChange. Client will continue to
+* receive this notification whenever new PI is available until clients unsubscribes.
+*
+* @since S60 3.2
+* @param aPi Programme identification
+*/
+virtual void MrroRdsDataPI( TInt aPi ) = 0;
+/**
+* New Programme Type(PTY) is available. This event is asynchronous and is received after
+* a call to CRadioRdsUtility::NotifyRdsDataChange. Client will continue to receive this
+* notification whenever new PTY is available until clients unsubscribes.
+*
+* @since S60 3.2
+* @param aPty Programme type
+*/
+virtual void MrroRdsDataPTY( TRdsProgrammeType aPty ) = 0;
+/**
+* New Programme Service(PS) is available. This event is asynchronous and is received after
+* a call to CRadioRdsUtility::NotifyRdsDataChange. Client will continue to receive this
+* notification whenever new PS is available until clients unsubscribes.
+*
+* @since S60 3.2
+* @param aPs Programme service
+*/
+virtual void MrroRdsDataPS( TRdsPSName& aPs ) = 0;
+/**
+* New Radio Text(RT) is available. This event is asynchronous and is received after
+* a call to CRadioRdsUtility::NotifyRdsDataChange. Client will continue to receive this
+* notification whenever new RT is available until clients unsubscribes.
+*
+* @since S60 3.2
+* @param aRt Radio text
+*/
+virtual void MrroRdsDataRT( TRdsRadioText& aRt ) = 0;
+/**
+* Clock Time(CT) is available. This event is asynchronous and is received after a call
+* to CRadioRdsUtility::NotifyRdsDataChange. Client will continue to receive this notification
+* whenever new CT is available until clients unsubscribes.
+*
+* @since S60 3.2
+* @param aCt Clock time
+*/
+virtual void MrroRdsDataCT( TDateTime& aCt ) = 0;
+/**
+* Called when Traffice Announcement(TA) status changes. This event is asynchronous
+* and is received after a call to CRadioRdsUtility::NotifyRdsDataChange. Client will continue
+* to receive this notification whenever TA status changes until clients unsubscribes.
+*
+* @since S60 3.2
+* @param aTaOn ETrue indicates that Traffic Announcement is on.
+*/
+virtual void MrroRdsDataTA( TBool aTaOn ) = 0;
+/**
+* New Radio Text+(RT+) is available. This event is asynchronous and is received after
+* a call to CRadioRdsUtility::NotifyRadioTextPlusChange. Client will continue to
+* receive this notification whenever new RT+ is available until clients unsubscribes.
+*
+* @since S60 3.2
+* @param aRtPlusClass Radio text plus class
+* @param aRtPlusData Radio text plus data
+*/
+virtual void MrroRdsDataRTplus( TRdsRTplusClass aRtPlusClass, TRdsRadioText& aRtPlusData ) = 0;
+/**
+* Called when tuner starts to search for an Alternate Frequency(AF) with stronger signal.
+* This event is asynchronous and is received after a call to
+* CRadioRdsUtility::SetAutomaticSwitching. Client will continue to receive this notification
+* whenever new search is started until clients turns automatic switching off.
+*
+* @since S60 3.2
+*/
+virtual void MrroRdsSearchBeginAF() = 0;
+/**
+* Called when search for an Alternate Frequency(AF) ends. This event is asynchronous and
+* is received after a call to CRadioRdsUtility::SetAutomaticSwitching. Client will continue
+* to receive this notification until clients turns automatic switching off.
+*
+* Most common error codes:
+* KErrNone - Successful, new frequency found
+* KErrNotFound - Ended, but frequency hasn't changed
+* KErrCancel - Cancelled
+*
+* @since S60 3.2
+* @param aError A standard system error code or RDS control error (TRdsControlError).
+* @param aFrequency The frequency(Hz) of the radio station that was found.
+*/
+virtual void MrroRdsSearchEndAF( TInt aError, TInt aFrequency ) = 0;
+	/**
+	 * Called when the tuner has re-tuned to another frequency that is broadcasting
+	 * Traffic Announcement(TA). This notification sent only when the client has turned the
+	 * automatic traffic announcement on.
+	 *
+	 * @since S60 3.2
+* @param aFrequency The frequency(Hz) of the radio station that was found.
+	 */
+	virtual void MrroRdsStationChangeTA( TInt aFrequency ) = 0;
+/**
+* Called when automatic switching (AF) setting changes.
+*
+* @since S60 3.2
+* @param aAuto ETrue indicates that automatic switching is on.
+*/
+virtual void MrroRdsEventAutomaticSwitchingChange( TBool aAuto ) = 0;
+/**
+* Called when automatic traffic announcement setting changes.
+*
+* @since S60 3.2
+* @param aAuto ETrue indicates that automatic traffic announcement is on.
+*/
+virtual void MrroRdsEventAutomaticTrafficAnnouncement( TBool aAuto ) = 0;
+/**
+* Called when 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 MrroRdsEventSignalChange( TBool aSignal ) = 0;
+};
+/**
+*  This class provides an interface to allow clients to control the RDS hardware
+*  present on a device.
+*
+*  @lib RadioUtility.lib
+*  @since S60 3.2
+*/
+class CRadioRdsUtility : public CBase
+{
+friend class CRadioUtility::CBody;
+public:
+/**
+* Close the RDS utility and free all memory allocated.
+*
+* @since S60 3.2
+*/
+	IMPORT_C void Close();
+	/**
+* Get the capabilities of the RDS control on the device.
+*
+* @since S60 3.2
+* @param aCaps The capabilities object to fill
+* @return A standard system error code or RDS control error (TRdsControlError).
+*/
+IMPORT_C TInt GetCapabilities( TRdsCapabilities& aCaps ) const;
+/**
+* Get the status of the RDS reception.
+*
+* @since S60 3.2
+* @param aRdsSignal On return, will be ETrue if RDS signal can be recepted, EFalse otherwise.
+* @return A standard system error code or RDS control error (TRdsControlError).
+*/
+IMPORT_C TInt GetRdsSignalStatus( TBool& aRdsSignal ) const;
+/**
+* Subscribe for notification for the specified RDS data. Client should first check
+* the capabilities to see if a feature is supported.
+* Request for notification for non-supported features will simply be ignored.
+*
+* For example, if the client wishes to be notified when new Programme Type and
+* Traffic Announcement is available:
+*      iRdsData = ERdsProgrammeType | ERdsTrafficAnnouncement;
+*      iRdsUtility->NotifyRdsDataChange(iRdsData);
+*
+* @since S60 3.2
+* @param aRdsData Bitfield indicating notification request.
+* @see MRadioRdsObserver::MrroRdsDataPI
+* @see MRadioRdsObserver::MrroRdsDataPTY
+* @see MRadioRdsObserver::MrroRdsDataPS
+* @see MRadioRdsObserver::MrroRdsDataRT
+* @see MRadioRdsObserver::MrroRdsDataCT
+* @see MRadioRdsObserver::MrroRdsDataTA
+*/
+IMPORT_C TInt NotifyRdsDataChange( TRdsData aRdsData );
+/**
+* Cancel NotifyRdsDataChange request.
+*
+* @since S60 3.2
+*/
+IMPORT_C void CancelNotifyRdsDataChange();
+/**
+* Subscribe for notification for the specified RadioText+ data. Client should first check
+* the capabilities to see if RT+ feature is supported.
+* Returns KErrNotSupported if RT+ is not supported.
+*
+* For example, if the client wishes to be notified only when new Title and Genre are available:
+*      iRtPlusClassArray.Append(ERTplusItemTitle);
+*      iRtPlusClassArray.Append(ERTplusItemTitle);
+*      iRdsUtility->NotifyRadioTextPlusChangeL(iRtPlusClassArray);
+*
+* Note that if the client wishes to receive the entire radio text data chunk, client should
+* subscribe for ERdsRadioText using NotifyRdsDataChange instead.
+*
+* @since S60 3.2
+* @param aRtPlusClasses Array of RT+ class to be notified
+* @see MRadioRdsObserver::MrroRdsDataRTplus
+*/
+IMPORT_C TInt NotifyRadioTextPlusChange( RArray<TInt>& aRtPlusClasses );
+/**
+* Cancel NotifyRadioTextPlusChange request.
+*
+* @since S60 3.2
+*/
+IMPORT_C void CancelNotifyRadioTextPlusChange();
+/**
+* Turn on/off automatic switching of frequency based on Alternate Frequency.
+* This will cause RDS device to search for alternate frequency when the signal strength
+* deteriorates. User should be ready to receive MrroRdsSearchBeginAF and MrroRdsSearchEndAF.
+* Automatic switching is off by default.
+*
+* @since S60 3.2
+* @param aAuto ETrue to turn automatic switching on, EFalse to turn it off.
+* @return A standard system error code.
+* @see MRadioRdsObserver::MrroRdsSearchBeginAF
+* @see MRadioRdsObserver::MrroRdsSearchEndAF
+*/
+IMPORT_C TInt SetAutomaticSwitching( TBool aAuto );
+/**
+* Find out whether automatic switching is on or off.
+*
+* @since S60 3.2
+* @param aAuto On return, ETrue indicates that automatic switching is enabled.
+* @return A standard system error code.
+*/
+IMPORT_C TInt GetAutomaticSwitching( TBool& aAuto );
+/**
+* Cancel ongoing search for an Alternate Frequency (AF) with stronger signal.
+*
+* Client can issue this request to interrupt the search indicated with
+* MRadioRdsObserver::MrroRdsSearchBeginAF.
+*
+* @since S60 3.2
+*/
+IMPORT_C void CancelAFSearch();
+/**
+* Turns on/off automatic switching of frequency based on Traffic Announcement.
+* This will cause RDS device to search for frequencies broadcasting traffic announcement.
+* Client will be notified of frequency change though the tuner event.
+* It's up to the client to return to the previous frequency when the traffic announcement
+* is finished.
+*
+* NOTE: This is only supported in dual tuner configuration since the secondary tuner
+* needs to perform continuous scanning for frequency broadcasting traffic announcement,
+* while the primary tuner is used for normal tuner activities.
+*
+* @since S60 3.2
+* @param aAuto ETrue indicates that automatic switching is on.
+* @return A standard system error code.
+*/
+IMPORT_C TInt SetAutomaticTrafficAnnouncement( TBool aAuto );
+/**
+* Find out whether automatic traffic announcement is enabled.
+*
+* @since S60 3.2
+* @param aAuto On return, ETrue indicates that automatic traffic announcement is on.
+* @return A standard system error code.
+*/
+IMPORT_C TInt GetAutomaticTrafficAnnouncement( TBool& aAuto );
+/**
+* Asynchronous request to find a radio station with the specified Programme Type(PTY),
+* starting from the currently tuned frequency and searching in the direction specified
+* (i.e. up or down). User must be ready to receive callback method MrroStationSeekByPTYComplete
+* The station found is returned in the callback.
+*
+* @since S60 3.2
+* @param aPty The type of programme to search for.
+* @param aSeekUp The direction to search in. Searches upwards if set to ETrue.
+* @see MRadioRdsObserver::MrroStationSeekByPTYComplete
+*/
+IMPORT_C void StationSeekByPTY( TRdsProgrammeType aPty, TBool aSeekUp );
+/**
+* Asynchronous request to find a radio station with Traffic Announcement(TA),
+* starting from the currently tuned frequency and searching in the direction specified
+* (i.e. up or down). User must be ready to receive callback method MrroStationSeekByTAComplete
+* The station found is returned in the callback.
+*
+* @since S60 3.2
+* @param aSeekUp The direction to search in. Searches upwards if set to ETrue.
+* @see MRadioRdsObserver::MrroStationSeekByTAComplete
+*/
+IMPORT_C void StationSeekByTA( TBool aSeekUp );
+/**
+* Asynchronous request to find a radio station with Traffic Programme(TP),
+* starting from the currently tuned frequency and searching in the direction specified
+* (i.e. up or down). User must be ready to receive callback method MrroStationSeekByTPComplete
+* The station found is returned in the callback.
+*
+* @since S60 3.2
+* @param aSeekUp The direction to search in. Searches upwards if set to ETrue.
+* @see MRadioRdsObserver::MrroStationSeekByTPComplete
+*/
+IMPORT_C void StationSeekByTP( TBool aSeekUp );
+/**
+* Cancels an ongoing retune operation, as initiated by a call to StationSeekByPTY,
+* StationSeekByTA, or StationSeekByTP.
+* The usual callback will not occur if this has been called.
+*
+* @since S60 3.2
+*/
+IMPORT_C void CancelRdsStationSeek();
+/**
+* Asynchronous request to find all frequencies sending the given Programme Type (PTY).
+* User must be ready to receive callback method MrroGetFreqByPTYComplete.
+*
+* NOTE: This is only supported in dual tuner configuration since the secondary tuner
+* needs to perform continuous scanning for frequencies broadcasting given Programme Type
+* while the primary tuner is used for normal tuner activities.
+* Client should first check the tuner capabilities. Will return KErrNotSupported in
+* callback method if this feature is not supported.
+*
+* @since S60 3.2
+* @param aPty The type of programme to search for
+* @see MRadioRdsObserver::MrroGetFreqByPTYComplete
+*/
+IMPORT_C void GetFreqByPTY( TRdsProgrammeType aPty );
+/**
+* Cancels an ongoing request to find all frequencies sending a given Programme Type (PTY).
+* The usual callback will not occur if this has been called.
+*
+* @since S60 3.2
+*/
+IMPORT_C void CancelGetFreqByPTY();
+/**
+* Asynchronous request to find all frequencies sending Traffic Announcement (TA). User must
+* be ready to receive callback method MrroGetFreqByTAComplete.
+*
+* NOTE: This is only supported in dual tuner configuration since the secondary tuner
+* needs to perform continuous scanning for frequencies broadcasting given Traffic Announcement
+* while the primary tuner is used for normal tuner activities.
+* Client should first check the tuner capabilities. Will return KErrNotSupported in
+* callback method if this feature is not supported.
+*
+* @since S60 3.2
+* @see MRadioRdsObserver::MrroGetFreqByTAComplete
+*/
+IMPORT_C void GetFreqByTA();
+/**
+* Cancels an ongoing request to find all frequencies sending Traffic Announcement.
+* The usual callback will not occur if this has been called.
+*
+* @since S60 3.2
+*/
+IMPORT_C void CancelGetFreqByTA();
+/**
+* Asynchronous request to find all Programme Service names (PS) sending the given Programme
+* Type (PTY). User must be ready to receive callback method MrroGetPSByPTYComplete.
+*
+* NOTE: This is only supported in dual tuner configuration since the secondary tuner
+* needs to perform continuous scanning for frequencies broadcasting given Programme Type
+* while the primary tuner is used for normal tuner activities.
+* Client should first check the tuner capabilities. Will return KErrNotSupported in
+* callback method if this feature is not supported.
+*
+* @since S60 3.2
+* @param aPty The type of programme to search for
+* @see MRadioRdsObserver::MrroGetPSByPTYComplete
+*/
+IMPORT_C void GetPSByPTY( TRdsProgrammeType aPty );
+/**
+* Cancels an ongoing request to find all Programme Service names (PS) sending a given
+* Programme Type (PTY). The usual callback will not occur if this has been called.
+*
+* @since S60 3.2
+*/
+IMPORT_C void CancelGetPSByPTY();
+/**
+* Asynchronous request to find all Programme Service names (PS) sending Traffic Announcement (TA).
+* User must be ready to receive callback method MrroGetPSByTAComplete.
+*
+* NOTE: This is only supported in dual tuner configuration since the secondary tuner
+* needs to perform continuous scanning for frequencies broadcasting given Traffic Announcement
+* while the primary tuner is used for normal tuner activities.
+* Client should first check the tuner capabilities. Will return KErrNotSupported in
+* callback method if this feature is not supported.
+*
+* @since S60 3.2
+* @see MRadioRdsObserver::MrroGetPSByTAComplete
+*/
+IMPORT_C void GetPSByTA();
+/**
+* Cancels an ongoing request to find all Programme Service names (PS) sending Traffic Announcement.
+* The usual callback will not occur if this has been called.
+*
+* @since S60 3.2
+*/
+IMPORT_C void CancelGetPSByTA();
+/**
+* Get the current Programme Identification code.
+* RDS data is received over the air and may not be available immediately following
+* tune operation. If data is not available, this function will return KErrNotFound.
+* If a value is returned, this is the last known value, which may not be up to date.
+* To be notified of the most recent value, client should use NotifyRdsDataChange.
+*
+* @since S60 3.2
+* @param aPi On return contains Programme Identification code
+* @return A standard system error code or RDS control error (TRdsControlError).
+*/
+IMPORT_C TInt GetProgrammeIdentification( TInt& aPi );
+/**
+* Get the current Programme Type.
+* RDS data is received over the air and may not be available immediately following
+* tune operation. If data is not available, this function will return KErrNotFound.
+* If a value is returned, this is the last known value, which may not be up to date.
+* To be notified of the most recent value, client should use NotifyRdsDataChange.
+*
+* @since S60 3.2
+* @param aPty On return contains Programme Type
+* @return A standard system error code or RDS control error (TRdsControlError).
+*/
+IMPORT_C TInt GetProgrammeType( TRdsProgrammeType& aPty );
+/**
+* Get the current Programme Service name.
+* RDS data is received over the air and may not be available immediately following
+* tune operation. If data is not available, this function will return KErrNotFound.
+* If a value is returned, this is the last known value, which may not be up to date.
+* To be notified of the most recent value, client should use NotifyRdsDataChange.
+*
+* Programme Service name is fixed to 8 characters.
+*
+* @since S60 3.2
+* @param aPs On return contains Programme Service name
+* @return A standard system error code or RDS control error (TRdsControlError).
+*/
+IMPORT_C TInt GetProgrammeService( TRdsPSName& aPs );
+/**
+* Get the current Radio Text.
+* RDS data is received over the air and may not be available immediately following
+* tune operation. If data is not available, this function will return KErrNotFound.
+* If a value is returned, this is the last known value, which may not be up to date.
+* To be notified of the most recent value, client should use NotifyRdsDataChange.
+*
+* The maximum possible length for radio text is 64 characters.
+*
+* @since S60 3.2
+* @param aRt On return contains Radio Text
+* @return A standard system error code or RDS control error (TRdsControlError).
+*/
+IMPORT_C TInt GetRadioText( TRdsRadioText& aRt );
+/**
+* Get the current Radio Text+.
+* RDS data is received over the air and may not be available immediately following
+* tune operation. If data is not available, this function will return KErrNotFound.
+* If a value is returned, this is the last known value, which may not be up to date.
+* To be notified of the most recent value, client should use NotifyRdsDataChange.
+*
+* The maximum possible length for radio text+ field is 64 characters.
+*
+* @since S60 3.2
+* @param aRtPlusClass Radio text plus class
+* @param aRtPlusData On return contains Radio Text+ field
+* @return A standard system error code or RDS control error (TRdsControlError).
+*/
+IMPORT_C TInt GetRadioTextPlus( TRdsRTplusClass aRtPlusClass, TRdsRadioText& aRtPlusData );
+/**
+* Get the current Clock Time and date.
+* RDS data is received over the air and may not be available immediately following
+* tune operation. If data is not available, this function will return KErrNotFound.
+* If a value is returned, this is the last known value, which may not be up to date.
+* To be notified of the most recent value, client should use NotifyRdsDataChange.
+*
+* @since S60 3.2
+* @param aCt On return contains current time and date
+* @return A standard system error code or RDS control error (TRdsControlError).
+*/
+IMPORT_C TInt GetClockTime( TDateTime& aCt );
+/**
+* Get Traffic Announcement status at the current station.
+*
+* @since S60 3.2
+* @param aTaStatus On return, will be ETrue if current station has ongoing traffic announcement
+* @return A standard system error code or RDS control error (TRdsControlError).
+*/
+IMPORT_C TInt GetTrafficAnnouncementStatus( TBool& aTaStatus );
+/**
+* Get Traffic Programme status at the current station.
+*
+* @since S60 3.2
+* @param aTpStatus On return, will be ETrue if current station supports traffic programme
+* @return A standard system error code or RDS control error (TRdsControlError).
+*/
+IMPORT_C TInt GetTrafficProgrammeStatus( TBool& aTpStatus );
+private:
+/**
+* Factory function to create a new instance of the RDS utility.
+*
+* @since S60 3.2
+* @param aRadioSession Reference to radio session
+* @param aObserver The observer object for receiving async completion callbacks
+* @return A new RDS utility object.
+*/
+static CRadioRdsUtility* NewL( RRadioSession& aRadioSession, MRadioRdsObserver& aObserver );
+virtual ~CRadioRdsUtility();
+CRadioRdsUtility();
+void ConstructL();
+private: // data
+class CBody;
+/**
+* RDS utility implementation body
+* Own.
+*/
+CBody* iBody;
+};
+#endif    // C_RADIORDSUTILITY_H
+// End of File