Class CMMRdsTunerUtility

class CMMRdsTunerUtility : public CBase;

Description

The RDS class augments the tuner API to give access to the RDS capabilities of the device. As such additional tuner technologies can be supported without changing the Tuner API.

Note that despite this class being names 'RDS', it is capable of supporting both the RDS standard, and the North American equivilant RBDS. The only important difference from the APIs perspective is the interpretation of the Programme Type (PTY) codes. See TRdsProgrammeType for more information.

Derivation

• CBase - Base class for all classes to be instantiated on the heap

• CMMRdsTunerUtility - The RDS class augments the tuner API to give access to the RDS capabilities of the device

Members

Defined in CMMRdsTunerUtility:
CancelGetRdsTime(), CancelNotifyAlternativeFrequencies(), CancelNotifyAnnouncement(), CancelNotifyEonInfo(), CancelNotifyRadioText(), CancelNotifyRdsDataChange(), CancelNotifyRdsSignalChange(), CancelNotifyRdsStateChange(), CancelRdsSearch(), CancelReceiveRdsFrames(), ConvertRdsLanguageId(), ConvertRdsLanguageId(), CustomCommandAsync(), CustomCommandSync(), ERdsNewsAnnouncement, ERdsTrafficAnnouncement, GetAlternativeFrequency(), GetAlternativeFrequencyListL(), GetAnnouncementVolume(), GetAnnouncementVolumeOffset(), GetEonFrequenciesL(), GetEonInfoL(), GetEonMappedFrequenciesL(), GetNewsAnnouncement(), GetRadioText(), GetRadioTextLength(), GetRdsCapabilities(), GetRdsData(), GetRdsTime(), GetRegionalLink(), GetTrafficAnnouncement(), IsRdsSignal(), NewL(), NotifyAlternativeFrequencies(), NotifyAnnouncement(), NotifyEonInfo(), NotifyRadioText(), NotifyRdsDataChange(), NotifyRdsSignalChange(), NotifyRdsStateChange(), ReceiveRdsFrames(), SetAlternativeFrequency(), SetAnnouncementVolume(), SetAnnouncementVolumeOffset(), SetNewsAnnouncement(), SetRegionalLink(), SetTrafficAnnouncement(), StationSearchByProgrammeIdentifier(), StationSearchByProgrammeType(), StationSearchByRds(), StationSearchByTrafficProgramme(), StopAnnouncement(), TAnnouncementType, TuneToEonStation(), ~CMMRdsTunerUtility()

Inherited from CBase:
Delete(), Extension_(), operator new()

static IMPORT_C CMMRdsTunerUtility *NewL(CMMTunerUtility &aTuner, MMMTunerObserver &aObserver);

Description

Factory function to create a new instance of the RDS Tuner API

Parameters

CMMTunerUtility &aTuner A RDS capable tuner object (check using CMMTunerUtility::GetCapabilities()) MMMTunerObserver &aObserver The observer of the tuner to receive asynchronous completion messages.

Return value

CMMRdsTunerUtility * A pointer and ownership of a fully constructed CMMRdsTunerUtility object

Leave codes

KErrNoMemory Out of memory KErrNotFound CMMRdsTunerUtility object is not present KErrNotSupported RDS is not supported by the tuner

virtual IMPORT_C ~CMMRdsTunerUtility();

Description

Final stage deconstruction of a CMMRdsTunerUtility object

IMPORT_C TInt GetRdsCapabilities(TRdsCapabilities &aCaps) const;

Description

Get the RDS capabilities of the device

Parameters

TRdsCapabilities &aCaps The capabilities object to fill

Return value

TInt A standard system error code

IMPORT_C TInt IsRdsSignal(TBool &aRds);

Description

Returns the status of the RDS reception.

Parameters

TBool &aRds On return, will be ETrue if and only if a RDS signal is currently being received.

Return value

TInt A standard system error code

IMPORT_C void StationSearchByRds(TFrequency aStartFrequency, CMMTunerUtility::TTunerBand aBand, CMMTunerUtility::TSearchDirection aSearchDirection, TBool aCircularSeek=ETrue);

Description

Find a radio station which contains RDS data starting at the start frequency and searching in the direction specified (i.e. Up or down).

Note: this function is subject to the same access control scheme as the Tune methods of CMMTunerUtility

Parameters

TFrequency aStartFrequency The frequency to start searching from, or 0 to start at the beginning of the stated band. CMMTunerUtility::TTunerBand aBand The frequency band to search. This must be a FM band. CMMTunerUtility::TSearchDirection aSearchDirection The direction to search in TBool aCircularSeek If set to ETrue the station seek will loop back to the other end of the band once the end of the band has been reached. (Defaults to ETrue) If not set reaching the end of the band without finding a station will result in a callback to MToTuneComplete with error KErrNotFound.

IMPORT_C void StationSearchByProgrammeType(TRdsProgrammeType aProgType, TFrequency aStartFrequency, CMMTunerUtility::TTunerBand aBand, CMMTunerUtility::TSearchDirection aSearchDirection, TBool aCircularSeek=ETrue);

Description

Find a radio station, of the specified programme type starting at the start frequency and searching in the direction specified (i.e. Up or down).

Note: this function is subject to the same access control scheme as the Tune methods of CMMTunerUtility

Parameters

TRdsProgrammeType aProgType The type of programme to search for TFrequency aStartFrequency The frequency to start searching from, or 0 to start at the beginning of the stated band. CMMTunerUtility::TTunerBand aBand The frequency band to search. This must be a FM band. CMMTunerUtility::TSearchDirection aSearchDirection The direction to search in TBool aCircularSeek If set to ETrue the station seek will loop back to the other end of the band once the end of the band has been reached. (Defaults to ETrue) If not set reaching the end of the band without finding a station will result in a callback to MToTuneComplete with error KErrNotFound.

IMPORT_C void StationSearchByProgrammeIdentifier(TRdsProgrammeIdentifier aPi, TFrequency aStartFrequency, CMMTunerUtility::TTunerBand aBand, CMMTunerUtility::TSearchDirection aSearchDirection, TBool aCircularSeek=ETrue);

Description

Find a radio station, with the specified programme identifier starting at the start frequency and searching in the direction specified (i.e. Up or down).

Note: this function is subject to the same access control scheme as the Tune methods of CMMTunerUtility

Parameters

TRdsProgrammeIdentifier aPi The programme identifier of the station to search for TFrequency aStartFrequency The frequency to start searching from, or 0 to start at the beginning of the stated band. CMMTunerUtility::TTunerBand aBand The frequency band to search. This must be a FM band. CMMTunerUtility::TSearchDirection aSearchDirection The direction to search in TBool aCircularSeek If set to ETrue the station seek will loop back to the other end of the band once the end of the band has been reached. (Defaults to ETrue) If not set reaching the end of the band without finding a station will result in a callback to MToTuneComplete with error KErrNotFound.

IMPORT_C void StationSearchByTrafficProgramme(TBool aTp, TFrequency aStartFrequency, CMMTunerUtility::TTunerBand aBand, CMMTunerUtility::TSearchDirection aSearchDirection, TBool aCircularSeek=ETrue);

Description

Find a radio station, with the specified traffic programme flag value starting at the start frequency and searching in the direction specified (i.e. Up or down).

Note: this function is subject to the same access control scheme as the Tune methods of CMMTunerUtility

Parameters

TBool aTp The TP flag value of a station to search for TFrequency aStartFrequency The frequency to start searching from, or 0 to start at the beginning of the stated band. CMMTunerUtility::TTunerBand aBand The frequency band to search. This must be a FM band. CMMTunerUtility::TSearchDirection aSearchDirection The direction to search in TBool aCircularSeek If set to ETrue the station seek will loop back to the other end of the band once the end of the band has been reached. (Defaults to ETrue) If not set reaching the end of the band without finding a station will result in a callback to MToTuneComplete with error KErrNotFound.

IMPORT_C void CancelRdsSearch();

Description

Cancels an ongoing RDS search as initiated by one of the functions StationSearchByRds, StationSearchByProgrammeType, StationSearchByProgrammeIdentifier or StationSearchByTrafficProgramme. The asynchronous callback will not occur if this is called.

Has not affect if no RDS search operation is ongoing.

IMPORT_C TInt NotifyRdsDataChange(MMMRdsDataObserver &aObserver, TUint32 aWhichData=TRdsData::KAllRdsData);

Description

Requests notifications when all RDS data become invalid due to the tuner being retuned.

Parameters

MMMRdsDataObserver &aObserver The client to be notified. TUint32 aWhichData The subset of data for which change notifications are required.

Return value

TInt A standard system wide error code.

IMPORT_C void CancelNotifyRdsDataChange();

Description

Cancel a NotifyRdsDataChange request.

IMPORT_C TInt GetRdsData(TRdsData &aData, TUint32 &aValid, TUint32 aWhichData=TRdsData::KAllRdsData) const;

Description

Request some RDS data. This will complete immediately with whatever RDS data have already been received.

When this function returns, and data that was requested but is not indicated to be valid can be assumed not to have been received.

Parameters

TRdsData &aData The RDS data will be written to this variable. TUint32 &aValid On return, indicates a subset of RDS data that are valid. TUint32 aWhichData The subset of RDS data that are being requested.

Return value

TInt A standard system wide error code.

static IMPORT_C TLanguage ConvertRdsLanguageId(TRdsLanguageIdentifier aRdsLangId);

Description

Parameters

TRdsLanguageIdentifier aRdsLangId An RDS language identification code

Return value

TLanguage The corresponding TLanguage member, or ELangOther if none exists.

IMPORT_C TInt ConvertRdsLanguageId(TRdsLanguageIdentifier aRdsLangId, TLanguage &aLanguage);

Description

Converts an RDS language identifier into a Symbian TLanguage type. Note that not all languages defined by the RDS specification IEC62106 are present in the TLanguage enumeration; in these cases, a value of ELangOther will be returned.

Parameters

TRdsLanguageIdentifier aRdsLangId An RDS language identification code aLanguage The corresponding TLanguage value, or ELangOther if none exists. TLanguage &aLanguage

Return value

TInt A standard system wide error code.

IMPORT_C TInt GetRadioTextLength(TUint &aLength) const;

Description

Get the length of the available radio text. If no radio text is available this function will return KErrNotFound. The maximum possible length for radio text is 64 characters.

Parameters

TUint &aLength The variable to set to the length of the avaiable radio text

Return value

TInt A standard system error code.

IMPORT_C TInt GetRadioText(TDes &aRadioText) const;

Description

Get the radio text. If no radio text is available, this will return KErrNotFound. In this case, a client can call NotifyRadioText to receive a notification when it is received.

The radio text will have been converted to unicode, eliminating any control characters within it.

Parameters

TDes &aRadioText The descriptor to fill with the radio text

Return value

TInt A standard system error code

IMPORT_C TInt NotifyRadioText(MMMRdsDataObserver &aObserver);

Description

Request notification when the radio text is received or changes.

Parameters

MMMRdsDataObserver &aObserver The client to be notified when the radio text is received or changes.

Return value

TInt A standard system wide error code.

IMPORT_C void CancelNotifyRadioText();

Description

Cancel a NotifyRadioText request.

IMPORT_C TInt NotifyRdsSignalChange(MMMRdsSignalChangeObserver &aRecipient);

Description

Request to receive notification about availability of Rds signal

Parameters

MMMRdsSignalChangeObserver &aRecipient The object to receive the notifications.

Return value

TInt A system wide error code.

IMPORT_C void CancelNotifyRdsSignalChange();

Description

Cancels an outstanding NotifyRdsSignalChange request.

IMPORT_C TInt SetRegionalLink(TBool aRegOn);

Description

Turns regional link function on or off depending on the value of the parameter. A value of ETrue should be passed if you wish to stay tuned to the currently tuned local station regardless of signal quality and signal strength. i.e. don't switch to another local station in the region.

Parameters

TBool aRegOn ETrue to turn regional link on, EFalse to turn it off

Return value

TInt A standard system error code

IMPORT_C TInt GetRegionalLink(TBool &aRegOn) const;

Description

Finds out if the regional link function is currently on or off.

Parameters

TBool &aRegOn This will be set to ETrue on return if and only if the regional link function is currently enabled.

Return value

TInt A standard system error code.

IMPORT_C TInt SetTrafficAnnouncement(TBool aTaOn);

Description

Turn the travel announcement function on or off depending on the value of the parameter. A value of ETrue turns on Traffic Announcements, EFalse turns them off.

If Traffic announcements are disabled while the tuner is retuned to a traffic announcement, the tuner will not revert to the original frequency. To revert to the original frequency, StopAnnouncement() must be called before the traffic announcement feature is disabled.

Parameters

TBool aTaOn ETrue to turn TA on, EFalse to turn it off

Return value

TInt A standard system error code

IMPORT_C TInt GetTrafficAnnouncement(TBool &aTaOn) const;

Description

Finds out if the traffic announcement function is currently enabled or not.

Parameters

TBool &aTaOn This is set to ETrue on return if and only if the traffic announcement function is currenly enabled.

Return value

TInt A standard error code.

IMPORT_C TInt SetAnnouncementVolume(TInt aVolume);

Description

Set the absolute volume to apply during a traffic or news announcement.

Parameters

TInt aVolume The volume to use. Must be between 0 and MaxVolume.

Return value

TInt A standard system error code.

IMPORT_C TInt GetAnnouncementVolume(TInt &aVolume) const;

Description

Find the current absolute volume level used for news of traffic annoucements.

Parameters

TInt &aVolume This will be set to the current volume used for annoucements.

Return value

TInt A standard system error code, KErrNotFound if a annoucement volume offset has been set. use.

IMPORT_C TInt SetAnnouncementVolumeOffset(TInt aVolumeOffset);

Description

Set the offset to the system volume level to apply during a traffic or news announcement

Parameters

TInt aVolumeOffset The offset to the volume level to set for announcements. Must be between -MaxVolume and MaxVolume inclusive. the actual volume with the offset applied will be clipped between 0 and MaxVolume if the offset would otherwise result in a volume outside this range.

Return value

TInt A standard system error code

IMPORT_C TInt GetAnnouncementVolumeOffset(TInt &aVolumeOffset) const;

Description

Find the current offset of the system volume that applies during traffic and news announcements.

Parameters

TInt &aVolumeOffset This will be set to the current traffic and news announcement offset on return.

Return value

TInt A standard system error code, KErrNotFound if an absolute annoucement volume has been set.

IMPORT_C TInt SetNewsAnnouncement(TBool aNaOn);

Description

Turn the news announcement function on or off depending on the value of the parameter. The news announcement function when enabled causes the radio to retune to a station when that station is broadcasting a news report. When the news announcement is finished the radio will tune back to the original station. A value of ETrue turns on News Announcements, EFalse turns them off.

If News announcements are disabled while the tuner is retuned to a news announcement, the tuner will not revert to the original frequency. To revert to the original frequency, StopAnnouncement() must be called before the news announcement feature is disabled.

Parameters

TBool aNaOn ETrue to turn NA on, EFalse to turn it off

Return value

TInt A standard system error code

IMPORT_C TInt GetNewsAnnouncement(TBool &aNaOn) const;

Description

Finds out whether the news announcement function is on or off.

Parameters

TBool &aNaOn This will be set to ETrue if and only if the new announcement function is currently on.

Return value

TInt A standard system error code.

IMPORT_C TInt StopAnnouncement();

Description

Cancels any current announcement, reverting to the original frequency. The announcement feature will remain enabled. If no announcement is currently happening, this function has no affect. This can be used for both News and Traffic announcements.

Return value

TInt A standard system error code. KErrNone if an announcement was successfully stopped, or KErrNotReady if no announcement is currently happening.

IMPORT_C TInt SetAlternativeFrequency(TBool aAfOn);

Description

Turns alternative frequency function on or off depending on the value of the parameter. Sets the automatic switching of the transmitter in the case of a stronger transmitter with the same PI presence. Based on AF and/or EON fields. A value of ETrue should be passed if you wish to enable automatic retuning to the current station on an alternative frequency.

Parameters

TBool aAfOn ETrue to turn alternative frequency on, EFalse to turn it off

Return value

TInt A standard system error code

IMPORT_C TInt GetAlternativeFrequency(TBool &aAfOn) const;

Description

Finds out whether the alternative frequency function is on or off i.e. gets the mode of the automatic switching of the transmitter in case of a stronger transmitter with the same PI presence.

Parameters

TBool &aAfOn This will be set to ETrue if and only if the alternative frequency function is currently on.

Return value

TInt A standard system error code.

IMPORT_C TInt NotifyRdsStateChange(MMMRdsStateChangeObserver &aObserver);

Description

Requests a notification when RDS functionality is enabled or disabled, or when the traffic announcement volume offset is changed.

Parameters

MMMRdsStateChangeObserver &aObserver The class which is to be notified of the changes.

Return value

TInt A standard system error code.

IMPORT_C void CancelNotifyRdsStateChange();

Description

Cancels an outstanding RDS state change notification request.

IMPORT_C void GetRdsTime(TPckg< TDateTime > &aTimeAndDate, TRequestStatus &aStatus) const;

Description

Get the current RDS time. This is an asynchronous function due to the latency of the RDS information becoming available. This information is broadcast at the start of every minute, and is not cached for obvious reasons. Thus, whenever a request is made, it will complete next time the Data and Time are broadcast. The RDS standard states that this is broadcast within 0.1s of the start of a minute, and is accurate to one minute. The latency of the notification reaching the application cannot be guarteed.

Parameters

TPckg< TDateTime > &aTimeAndDate The variable to set to the current RDS time and date TRequestStatus &aStatus A TRequestStatus. This will be signalled when the request completes and will contain the result of the request, this will be one of the system error codes.

IMPORT_C void CancelGetRdsTime();

Description

Cancel the GetRdsTime request

IMPORT_C TInt NotifyAnnouncement(MMMRdsAnnouncementObserver &aObserver);

Description

Request notification when a retune caused by an announcement occurs. This will be a traffic or news announcement. A notification will be provided both at the start of the announcement and at the end.

Parameters

MMMRdsAnnouncementObserver &aObserver The object wishing to receive announcement events

Return value

TInt A standard system error code

IMPORT_C void CancelNotifyAnnouncement();

Description

Cancel the NotifyAnnouncement request

IMPORT_C void GetEonInfoL(RArray< TEonStation > &aEonInfo) const;

Description

Returns a list containing information about other networks broadcast with the currently tuned programmme. This call will return immediately with whatever EON information is currently available. Note that is is possible for this function to return no EON stations when several are being broadcast simply because not enough RDS frames have been received yet. An interested application should make a call to NotifyEonInfo to receive notifications when EON information is received or changes.

Parameters

RArray< TEonStation > &aEonInfo An array to which the EON information will be appended.

IMPORT_C void GetEonFrequenciesL(const TEonStation &aEonStation, RArray< TFrequency > &aFrequencies) const;

Description

Gets the frequencies assoicated with an EON station. This will complete immediately with whatever frequencies are currently cached. An interested application should make a call to NotifyEonChange to receive notifications when more frequencies are received.

Parameters

const TEonStation &aEonStation the EON station to get the frequencies for RArray< TFrequency > &aFrequencies an array to which the frequencies associated with the given station will be appended.

IMPORT_C void GetEonMappedFrequenciesL(const TEonStation &aEonStation, RArray< TEonMappedFrequency > &aMappedFrequencies) const;

Description

Gets the mapped frequencies associated with an EON station. This will complete immediately with whatever mapped frequencies are currently cached. An interested application should make a call to NotifyEonChange to receive notifications when more frequencies are received.

Parameters

const TEonStation &aEonStation the EON station to get the mapped frequencies for RArray< TEonMappedFrequency > &aMappedFrequencies an array to which the mapped frequencies associated with the given station will be appended.

IMPORT_C TInt NotifyEonInfo(MMMRdsEonObserver &aObserver);

Description

Request notification when the Enhanced Other Networks (EON) information changes.

Parameters

MMMRdsEonObserver &aObserver The client to be notifier when EON information changes or an error occurs.

Return value

TInt A standard error code

IMPORT_C void CancelNotifyEonInfo();

Description

Cancels a NotifyEonInfo request.

IMPORT_C void TuneToEonStation(const TEonStation &aEonStation);

Description

Tunes to a station represented by a TEonStation. This will result to a callback to MtoTuneComplete.

Parameters

const TEonStation &aEonStation The EON station that is to be tuned to.

IMPORT_C void GetAlternativeFrequencyListL(RArray< TAlternativeFrequency > &aAfArray);

Description

Returns an array containing the current alternative frequencies list, if any. This will return immediately containing whatever AF information has already been received. If a client wishes to be notified when this information changes, a call to NotifyAlternativeFrequencies should be made.

Parameters

RArray< TAlternativeFrequency > &aAfArray An array to which the list of alternative frequencies are to be appended

Leave codes

A system wide error code.

IMPORT_C TInt NotifyAlternativeFrequencies(MMMRdsAlternativeFrequenciesObserver *aObserver);

Description

Requests notifications when the list of alternative frequencies is received or changes.

Parameters

MMMRdsAlternativeFrequenciesObserver *aObserver The client to which notification should be sent.

Return value

TInt TInt A system wide error code.

IMPORT_C void CancelNotifyAlternativeFrequencies();

Description

Cancels a NotifyAlternativeFrequencies request.

IMPORT_C TInt ReceiveRdsFrames(TUint32 aWhichGroups, MMMRdsFrameReceiver &aRecipient);

Description

Request to receive raw RDS frames. If the request is successful, the recipient will be called back whenever an RDS frame of one of the requested types is received.

Parameters

TUint32 aWhichGroups The set of frame types that the recipient wished to receive. This value should contain values from enumeration TRdsFrameGroup ored together to indicate which frames the recipient is interested in. MMMRdsFrameReceiver &aRecipient The object to receive the RDS frames.

Return value

TInt A system wide error code.

IMPORT_C void CancelReceiveRdsFrames();

Description

Cancels an outstanding ReceiveRdsFrames request.

IMPORT_C TInt CustomCommandSync(TInt aFunction, const TIpcArgs &aArgs);

Description

Send a synchronous custom command to the RDS tuner.

Parameters

TInt aFunction The function number to indicate which function is to be called on the interface defined by the first IPC argument const TIpcArgs &aArgs The IPC arguments to send to the RDS tuner. The first of these arguments must be the UID of the interface within the tuner to which the command is destined, represented as an integer. Failure to set the first argument properly will result in the command completing with KErrNotSupported at best, but possibly the client being panicked.

Return value

TInt A standard system error code

IMPORT_C void CustomCommandAsync(TInt aFunction, const TIpcArgs &aArgs, TRequestStatus &aStatus);

Description

Send an asynchronous custom command to the RDS tuner.

Parameters

TInt aFunction The function number to indicate which function is to be called on the interface defined by the first IPC argument const TIpcArgs &aArgs The IPC arguments to send to the RDS tuner. The first of these arguments must be the UID of the interface within the tuner to which the command is destined, represented as an integer. Failure to set the first argument properly will result in the command completing with KErrNotSupported at best, but possibly the client being panicked. TRequestStatus &aStatus The TRequestStatus of an active object. This will contain the result of the request on completion. The exact range of result values is dependent on the interface.

TAnnouncementType

Description

RDS Announcement Type

ERdsTrafficAnnouncement Traffic announcement ERdsNewsAnnouncement News announcement