CRadioRdsUtility Class Reference

class CRadioRdsUtility : public CBase

This class provides an interface to allow clients to control the RDS hardware present on a device.

RadioUtility.lib
Since
S60 3.2

Inherits from

Nested Classes and Structures

Public Member Functions
IMPORT_C voidCancelAFSearch()
IMPORT_C voidCancelGetFreqByPTY()
IMPORT_C voidCancelGetFreqByTA()
IMPORT_C voidCancelGetPSByPTY()
IMPORT_C voidCancelGetPSByTA()
IMPORT_C voidCancelNotifyRadioTextPlusChange()
IMPORT_C voidCancelNotifyRdsDataChange()
IMPORT_C voidCancelRdsStationSeek()
IMPORT_C voidClose()
IMPORT_C TIntGetAutomaticSwitching(TBool &)
IMPORT_C TIntGetAutomaticTrafficAnnouncement(TBool &)
IMPORT_C TIntGetCapabilities(TRdsCapabilities &)
IMPORT_C TIntGetClockTime(TDateTime &)
IMPORT_C voidGetFreqByPTY(TRdsProgrammeType)
IMPORT_C voidGetFreqByTA()
IMPORT_C voidGetPSByPTY(TRdsProgrammeType)
IMPORT_C voidGetPSByTA()
IMPORT_C TIntGetProgrammeIdentification(TInt &)
IMPORT_C TIntGetProgrammeService(TRdsPSName &)
IMPORT_C TIntGetProgrammeType(TRdsProgrammeType &)
IMPORT_C TIntGetRadioText(TRdsRadioText &)
IMPORT_C TIntGetRadioTextPlus(TRdsRTplusClass, TRdsRadioText &)
IMPORT_C TIntGetRdsSignalStatus(TBool &)
IMPORT_C TIntGetTrafficAnnouncementStatus(TBool &)
IMPORT_C TIntGetTrafficProgrammeStatus(TBool &)
IMPORT_C TIntNotifyRadioTextPlusChange(RArray< TInt > &)
IMPORT_C TIntNotifyRdsDataChange(TRdsData)
IMPORT_C TIntSetAutomaticSwitching(TBool)
IMPORT_C TIntSetAutomaticTrafficAnnouncement(TBool)
IMPORT_C voidStationSeekByPTY(TRdsProgrammeType, TBool)
IMPORT_C voidStationSeekByTA(TBool)
IMPORT_C voidStationSeekByTP(TBool)
Private Member Functions
CRadioRdsUtility()
~CRadioRdsUtility()
voidConstructL()
CRadioRdsUtility *NewL(RRadioSession &, MRadioRdsObserver &)
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
Private Attributes
CBody *iBody

Constructor & Destructor Documentation

CRadioRdsUtility()

CRadioRdsUtility()[private]

~CRadioRdsUtility()

~CRadioRdsUtility()[private, virtual]

Member Functions Documentation

CancelAFSearch()

IMPORT_C voidCancelAFSearch()

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

CancelGetFreqByPTY()

IMPORT_C voidCancelGetFreqByPTY()

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

CancelGetFreqByTA()

IMPORT_C voidCancelGetFreqByTA()

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

CancelGetPSByPTY()

IMPORT_C voidCancelGetPSByPTY()

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

CancelGetPSByTA()

IMPORT_C voidCancelGetPSByTA()

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

CancelNotifyRadioTextPlusChange()

IMPORT_C voidCancelNotifyRadioTextPlusChange()

Cancel NotifyRadioTextPlusChange request.

Since
S60 3.2

CancelNotifyRdsDataChange()

IMPORT_C voidCancelNotifyRdsDataChange()

Cancel NotifyRdsDataChange request.

Since
S60 3.2

CancelRdsStationSeek()

IMPORT_C voidCancelRdsStationSeek()

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

Close()

IMPORT_C voidClose()

Close the RDS utility and free all memory allocated.

Since
S60 3.2

ConstructL()

voidConstructL()[private]

GetAutomaticSwitching(TBool &)

IMPORT_C TIntGetAutomaticSwitching(TBool &aAuto)

Find out whether automatic switching is on or off.

Since
S60 3.2

Parameters

TBool & aAutoOn return, ETrue indicates that automatic switching is enabled.

GetAutomaticTrafficAnnouncement(TBool &)

IMPORT_C TIntGetAutomaticTrafficAnnouncement(TBool &aAuto)

Find out whether automatic traffic announcement is enabled.

Since
S60 3.2

Parameters

TBool & aAutoOn return, ETrue indicates that automatic traffic announcement is on.

GetCapabilities(TRdsCapabilities &)

IMPORT_C TIntGetCapabilities(TRdsCapabilities &aCaps)const

Get the capabilities of the RDS control on the device.

Since
S60 3.2

Parameters

TRdsCapabilities & aCapsThe capabilities object to fill

GetClockTime(TDateTime &)

IMPORT_C TIntGetClockTime(TDateTime &aCt)

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

Parameters

TDateTime & aCtOn return contains current time and date

GetFreqByPTY(TRdsProgrammeType)

IMPORT_C voidGetFreqByPTY(TRdsProgrammeTypeaPty)

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.

Parameters

TRdsProgrammeType aPtyThe type of programme to search for

GetFreqByTA()

IMPORT_C voidGetFreqByTA()

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.

GetPSByPTY(TRdsProgrammeType)

IMPORT_C voidGetPSByPTY(TRdsProgrammeTypeaPty)

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.

Parameters

TRdsProgrammeType aPtyThe type of programme to search for

GetPSByTA()

IMPORT_C voidGetPSByTA()

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.

GetProgrammeIdentification(TInt &)

IMPORT_C TIntGetProgrammeIdentification(TInt &aPi)

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

Parameters

TInt & aPiOn return contains Programme Identification code

GetProgrammeService(TRdsPSName &)

IMPORT_C TIntGetProgrammeService(TRdsPSName &aPs)

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

Parameters

TRdsPSName & aPsOn return contains Programme Service name

GetProgrammeType(TRdsProgrammeType &)

IMPORT_C TIntGetProgrammeType(TRdsProgrammeType &aPty)

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

Parameters

TRdsProgrammeType & aPtyOn return contains Programme Type

GetRadioText(TRdsRadioText &)

IMPORT_C TIntGetRadioText(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 is 64 characters.

Since
S60 3.2

Parameters

TRdsRadioText & aRtOn return contains Radio Text

GetRadioTextPlus(TRdsRTplusClass, TRdsRadioText &)

IMPORT_C TIntGetRadioTextPlus(TRdsRTplusClassaRtPlusClass,
TRdsRadioText &aRtPlusData
)

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

Parameters

TRdsRTplusClass aRtPlusClassRadio text plus class
TRdsRadioText & aRtPlusDataOn return contains Radio Text+ field

GetRdsSignalStatus(TBool &)

IMPORT_C TIntGetRdsSignalStatus(TBool &aRdsSignal)const

Get the status of the RDS reception.

Since
S60 3.2

Parameters

TBool & aRdsSignalOn return, will be ETrue if RDS signal can be recepted, EFalse otherwise.

GetTrafficAnnouncementStatus(TBool &)

IMPORT_C TIntGetTrafficAnnouncementStatus(TBool &aTaStatus)

Get Traffic Announcement status at the current station.

Since
S60 3.2

Parameters

TBool & aTaStatusOn return, will be ETrue if current station has ongoing traffic announcement

GetTrafficProgrammeStatus(TBool &)

IMPORT_C TIntGetTrafficProgrammeStatus(TBool &aTpStatus)

Get Traffic Programme status at the current station.

Since
S60 3.2

Parameters

TBool & aTpStatusOn return, will be ETrue if current station supports traffic programme

NewL(RRadioSession &, MRadioRdsObserver &)

CRadioRdsUtility *NewL(RRadioSession &aRadioSession,
MRadioRdsObserver &aObserver
)[private, static]

Factory function to create a new instance of the RDS utility.

Since
S60 3.2

Parameters

RRadioSession & aRadioSessionReference to radio session
MRadioRdsObserver & aObserverThe observer object for receiving async completion callbacks

NotifyRadioTextPlusChange(RArray< TInt > &)

IMPORT_C TIntNotifyRadioTextPlusChange(RArray< TInt > &aRtPlusClasses)

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.

Parameters

RArray< TInt > & aRtPlusClassesArray of RT+ class to be notified

NotifyRdsDataChange(TRdsData)

IMPORT_C TIntNotifyRdsDataChange(TRdsDataaRdsData)

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);

Parameters

TRdsData aRdsDataBitfield indicating notification request.

SetAutomaticSwitching(TBool)

IMPORT_C TIntSetAutomaticSwitching(TBoolaAuto)

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.

Parameters

TBool aAutoETrue to turn automatic switching on, EFalse to turn it off.

SetAutomaticTrafficAnnouncement(TBool)

IMPORT_C TIntSetAutomaticTrafficAnnouncement(TBoolaAuto)

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

Parameters

TBool aAutoETrue indicates that automatic switching is on.

StationSeekByPTY(TRdsProgrammeType, TBool)

IMPORT_C voidStationSeekByPTY(TRdsProgrammeTypeaPty,
TBoolaSeekUp
)

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.

Parameters

TRdsProgrammeType aPtyThe type of programme to search for.
TBool aSeekUpThe direction to search in. Searches upwards if set to ETrue.

StationSeekByTA(TBool)

IMPORT_C voidStationSeekByTA(TBoolaSeekUp)

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.

Parameters

TBool aSeekUpThe direction to search in. Searches upwards if set to ETrue.

StationSeekByTP(TBool)

IMPORT_C voidStationSeekByTP(TBoolaSeekUp)

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.

Parameters

TBool aSeekUpThe direction to search in. Searches upwards if set to ETrue.

Member Data Documentation

CBody * iBody

CBody *iBody[private]

RDS utility implementation body Own.