Package: android.hardware.broadcastradio@1.1

ITuner

interface ITuner extends @1.0::ITuner

Methods

tuneByProgramSelector

tuneByProgramSelector (ProgramSelector program)
generates (Result result)

Tune to a specified program.

For AM/FM, it must be called when a valid configuration has been applied.Automatically cancels pending scan, step or tune.

If method returns OK, ITunerCallback.tuneComplete_1_1() MUST be called:- once successfully tuned;- after a time out;- after a full band scan, if no station found.

The tuned field of ProgramInfo should indicate if tuned to a valid station or not.

Details
Parameters
program
Program to tune to.
Generates
result
OK if successfully started tunning.INVALID_ARGUMENTS if invalid arguments are passed.NOT_INITIALIZED if another error occurs.

cancelAnnouncement

cancelAnnouncement ()
generates (Result result)

Cancels announcement.

If it was traffic announcement, trafficAnnouncement(false)callback should be called(just like it was ended in a normal way). Similarly for emergency announcement.If there was no announcement, then no action should be taken.

There is a race condition between calling cancelAnnouncement and the actual announcement being finished, so trafficAnnouncement / emergencyAnnouncement callback should be tracked with proper locking.

Details
Generates
result
OK if successfully cancelled announcement or there was no announcement.NOT_INITIALIZED if another error occurs.

getProgramInformation_1_1

getProgramInformation_1_1 ()
generates (Result result, ProgramInfo info)

Retrieve current station information.

Details
Generates
result
OK if scan successfully started NOT_INITIALIZED if another error occurs
info
Current program information.

startBackgroundScan

startBackgroundScan ()
generates (ProgramListResult result)

Initiates a background scan to update internally cached program list.

HAL client may not need to initiate the scan explicitly with this call, ie.HAL implementation MAY perform the scan on boot.It's a common practice in devices with two physical tuners with background scanning.

Device must call backgroundScanComplete if the result is OK, even if the scan fails later(it must pass proper result through the callback). Otherwise, backgroundScanComplete must not be called as a result of this certain attempt.It may still be called as a response to another call to startBackgroundScan, former or latter.

Device may utilize an already running(but not finished)scan for subsequent calls to startBackgroundScan, issuing a single backgroundScanComplete callback.

If a device supports continuous background scanning, it may succeed(return OK and call backgroundScanComplete)without any additional operation performed.

Foreground scanning may be implemented in the front end app with@1.0::ITuner scan operation.

Details
Generates
result
OK if the scan was properly scheduled(this does not mean it successfully finished). UNAVAILABLE if the background scan is unavailable, ie.temporarily due to ongoing foreground playback in single-tuner device.NOT_INITIALIZED other error, ie.HW failure.

getProgramList

getProgramList (vec<VendorKeyValue> vendorFilter)
generates (ProgramListResult result, vec<ProgramInfo> programList)

Retrieve station list.

This call does not trigger actual scan, but operates on the list cached internally at the driver level.

Details
Parameters
vendorFilter
vendor-specific filter for the stations to be retrieved.An empty vector MUST result in full list for a given tuner.
Generates
result
OK if the list was successfully retrieved.INVALID_ARGUMENTS if invalid arguments are passed NOT_READY if the scan is in progress.NOT_STARTED if the scan has not been started, client may call startBackgroundScan to fix this.NOT_INITIALIZED if any other error occurs.
programList
List of stations available for user.

setAnalogForced

setAnalogForced (bool isForced)
generates (Result result)

Forces the analog playback for the supporting radio technology.

User may disable digital playback for FM HD Radio or hybrid FM/DAB with this option.This is purely user choice, ie.does not reflect digital- analog handover managed from the HAL implementation side.

Some radio technologies may not support this, ie.DAB.

Details
Parameters
isForced
true to force analog, false for a default behaviour.
Generates
result
OK if the setting was successfully done.INVALID_STATE if the switch is not supported at current configuration.NOT_INITIALIZED if any other error occurs.

isAnalogForced

isAnalogForced ()
generates (Result result, bool isForced)

Checks, if the analog playback is forced, see setAnalogForced.

The isForced value is only valid if result was OK.

Details
Generates
result
OK if the call succeeded and isForced is valid.INVALID_STATE if the switch is not supported at current configuration.NOT_INITIALIZED if any other error occurs.
isForced
true if analog is forced, false otherwise.