1 /* Copyright (C) 2017 The Android Open Source Project 2 * 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 package android.hardware.broadcastradio@2.0; 17 18 interface ITunerSession { 19 /** 20 * Tune to a specified program. 21 * 22 * Automatically cancels pending tune(), scan() or step(). 23 * If the method returns OK, tuneFailed or currentProgramInfoChanged 24 * callback must be called. 25 * 26 * @param program Program to tune to. 27 * @return result OK if successfully started tuning. 28 * NOT_SUPPORTED if the program selector doesn't contain any 29 * supported identifier. 30 * INVALID_ARGUMENTS if the program selector contains 31 * identifiers in invalid format (i.e. out of range). 32 */ 33 tune(ProgramSelector program) generates (Result result); 34 35 /** 36 * Tune (seek) to the next valid program on the "air". 37 * 38 * This might more naturally be called "seek" but for legacy reasons, the 39 * entry point remains "scan". This should not be confused with the actual 40 * scan operation (where the radio seeks through programs in a loop until 41 * user chooses to stay on one of them) nor background scan operation (that 42 * a tuner may do in order to locate all available programs. This function 43 * is meant to advance to the next detected program and stay there. 44 * 45 * Automatically cancels pending tune(), scan() or step(). 46 * If the method returns OK, tuneFailed or currentProgramInfoChanged 47 * callback must be called. 48 * 49 * The skipSubChannel parameter is used to skip digital radio subchannels: 50 * - HD Radio SPS; 51 * - DAB secondary service. 52 * 53 * As an implementation detail, the HAL has the option to perform an actual 54 * seek or select the next program from the list retrieved in the 55 * background, if one is not stale. 56 * 57 * @param directionUp True to change towards higher numeric values 58 * (frequency, channel number), false towards lower. 59 * @param skipSubChannel Don't tune to subchannels. 60 * @return result OK if the operation has successfully started. 61 */ 62 scan(bool directionUp, bool skipSubChannel) generates (Result result); 63 64 /** 65 * Tune to the adjacent channel, which may not be occupied by any program. 66 * 67 * Automatically cancels pending tune(), scan() or step(). 68 * If the method returns OK, tuneFailed or currentProgramInfoChanged 69 * callback must be called. 70 * 71 * @param directionUp True to change towards higher numeric values 72 * (frequency, channel number), false towards lower. 73 * @return result OK successfully started tuning. 74 * NOT_SUPPORTED if tuning to an unoccupied channel is not 75 * supported (i.e. for satellite radio). 76 */ 77 step(bool directionUp) generates (Result result); 78 79 /** 80 * Cancel a pending tune(), scan() or step(). 81 * 82 * If there is no such operation running, the call must be ignored. 83 */ 84 cancel(); 85 86 /** 87 * Applies a filter to the program list and starts sending program list 88 * updates over onProgramListUpdated callback. 89 * 90 * There may be only one updates stream active at the moment. Calling this 91 * method again must result in cancelling the previous update request. 92 * 93 * This call clears the program list on the client side, the HAL must send 94 * the whole list again. 95 * 96 * If the program list scanning hardware (i.e. background tuner) is 97 * unavailable at the moment, the call must succeed and start updates 98 * when it becomes available. 99 * 100 * @param filter Filter to apply on the fetched program list. 101 * @return result OK successfully started fetching list updates. 102 * NOT_SUPPORTED program list scanning is not supported 103 * by the hardware. 104 */ 105 startProgramListUpdates(ProgramFilter filter) generates (Result result); 106 107 /** 108 * Stops sending program list updates. 109 */ 110 stopProgramListUpdates(); 111 112 /** 113 * Fetches the current setting of a given config flag. 114 * 115 * The success/failure result must be consistent with setConfigFlag. 116 * 117 * @param flag Flag to fetch. 118 * @return result OK successfully fetched the flag. 119 * INVALID_STATE if the flag is not applicable right now. 120 * NOT_SUPPORTED if the flag is not supported at all. 121 * @return value The current value of the flag, if result is OK. 122 */ 123 isConfigFlagSet(ConfigFlag flag) generates (Result result, bool value); 124 125 /** 126 * Sets the config flag. 127 * 128 * The success/failure result must be consistent with isConfigFlagSet. 129 * 130 * @param flag Flag to set. 131 * @param value The new value of a given flag. 132 * @return result OK successfully set the flag. 133 * INVALID_STATE if the flag is not applicable right now. 134 * NOT_SUPPORTED if the flag is not supported at all. 135 */ 136 setConfigFlag(ConfigFlag flag, bool value) generates (Result result); 137 138 /** 139 * Generic method for setting vendor-specific parameter values. 140 * The framework does not interpret the parameters, they are passed 141 * in an opaque manner between a vendor application and HAL. 142 * 143 * Framework does not make any assumptions on the keys or values, other than 144 * ones stated in VendorKeyValue documentation (a requirement of key 145 * prefixes). 146 * 147 * For each pair in the result vector, the key must be one of the keys 148 * contained in the input (possibly with wildcards expanded), and the value 149 * must be a vendor-specific result status (i.e. the string "OK" or an error 150 * code). The implementation may choose to return an empty vector, or only 151 * return a status for a subset of the provided inputs, at its discretion. 152 * 153 * Application and HAL must not use keys with unknown prefix. In particular, 154 * it must not place a key-value pair in results vector for unknown key from 155 * parameters vector - instead, an unknown key should simply be ignored. 156 * In other words, results vector may contain a subset of parameter keys 157 * (however, the framework doesn't enforce a strict subset - the only 158 * formal requirement is vendor domain prefix for keys). 159 * 160 * @param parameters Vendor-specific key-value pairs. 161 * @return results Operation completion status for parameters being set. 162 */ 163 setParameters(vec<VendorKeyValue> parameters) 164 generates (vec<VendorKeyValue> results); 165 166 /** 167 * Generic method for retrieving vendor-specific parameter values. 168 * The framework does not interpret the parameters, they are passed 169 * in an opaque manner between a vendor application and HAL. 170 * 171 * Framework does not cache set/get requests, so it's allowed for 172 * getParameter to return a different value than previous setParameter call. 173 * 174 * The syntax and semantics of keys are up to the vendor (as long as prefix 175 * rules are obeyed). For instance, vendors may include some form of 176 * wildcard support. In such case, result vector may be of different size 177 * than requested keys vector. However, wildcards are not recognized by 178 * framework and they are passed as-is to the HAL implementation. 179 * 180 * Unknown keys must be ignored and not placed into results vector. 181 * 182 * @param keys Parameter keys to fetch. 183 * @return parameters Vendor-specific key-value pairs. 184 */ 185 getParameters(vec<string> keys) generates (vec<VendorKeyValue> parameters); 186 187 /** 188 * Closes the session. 189 * 190 * The call must not fail and must only be issued once. 191 * 192 * After the close call is executed, no other calls to this interface 193 * are allowed. 194 */ 195 close(); 196 }; 197
