Collapse all Symbian^3 Application Developer Library

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

CRadioRdsUtility
- CBase

Nested Classes and Structures

CRadioRdsUtility::CBody

Public Member Functions
IMPORT_C void	CancelAFSearch ()
IMPORT_C void	CancelGetFreqByPTY ()
IMPORT_C void	CancelGetFreqByTA ()
IMPORT_C void	CancelGetPSByPTY ()
IMPORT_C void	CancelGetPSByTA ()
IMPORT_C void	CancelNotifyRadioTextPlusChange ()
IMPORT_C void	CancelNotifyRdsDataChange ()
IMPORT_C void	CancelRdsStationSeek ()
IMPORT_C void	Close ()
IMPORT_C TInt	GetAutomaticSwitching ( TBool &)
IMPORT_C TInt	GetAutomaticTrafficAnnouncement ( TBool &)
IMPORT_C TInt	GetCapabilities ( TRdsCapabilities &)
IMPORT_C TInt	GetClockTime ( TDateTime &)
IMPORT_C void	GetFreqByPTY ( TRdsProgrammeType )
IMPORT_C void	GetFreqByTA ()
IMPORT_C void	GetPSByPTY ( TRdsProgrammeType )
IMPORT_C void	GetPSByTA ()
IMPORT_C TInt	GetProgrammeIdentification ( TInt &)
IMPORT_C TInt	GetProgrammeService ( TRdsPSName &)
IMPORT_C TInt	GetProgrammeType ( TRdsProgrammeType &)
IMPORT_C TInt	GetRadioText ( TRdsRadioText &)
IMPORT_C TInt	GetRadioTextPlus ( TRdsRTplusClass , TRdsRadioText &)
IMPORT_C TInt	GetRdsSignalStatus ( TBool &)
IMPORT_C TInt	GetTrafficAnnouncementStatus ( TBool &)
IMPORT_C TInt	GetTrafficProgrammeStatus ( TBool &)
IMPORT_C TInt	NotifyRadioTextPlusChange ( RArray < TInt > &)
IMPORT_C TInt	NotifyRdsDataChange ( TRdsData )
IMPORT_C TInt	SetAutomaticSwitching ( TBool )
IMPORT_C TInt	SetAutomaticTrafficAnnouncement ( TBool )
IMPORT_C void	StationSeekByPTY ( TRdsProgrammeType , TBool )
IMPORT_C void	StationSeekByTA ( TBool )
IMPORT_C void	StationSeekByTP ( TBool )

Private Member Functions
	CRadioRdsUtility ()
	~CRadioRdsUtility ()
void	ConstructL ()
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 void

CancelAFSearch

(

)

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 void

CancelGetFreqByPTY

(

)

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 void

CancelGetFreqByTA

(

)

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 void

CancelGetPSByPTY

(

)

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 void

CancelGetPSByTA

(

)

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 void

CancelNotifyRadioTextPlusChange

(

)

Cancel NotifyRadioTextPlusChange request.

Since: S60 3.2

CancelNotifyRdsDataChange()

IMPORT_C void

CancelNotifyRdsDataChange

(

)

Cancel NotifyRdsDataChange request.

Since: S60 3.2

CancelRdsStationSeek()

IMPORT_C void

CancelRdsStationSeek

(

)

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 void

(

)

Close the RDS utility and free all memory allocated.

Since: S60 3.2

ConstructL()

void

ConstructL

(

)

[private]

GetAutomaticSwitching(TBool &)

IMPORT_C TInt

GetAutomaticSwitching

(

TBool &

aAuto

)

Find out whether automatic switching is on or off.

Since: S60 3.2

Parameters

TBool & aAuto

On return, ETrue indicates that automatic switching is enabled.

GetAutomaticTrafficAnnouncement(TBool &)

IMPORT_C TInt

GetAutomaticTrafficAnnouncement

(

TBool &

aAuto

)

Find out whether automatic traffic announcement is enabled.

Since: S60 3.2

Parameters

TBool & aAuto

On return, ETrue indicates that automatic traffic announcement is on.

GetCapabilities(TRdsCapabilities &)

IMPORT_C TInt

GetCapabilities

(

TRdsCapabilities &

aCaps

)

const

Get the capabilities of the RDS control on the device.

Since: S60 3.2

Parameters

TRdsCapabilities & aCaps

The capabilities object to fill

GetClockTime(TDateTime &)

IMPORT_C TInt

GetClockTime

(

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 & aCt

On return contains current time and date

GetFreqByPTY(TRdsProgrammeType)

IMPORT_C void

GetFreqByPTY

(

TRdsProgrammeType

aPty

)

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

MRadioRdsObserver::MrroGetFreqByPTYComplete

Parameters

TRdsProgrammeType aPty

The type of programme to search for

GetFreqByTA()

IMPORT_C void

GetFreqByTA

(

)

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

MRadioRdsObserver::MrroGetFreqByTAComplete

GetPSByPTY(TRdsProgrammeType)

IMPORT_C void

GetPSByPTY

(

TRdsProgrammeType

aPty

)

Asynchronous request to find all Programme Service names (PS) sending the given Programme Type (PTY). User must be ready to receive callback method MrroGetPSByPTYComplete.

Since: S60 3.2

MRadioRdsObserver::MrroGetPSByPTYComplete

Parameters

TRdsProgrammeType aPty

The type of programme to search for

GetPSByTA()

IMPORT_C void

GetPSByTA

(

)

Asynchronous request to find all Programme Service names (PS) sending Traffic Announcement (TA). User must be ready to receive callback method MrroGetPSByTAComplete.

Since: S60 3.2

MRadioRdsObserver::MrroGetPSByTAComplete

GetProgrammeIdentification(TInt &)

IMPORT_C TInt

GetProgrammeIdentification

(

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 & aPi

On return contains Programme Identification code

GetProgrammeService(TRdsPSName &)

IMPORT_C TInt

GetProgrammeService

(

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 & aPs

On return contains Programme Service name

GetProgrammeType(TRdsProgrammeType &)

IMPORT_C TInt

GetProgrammeType

(

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 & aPty

On return contains Programme Type

GetRadioText(TRdsRadioText &)

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

Since: S60 3.2

Parameters

TRdsRadioText & aRt

On return contains Radio Text

GetRadioTextPlus(TRdsRTplusClass, TRdsRadioText &)

IMPORT_C TInt	GetRadioTextPlus	(	TRdsRTplusClass	aRtPlusClass,
			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 aRtPlusClass	Radio text plus class
TRdsRadioText & aRtPlusData	On return contains Radio Text+ field

GetRdsSignalStatus(TBool &)

IMPORT_C TInt

GetRdsSignalStatus

(

TBool &

aRdsSignal

)

const

Get the status of the RDS reception.

Since: S60 3.2

Parameters

TBool & aRdsSignal

On return, will be ETrue if RDS signal can be recepted, EFalse otherwise.

GetTrafficAnnouncementStatus(TBool &)

IMPORT_C TInt

GetTrafficAnnouncementStatus

(

TBool &

aTaStatus

)

Get Traffic Announcement status at the current station.

Since: S60 3.2

Parameters

TBool & aTaStatus

On return, will be ETrue if current station has ongoing traffic announcement

GetTrafficProgrammeStatus(TBool &)

IMPORT_C TInt

GetTrafficProgrammeStatus

(

TBool &

aTpStatus

)

Get Traffic Programme status at the current station.

Since: S60 3.2

Parameters

TBool & aTpStatus

On 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 & aRadioSession	Reference to radio session
MRadioRdsObserver & aObserver	The observer object for receiving async completion callbacks

NotifyRadioTextPlusChange(RArray< TInt > &)

IMPORT_C TInt

NotifyRadioTextPlusChange

(

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.

Since: S60 3.2

MRadioRdsObserver::MrroRdsDataRTplus

Parameters

RArray < TInt > & aRtPlusClasses

Array of RT+ class to be notified

NotifyRdsDataChange(TRdsData)

IMPORT_C TInt

NotifyRdsDataChange

(

TRdsData

aRdsData

)

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

MRadioRdsObserver::MrroRdsDataPI MRadioRdsObserver::MrroRdsDataPTY MRadioRdsObserver::MrroRdsDataPS MRadioRdsObserver::MrroRdsDataRT MRadioRdsObserver::MrroRdsDataCT MRadioRdsObserver::MrroRdsDataTA

Parameters

TRdsData aRdsData

Bitfield indicating notification request.

SetAutomaticSwitching(TBool)

IMPORT_C TInt

SetAutomaticSwitching

(

TBool

aAuto

)

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

MRadioRdsObserver::MrroRdsSearchBeginAF MRadioRdsObserver::MrroRdsSearchEndAF

Parameters

TBool aAuto

ETrue to turn automatic switching on, EFalse to turn it off.

SetAutomaticTrafficAnnouncement(TBool)

IMPORT_C TInt

SetAutomaticTrafficAnnouncement

(

TBool

aAuto

)

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 aAuto

ETrue indicates that automatic switching is on.

StationSeekByPTY(TRdsProgrammeType, TBool)

IMPORT_C void	StationSeekByPTY	(	TRdsProgrammeType	aPty,
			TBool	aSeekUp
		)

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

MRadioRdsObserver::MrroStationSeekByPTYComplete

Parameters

TRdsProgrammeType aPty	The type of programme to search for.
TBool aSeekUp	The direction to search in. Searches upwards if set to ETrue.

StationSeekByTA(TBool)

IMPORT_C void

StationSeekByTA

(

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

MRadioRdsObserver::MrroStationSeekByTAComplete

Parameters

TBool aSeekUp

The direction to search in. Searches upwards if set to ETrue.

StationSeekByTP(TBool)

IMPORT_C void

StationSeekByTP

(

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

MRadioRdsObserver::MrroStationSeekByTPComplete

Parameters

TBool aSeekUp

The direction to search in. Searches upwards if set to ETrue.

Member Data Documentation

CBody * iBody

CBody *

iBody

[private]

RDS utility implementation body Own.