diff -r 000000000000 -r 71ca22bcf22a mmmw_plat/radio_utilities_api/inc/RadioRdsUtility.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/mmmw_plat/radio_utilities_api/inc/RadioRdsUtility.h Tue Feb 02 01:08:46 2010 +0200 @@ -0,0 +1,930 @@ +/* +* 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 + +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& 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& 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& 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& 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& 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 \ No newline at end of file