1/* 2 * Copyright (C) 2017 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.hardware.broadcastradio@1.1; 18 19import @1.0::ITuner; 20 21interface ITuner extends @1.0::ITuner { 22 23 /** 24 * Tune to a specified program. 25 * 26 * For AM/FM, it must be called when a valid configuration has been applied. 27 * Automatically cancels pending scan, step or tune. 28 * 29 * If method returns OK, ITunerCallback.tuneComplete_1_1() MUST be called: 30 * - once successfully tuned; 31 * - after a time out; 32 * - after a full band scan, if no station found. 33 * 34 * The tuned field of ProgramInfo should indicate if tuned to a valid 35 * station or not. 36 * 37 * @param program Program to tune to. 38 * @return result OK if successfully started tunning. 39 * INVALID_ARGUMENTS if invalid arguments are passed. 40 * NOT_INITIALIZED if another error occurs. 41 */ 42 tuneByProgramSelector(ProgramSelector program) generates (Result result); 43 44 /** 45 * Cancels announcement. 46 * 47 * If it was traffic announcement, trafficAnnouncement(false) callback 48 * should be called (just like it was ended in a normal way). Similarly for 49 * emergency announcement. If there was no announcement, then no action 50 * should be taken. 51 * 52 * There is a race condition between calling cancelAnnouncement and the 53 * actual announcement being finished, so trafficAnnouncement / 54 * emergencyAnnouncement callback should be tracked with proper locking. 55 * 56 * @return result OK if successfully cancelled announcement or there was 57 * no announcement. 58 * NOT_INITIALIZED if another error occurs. 59 */ 60 cancelAnnouncement() generates (Result result); 61 62 /** 63 * Retrieve current station information. 64 * @return result OK if scan successfully started 65 * NOT_INITIALIZED if another error occurs 66 * @return info Current program information. 67 */ 68 getProgramInformation_1_1() generates (Result result, ProgramInfo info); 69 70 /** 71 * Initiates a background scan to update internally cached program list. 72 * 73 * HAL client may not need to initiate the scan explicitly with this call, 74 * ie. HAL implementation MAY perform the scan on boot. It's a common 75 * practice in devices with two physical tuners with background scanning. 76 * 77 * Device must call backgroundScanComplete if the result is OK, even if the 78 * scan fails later (it must pass proper result through the callback). 79 * Otherwise, backgroundScanComplete must not be called as a result of this 80 * certain attempt. It may still be called as a response to another call to 81 * startBackgroundScan, former or latter. 82 * 83 * Device may utilize an already running (but not finished) scan for 84 * subsequent calls to startBackgroundScan, issuing a single 85 * backgroundScanComplete callback. 86 * 87 * If a device supports continuous background scanning, it may succeed 88 * (return OK and call backgroundScanComplete) without any additional 89 * operation performed. 90 * 91 * Foreground scanning may be implemented in the front end app with 92 * @1.0::ITuner scan operation. 93 * 94 * @return result OK if the scan was properly scheduled (this does not mean 95 * it successfully finished). 96 * UNAVAILABLE if the background scan is unavailable, 97 * ie. temporarily due to ongoing foreground 98 * playback in single-tuner device. 99 * NOT_INITIALIZED other error, ie. HW failure. 100 */ 101 startBackgroundScan() generates (ProgramListResult result); 102 103 /** 104 * Retrieve station list. 105 * 106 * This call does not trigger actual scan, but operates on the list cached 107 * internally at the driver level. 108 * 109 * @param vendorFilter vendor-specific filter for the stations to be retrieved. 110 * An empty vector MUST result in full list for a given tuner. 111 * @return result OK if the list was successfully retrieved. 112 * INVALID_ARGUMENTS if invalid arguments are passed 113 * NOT_READY if the scan is in progress. 114 * NOT_STARTED if the scan has not been started, client may 115 * call startBackgroundScan to fix this. 116 * NOT_INITIALIZED if any other error occurs. 117 * @return programList List of stations available for user. 118 */ 119 getProgramList(vec<VendorKeyValue> vendorFilter) 120 generates (ProgramListResult result, vec<ProgramInfo> programList); 121 122 /** 123 * Forces the analog playback for the supporting radio technology. 124 * 125 * User may disable digital playback for FM HD Radio or hybrid FM/DAB with 126 * this option. This is purely user choice, ie. does not reflect digital- 127 * analog handover managed from the HAL implementation side. 128 * 129 * Some radio technologies may not support this, ie. DAB. 130 * 131 * @param isForced true to force analog, false for a default behaviour. 132 * @return result OK if the setting was successfully done. 133 * INVALID_STATE if the switch is not supported at current 134 * configuration. 135 * NOT_INITIALIZED if any other error occurs. 136 */ 137 setAnalogForced(bool isForced) generates (Result result); 138 139 /** 140 * Checks, if the analog playback is forced, see setAnalogForced. 141 * 142 * The isForced value is only valid if result was OK. 143 * 144 * @return result OK if the call succeeded and isForced is valid. 145 * INVALID_STATE if the switch is not supported at current 146 * configuration. 147 * NOT_INITIALIZED if any other error occurs. 148 * @return isForced true if analog is forced, false otherwise. 149 */ 150 isAnalogForced() generates (Result result, bool isForced); 151}; 152