ITuner.hal revision a02b6ef23c6dd0405ceb1337ba05bf4e0087890c
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 tune_1_1(ProgramSelector program) generates (Result result); 43 44 /** 45 * Retrieve current station information. 46 * @return result OK if scan successfully started 47 * NOT_INITIALIZED if another error occurs 48 * @return info Current program information. 49 */ 50 getProgramInformation_1_1() generates (Result result, ProgramInfo info); 51 52 /** 53 * Initiates a background scan to update internally cached program list. 54 * 55 * HAL client may not need to initiate the scan explicitly with this call, 56 * ie. HAL implementation MAY perform the scan on boot. It's a common 57 * practice in devices with two physical tuners with background scanning. 58 * 59 * Device must call backgroundScanComplete if the result is OK, even if the 60 * scan fails later (it must pass proper result through the callback). 61 * Otherwise, backgroundScanComplete must not be called as a result of this 62 * certain attempt. It may still be called as a response to another call to 63 * startBackgroundScan, former or latter. 64 * 65 * Device may utilize an already running (but not finished) scan for 66 * subsequent calls to startBackgroundScan, issuing a single 67 * backgroundScanComplete callback. 68 * 69 * @return result OK if the scan was properly scheduled (this does not mean 70 * it successfully finished). 71 * UNAVAILABLE if the background scan is unavailable, 72 * ie. temporarily due to ongoing foreground 73 * playback in single-tuner device. 74 * NOT_INITIALIZED other error, ie. HW failure. 75 */ 76 startBackgroundScan() generates (ProgramListResult result); 77 78 /** 79 * Retrieve station list. 80 * 81 * This call does not trigger actual scan, but operates on the list cached 82 * internally at the driver level. 83 * 84 * @param filter vendor-specific filter for the stations to be retrieved. 85 * An empty string MUST result in full list. 86 * Client application MUST verify vendor/product name 87 * before setting this parameter to anything else. 88 * @return result OK if the list was successfully retrieved. 89 * INVALID_ARGUMENTS if invalid arguments are passed 90 * NOT_READY if the scan is in progress. 91 * NOT_STARTED if the scan has not been started, client may 92 * call startBackgroundScan to fix this. 93 * NOT_INITIALIZED if any other error occurs. 94 * @return programList List of stations available for user. 95 */ 96 getProgramList(string filter) 97 generates (ProgramListResult result, vec<ProgramInfo> programList); 98 99 /** 100 * Checks, if the analog playback is forced, see setAnalogForced. 101 * 102 * The isForced value is only valid if result was OK. 103 * 104 * @return result OK if the call succeeded and isForced is valid. 105 * INVALID_STATE if the switch is not supported at current 106 * configuration. 107 * NOT_INITIALIZED if any other error occurs. 108 * @return isForced true if analog is forced, false otherwise. 109 */ 110 isAnalogForced() generates (Result result, bool isForced); 111 112 /** 113 * Forces the analog playback for the supporting radio technology. 114 * 115 * User may disable digital playback for FM HD Radio or hybrid FM/DAB with 116 * this option. This is purely user choice, ie. does not reflect digital- 117 * analog handover managed from the HAL implementation side. 118 * 119 * Some radio technologies may not support this, ie. DAB. 120 * 121 * @param isForced true to force analog, false for a default behaviour. 122 * @return result OK if the setting was successfully done. 123 * INVALID_STATE if the switch is not supported at current 124 * configuration. 125 * NOT_INITIALIZED if any other error occurs. 126 */ 127 setAnalogForced(bool isForced) generates (Result result); 128}; 129