Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 1 | /* |
| 2 | * Copyright (C) 2015 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 | |
| 17 | package android.hardware.radio; |
| 18 | |
Tomasz Wasilczyk | d44b2ea | 2017-03-08 10:01:04 -0800 | [diff] [blame] | 19 | import android.annotation.NonNull; |
| 20 | import android.annotation.Nullable; |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 21 | import android.annotation.SystemApi; |
Tomasz Wasilczyk | 4482b14 | 2017-07-17 13:57:12 -0700 | [diff] [blame] | 22 | import android.graphics.Bitmap; |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 23 | import android.os.Handler; |
Tomasz Wasilczyk | c9a1ac7 | 2017-05-17 21:29:28 -0700 | [diff] [blame] | 24 | |
Tomasz Wasilczyk | d44b2ea | 2017-03-08 10:01:04 -0800 | [diff] [blame] | 25 | import java.util.List; |
Tomasz Wasilczyk | 0f1776d | 2017-08-03 11:03:49 -0700 | [diff] [blame] | 26 | import java.util.Map; |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 27 | |
| 28 | /** |
| 29 | * RadioTuner interface provides methods to control a radio tuner on the device: selecting and |
| 30 | * configuring the active band, muting/unmuting, scanning and tuning, etc... |
| 31 | * |
| 32 | * Obtain a RadioTuner interface by calling {@link RadioManager#openTuner(int, |
| 33 | * RadioManager.BandConfig, boolean, RadioTuner.Callback, Handler)}. |
| 34 | * @hide |
| 35 | */ |
| 36 | @SystemApi |
| 37 | public abstract class RadioTuner { |
| 38 | |
| 39 | /** Scanning direction UP for {@link #step(int, boolean)}, {@link #scan(int, boolean)} */ |
| 40 | public static final int DIRECTION_UP = 0; |
| 41 | |
| 42 | /** Scanning directions DOWN for {@link #step(int, boolean)}, {@link #scan(int, boolean)} */ |
| 43 | public static final int DIRECTION_DOWN = 1; |
| 44 | |
| 45 | /** |
| 46 | * Close the tuner interface. The {@link Callback} callback will not be called |
| 47 | * anymore and associated resources will be released. |
| 48 | * Must be called when the tuner is not needed to make hardware resources available to others. |
| 49 | * */ |
| 50 | public abstract void close(); |
| 51 | |
| 52 | /** |
| 53 | * Set the active band configuration for this module. |
| 54 | * Must be a valid configuration obtained via buildConfig() from a valid BandDescriptor listed |
| 55 | * in the ModuleProperties of the module with the specified ID. |
| 56 | * @param config The desired band configuration (FmBandConfig or AmBandConfig). |
| 57 | * @return |
| 58 | * <ul> |
| 59 | * <li>{@link RadioManager#STATUS_OK} in case of success, </li> |
| 60 | * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> |
| 61 | * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> |
| 62 | * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> |
| 63 | * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> |
| 64 | * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native |
| 65 | * service fails, </li> |
| 66 | * </ul> |
| 67 | */ |
| 68 | public abstract int setConfiguration(RadioManager.BandConfig config); |
| 69 | |
| 70 | /** |
| 71 | * Get current configuration. |
| 72 | * @param config a BandConfig array of lengh 1 where the configuration is returned. |
| 73 | * @return |
| 74 | * <ul> |
| 75 | * <li>{@link RadioManager#STATUS_OK} in case of success, </li> |
| 76 | * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> |
| 77 | * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> |
| 78 | * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> |
| 79 | * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> |
| 80 | * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native |
| 81 | * service fails, </li> |
| 82 | * </ul> |
| 83 | */ |
| 84 | public abstract int getConfiguration(RadioManager.BandConfig[] config); |
| 85 | |
| 86 | |
| 87 | /** |
| 88 | * Set mute state. When muted, the radio tuner audio source is not available for playback on |
| 89 | * any audio device. when unmuted, the radio tuner audio source is output as a media source |
| 90 | * and renderd over the audio device selected for media use case. |
| 91 | * The radio tuner audio source is muted by default when the tuner is first attached. |
| 92 | * Only effective if the tuner is attached with audio enabled. |
| 93 | * |
| 94 | * @param mute the requested mute state. |
| 95 | * @return |
| 96 | * <ul> |
| 97 | * <li>{@link RadioManager#STATUS_OK} in case of success, </li> |
| 98 | * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> |
| 99 | * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> |
| 100 | * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> |
| 101 | * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native |
| 102 | * service fails, </li> |
| 103 | * </ul> |
| 104 | */ |
| 105 | public abstract int setMute(boolean mute); |
| 106 | |
| 107 | /** |
| 108 | * Get mute state. |
| 109 | * |
| 110 | * @return {@code true} if the radio tuner audio source is muted or a problem occured |
| 111 | * retrieving the mute state, {@code false} otherwise. |
| 112 | */ |
| 113 | public abstract boolean getMute(); |
| 114 | |
| 115 | /** |
| 116 | * Step up or down by one channel spacing. |
| 117 | * The operation is asynchronous and {@link Callback} |
| 118 | * onProgramInfoChanged() will be called when step completes or |
| 119 | * onError() when cancelled or timeout. |
| 120 | * @param direction {@link #DIRECTION_UP} or {@link #DIRECTION_DOWN}. |
| 121 | * @param skipSubChannel indicates to skip sub channels when the configuration currently |
| 122 | * selected supports sub channel (e.g HD Radio). N/A otherwise. |
| 123 | * @return |
| 124 | * <ul> |
| 125 | * <li>{@link RadioManager#STATUS_OK} in case of success, </li> |
| 126 | * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> |
| 127 | * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> |
| 128 | * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> |
| 129 | * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> |
| 130 | * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native |
| 131 | * service fails, </li> |
| 132 | * </ul> |
| 133 | */ |
| 134 | public abstract int step(int direction, boolean skipSubChannel); |
| 135 | |
| 136 | /** |
| 137 | * Scan up or down to next valid station. |
| 138 | * The operation is asynchronous and {@link Callback} |
| 139 | * onProgramInfoChanged() will be called when scan completes or |
| 140 | * onError() when cancelled or timeout. |
| 141 | * @param direction {@link #DIRECTION_UP} or {@link #DIRECTION_DOWN}. |
| 142 | * @param skipSubChannel indicates to skip sub channels when the configuration currently |
| 143 | * selected supports sub channel (e.g HD Radio). N/A otherwise. |
| 144 | * @return |
| 145 | * <ul> |
| 146 | * <li>{@link RadioManager#STATUS_OK} in case of success, </li> |
| 147 | * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> |
| 148 | * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> |
| 149 | * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> |
| 150 | * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> |
| 151 | * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native |
| 152 | * service fails, </li> |
| 153 | * </ul> |
| 154 | */ |
| 155 | public abstract int scan(int direction, boolean skipSubChannel); |
| 156 | |
| 157 | /** |
| 158 | * Tune to a specific frequency. |
| 159 | * The operation is asynchronous and {@link Callback} |
| 160 | * onProgramInfoChanged() will be called when tune completes or |
| 161 | * onError() when cancelled or timeout. |
| 162 | * @param channel the specific channel or frequency to tune to. |
| 163 | * @param subChannel the specific sub-channel to tune to. N/A if the selected configuration |
| 164 | * does not support cub channels. |
| 165 | * @return |
| 166 | * <ul> |
| 167 | * <li>{@link RadioManager#STATUS_OK} in case of success, </li> |
| 168 | * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> |
| 169 | * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> |
| 170 | * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> |
| 171 | * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> |
| 172 | * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native |
| 173 | * service fails, </li> |
| 174 | * </ul> |
Tomasz Wasilczyk | 8cfb0e8 | 2017-07-12 13:59:20 -0700 | [diff] [blame] | 175 | * @deprecated Use {@link tune(ProgramSelector)} instead. |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 176 | */ |
Tomasz Wasilczyk | 8cfb0e8 | 2017-07-12 13:59:20 -0700 | [diff] [blame] | 177 | @Deprecated |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 178 | public abstract int tune(int channel, int subChannel); |
| 179 | |
| 180 | /** |
Tomasz Wasilczyk | 8cfb0e8 | 2017-07-12 13:59:20 -0700 | [diff] [blame] | 181 | * Tune to a program. |
| 182 | * |
| 183 | * The operation is asynchronous and {@link Callback} onProgramInfoChanged() will be called |
| 184 | * when tune completes or onError() when cancelled or on timeout. |
| 185 | * |
Jeff Sharkey | 67f9d50 | 2017-08-05 13:49:13 -0600 | [diff] [blame] | 186 | * @throws IllegalArgumentException if the provided selector is invalid |
Tomasz Wasilczyk | 8cfb0e8 | 2017-07-12 13:59:20 -0700 | [diff] [blame] | 187 | */ |
| 188 | public abstract void tune(@NonNull ProgramSelector selector); |
| 189 | |
| 190 | /** |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 191 | * Cancel a pending scan or tune operation. |
| 192 | * If an operation is pending, {@link Callback} onError() will be called with |
| 193 | * {@link #ERROR_CANCELLED}. |
| 194 | * @return |
| 195 | * <ul> |
| 196 | * <li>{@link RadioManager#STATUS_OK} in case of success, </li> |
| 197 | * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> |
| 198 | * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> |
| 199 | * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> |
| 200 | * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> |
| 201 | * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native |
| 202 | * service fails, </li> |
| 203 | * </ul> |
| 204 | */ |
| 205 | public abstract int cancel(); |
| 206 | |
| 207 | /** |
Tomasz Wasilczyk | c4cd823 | 2017-07-14 10:46:15 -0700 | [diff] [blame] | 208 | * Cancels traffic or emergency announcement. |
| 209 | * |
| 210 | * If there was no announcement to cancel, no action is taken. |
| 211 | * |
| 212 | * There is a race condition between calling cancelAnnouncement and the actual announcement |
| 213 | * being finished, so onTrafficAnnouncement / onEmergencyAnnouncement callback should be |
| 214 | * tracked with proper locking. |
| 215 | */ |
| 216 | public abstract void cancelAnnouncement(); |
| 217 | |
| 218 | /** |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 219 | * Get current station information. |
| 220 | * @param info a ProgramInfo array of lengh 1 where the information is returned. |
| 221 | * @return |
| 222 | * <ul> |
| 223 | * <li>{@link RadioManager#STATUS_OK} in case of success, </li> |
| 224 | * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> |
| 225 | * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> |
| 226 | * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> |
| 227 | * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> |
| 228 | * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native |
| 229 | * service fails, </li> |
| 230 | * </ul> |
| 231 | */ |
| 232 | public abstract int getProgramInformation(RadioManager.ProgramInfo[] info); |
| 233 | |
| 234 | /** |
Tomasz Wasilczyk | 4482b14 | 2017-07-17 13:57:12 -0700 | [diff] [blame] | 235 | * Retrieves a {@link Bitmap} for the given image ID or null, |
| 236 | * if the image was missing from the tuner. |
| 237 | * |
| 238 | * This involves doing a call to the tuner, so the bitmap should be cached |
| 239 | * on the application side. |
| 240 | * |
| 241 | * If the method returns null for non-zero ID, it means the image was |
| 242 | * updated on the tuner side. There is a race conditon between fetching |
| 243 | * image for an old ID and tuner updating the image (and cleaning up the |
| 244 | * old image). In such case, a new ProgramInfo with updated image id will |
| 245 | * be sent with a {@link onProgramInfoChanged} callback. |
| 246 | * |
| 247 | * @param id The image identifier, retrieved with |
| 248 | * {@link RadioMetadata#getBitmapId(String)}. |
| 249 | * @return A {@link Bitmap} or null. |
| 250 | * @throws IllegalArgumentException if id==0 |
| 251 | * @hide This API is not thoroughly elaborated yet |
| 252 | */ |
| 253 | public abstract @Nullable Bitmap getMetadataImage(int id); |
| 254 | |
| 255 | /** |
Tomasz Wasilczyk | e597ce1 | 2017-03-24 13:50:53 -0700 | [diff] [blame] | 256 | * Initiates a background scan to update internally cached program list. |
| 257 | * |
| 258 | * It may not be necessary to initiate the scan explicitly - the scan MAY be performed on boot. |
| 259 | * |
| 260 | * The operation is asynchronous and {@link Callback} backgroundScanComplete or onError will |
| 261 | * be called if the return value of this call was {@code true}. As result of this call |
| 262 | * programListChanged may be triggered (if the scanned list differs). |
| 263 | * |
| 264 | * @return {@code true} if the scan was properly scheduled, {@code false} if the scan feature |
| 265 | * is unavailable; ie. temporarily due to ongoing foreground playback in single-tuner device |
| 266 | * or permanently if the feature is not supported |
| 267 | * (see ModuleProperties#isBackgroundScanningSupported()). |
Tomasz Wasilczyk | e597ce1 | 2017-03-24 13:50:53 -0700 | [diff] [blame] | 268 | */ |
| 269 | public abstract boolean startBackgroundScan(); |
| 270 | |
| 271 | /** |
Tomasz Wasilczyk | d44b2ea | 2017-03-08 10:01:04 -0800 | [diff] [blame] | 272 | * Get the list of discovered radio stations. |
| 273 | * |
Tomasz Wasilczyk | 0f1776d | 2017-08-03 11:03:49 -0700 | [diff] [blame] | 274 | * To get the full list, set filter to null or empty map. |
| 275 | * Keys must be prefixed with unique vendor Java-style namespace, |
| 276 | * eg. 'com.somecompany.parameter1'. |
Tomasz Wasilczyk | d44b2ea | 2017-03-08 10:01:04 -0800 | [diff] [blame] | 277 | * |
Tomasz Wasilczyk | 0f1776d | 2017-08-03 11:03:49 -0700 | [diff] [blame] | 278 | * @param vendorFilter vendor-specific selector for radio stations. |
Tomasz Wasilczyk | d44b2ea | 2017-03-08 10:01:04 -0800 | [diff] [blame] | 279 | * @return a list of radio stations. |
Tomasz Wasilczyk | e597ce1 | 2017-03-24 13:50:53 -0700 | [diff] [blame] | 280 | * @throws IllegalStateException if the scan is in progress or has not been started, |
| 281 | * startBackgroundScan() call may fix it. |
Tomasz Wasilczyk | 0f1776d | 2017-08-03 11:03:49 -0700 | [diff] [blame] | 282 | * @throws IllegalArgumentException if the vendorFilter argument is not valid. |
Tomasz Wasilczyk | 436128f | 2018-01-08 16:46:09 -0800 | [diff] [blame] | 283 | * @deprecated Use {@link getDynamicProgramList} instead. |
Tomasz Wasilczyk | d44b2ea | 2017-03-08 10:01:04 -0800 | [diff] [blame] | 284 | */ |
Tomasz Wasilczyk | 436128f | 2018-01-08 16:46:09 -0800 | [diff] [blame] | 285 | @Deprecated |
Tomasz Wasilczyk | 0f1776d | 2017-08-03 11:03:49 -0700 | [diff] [blame] | 286 | public abstract @NonNull List<RadioManager.ProgramInfo> |
| 287 | getProgramList(@Nullable Map<String, String> vendorFilter); |
Tomasz Wasilczyk | d44b2ea | 2017-03-08 10:01:04 -0800 | [diff] [blame] | 288 | |
| 289 | /** |
Tomasz Wasilczyk | 436128f | 2018-01-08 16:46:09 -0800 | [diff] [blame] | 290 | * Get the dynamic list of discovered radio stations. |
| 291 | * |
| 292 | * The list object is updated asynchronously; to get the updates register |
| 293 | * with {@link ProgramList#addListCallback}. |
| 294 | * |
| 295 | * When the returned object is no longer used, it must be closed. |
| 296 | * |
| 297 | * @param filter filter for the list, or null to get the full list. |
| 298 | * @return the dynamic program list object, close it after use |
| 299 | * or {@code null} if program list is not supported by the tuner |
| 300 | */ |
| 301 | public @Nullable ProgramList getDynamicProgramList(@Nullable ProgramList.Filter filter) { |
| 302 | return null; |
| 303 | } |
| 304 | |
| 305 | /** |
Tomasz Wasilczyk | 5f0fbae | 2017-03-27 14:27:44 -0700 | [diff] [blame] | 306 | * Checks, if the analog playback is forced, see setAnalogForced. |
| 307 | * |
| 308 | * @throws IllegalStateException if the switch is not supported at current |
| 309 | * configuration. |
| 310 | * @return {@code true} if analog is forced, {@code false} otherwise. |
Tomasz Wasilczyk | ce40fe9 | 2018-01-04 20:52:39 -0800 | [diff] [blame] | 311 | * @deprecated Use {@link isConfigFlagSet(int)} instead. |
Tomasz Wasilczyk | 5f0fbae | 2017-03-27 14:27:44 -0700 | [diff] [blame] | 312 | */ |
Tomasz Wasilczyk | ce40fe9 | 2018-01-04 20:52:39 -0800 | [diff] [blame] | 313 | @Deprecated |
Tomasz Wasilczyk | 5f0fbae | 2017-03-27 14:27:44 -0700 | [diff] [blame] | 314 | public abstract boolean isAnalogForced(); |
| 315 | |
| 316 | /** |
| 317 | * Forces the analog playback for the supporting radio technology. |
| 318 | * |
| 319 | * User may disable digital playback for FM HD Radio or hybrid FM/DAB with |
| 320 | * this option. This is purely user choice, ie. does not reflect digital- |
| 321 | * analog handover managed from the HAL implementation side. |
| 322 | * |
| 323 | * Some radio technologies may not support this, ie. DAB. |
| 324 | * |
| 325 | * @param isForced {@code true} to force analog, {@code false} for a default behaviour. |
| 326 | * @throws IllegalStateException if the switch is not supported at current |
| 327 | * configuration. |
Tomasz Wasilczyk | ce40fe9 | 2018-01-04 20:52:39 -0800 | [diff] [blame] | 328 | * @deprecated Use {@link setConfigFlag(int, boolean)} instead. |
Tomasz Wasilczyk | 5f0fbae | 2017-03-27 14:27:44 -0700 | [diff] [blame] | 329 | */ |
Tomasz Wasilczyk | ce40fe9 | 2018-01-04 20:52:39 -0800 | [diff] [blame] | 330 | @Deprecated |
Tomasz Wasilczyk | 5f0fbae | 2017-03-27 14:27:44 -0700 | [diff] [blame] | 331 | public abstract void setAnalogForced(boolean isForced); |
| 332 | |
| 333 | /** |
Tomasz Wasilczyk | ce40fe9 | 2018-01-04 20:52:39 -0800 | [diff] [blame] | 334 | * Checks, if a given config flag is supported |
| 335 | * |
| 336 | * @param flag Flag to check. |
| 337 | * @return True, if the flag is supported. |
| 338 | */ |
| 339 | public boolean isConfigFlagSupported(@RadioManager.ConfigFlag int flag) { |
| 340 | return false; |
| 341 | } |
| 342 | |
| 343 | /** |
| 344 | * Fetches the current setting of a given config flag. |
| 345 | * |
| 346 | * The success/failure result is consistent with isConfigFlagSupported. |
| 347 | * |
| 348 | * @param flag Flag to fetch. |
| 349 | * @return The current value of the flag. |
| 350 | * @throws IllegalStateException if the flag is not applicable right now. |
| 351 | * @throws UnsupportedOperationException if the flag is not supported at all. |
| 352 | */ |
| 353 | public boolean isConfigFlagSet(@RadioManager.ConfigFlag int flag) { |
| 354 | throw new UnsupportedOperationException(); |
| 355 | } |
| 356 | |
| 357 | /** |
| 358 | * Sets the config flag. |
| 359 | * |
| 360 | * The success/failure result is consistent with isConfigFlagSupported. |
| 361 | * |
| 362 | * @param flag Flag to set. |
| 363 | * @param value The new value of a given flag. |
| 364 | * @throws IllegalStateException if the flag is not applicable right now. |
| 365 | * @throws UnsupportedOperationException if the flag is not supported at all. |
| 366 | */ |
| 367 | public void setConfigFlag(@RadioManager.ConfigFlag int flag, boolean value) { |
| 368 | throw new UnsupportedOperationException(); |
| 369 | } |
| 370 | |
| 371 | /** |
Tomasz Wasilczyk | 8e932c6 | 2017-11-17 16:18:40 +0000 | [diff] [blame] | 372 | * Generic method for setting vendor-specific parameter values. |
| 373 | * The framework does not interpret the parameters, they are passed |
| 374 | * in an opaque manner between a vendor application and HAL. |
| 375 | * |
| 376 | * Framework does not make any assumptions on the keys or values, other than |
| 377 | * ones stated in VendorKeyValue documentation (a requirement of key |
| 378 | * prefixes). |
Tomasz Wasilczyk | ce40fe9 | 2018-01-04 20:52:39 -0800 | [diff] [blame] | 379 | * See VendorKeyValue at hardware/interfaces/broadcastradio/2.0/types.hal. |
Tomasz Wasilczyk | 8e932c6 | 2017-11-17 16:18:40 +0000 | [diff] [blame] | 380 | * |
| 381 | * For each pair in the result map, the key will be one of the keys |
| 382 | * contained in the input (possibly with wildcards expanded), and the value |
| 383 | * will be a vendor-specific result status (such as "OK" or an error code). |
| 384 | * The implementation may choose to return an empty map, or only return |
| 385 | * a status for a subset of the provided inputs, at its discretion. |
| 386 | * |
| 387 | * Application and HAL must not use keys with unknown prefix. In particular, |
| 388 | * it must not place a key-value pair in results vector for unknown key from |
| 389 | * parameters vector - instead, an unknown key should simply be ignored. |
| 390 | * In other words, results vector may contain a subset of parameter keys |
| 391 | * (however, the framework doesn't enforce a strict subset - the only |
| 392 | * formal requirement is vendor domain prefix for keys). |
| 393 | * |
| 394 | * @param parameters Vendor-specific key-value pairs. |
| 395 | * @return Operation completion status for parameters being set. |
Tomasz Wasilczyk | 8e932c6 | 2017-11-17 16:18:40 +0000 | [diff] [blame] | 396 | */ |
Tomasz Wasilczyk | ce40fe9 | 2018-01-04 20:52:39 -0800 | [diff] [blame] | 397 | public @NonNull Map<String, String> |
| 398 | setParameters(@NonNull Map<String, String> parameters) { |
| 399 | throw new UnsupportedOperationException(); |
| 400 | } |
Tomasz Wasilczyk | 8e932c6 | 2017-11-17 16:18:40 +0000 | [diff] [blame] | 401 | |
| 402 | /** |
| 403 | * Generic method for retrieving vendor-specific parameter values. |
| 404 | * The framework does not interpret the parameters, they are passed |
| 405 | * in an opaque manner between a vendor application and HAL. |
| 406 | * |
| 407 | * Framework does not cache set/get requests, so it's possible for |
| 408 | * getParameter to return a different value than previous setParameter call. |
| 409 | * |
| 410 | * The syntax and semantics of keys are up to the vendor (as long as prefix |
| 411 | * rules are obeyed). For instance, vendors may include some form of |
| 412 | * wildcard support. In such case, result vector may be of different size |
| 413 | * than requested keys vector. However, wildcards are not recognized by |
| 414 | * framework and they are passed as-is to the HAL implementation. |
| 415 | * |
| 416 | * Unknown keys must be ignored and not placed into results vector. |
| 417 | * |
| 418 | * @param keys Parameter keys to fetch. |
| 419 | * @return Vendor-specific key-value pairs. |
Tomasz Wasilczyk | 8e932c6 | 2017-11-17 16:18:40 +0000 | [diff] [blame] | 420 | */ |
Tomasz Wasilczyk | ce40fe9 | 2018-01-04 20:52:39 -0800 | [diff] [blame] | 421 | public @NonNull Map<String, String> |
| 422 | getParameters(@NonNull List<String> keys) { |
| 423 | throw new UnsupportedOperationException(); |
| 424 | } |
Tomasz Wasilczyk | 8e932c6 | 2017-11-17 16:18:40 +0000 | [diff] [blame] | 425 | |
| 426 | /** |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 427 | * Get current antenna connection state for current configuration. |
| 428 | * Only valid if a configuration has been applied. |
| 429 | * @return {@code true} if the antenna is connected, {@code false} otherwise. |
| 430 | */ |
| 431 | public abstract boolean isAntennaConnected(); |
| 432 | |
| 433 | /** |
| 434 | * Indicates if this client actually controls the tuner. |
| 435 | * Control is always granted after |
| 436 | * {@link RadioManager#openTuner(int, |
| 437 | * RadioManager.BandConfig, boolean, Callback, Handler)} |
| 438 | * returns a non null tuner interface. |
| 439 | * Control is lost when another client opens an interface on the same tuner. |
| 440 | * When this happens, {@link Callback#onControlChanged(boolean)} is received. |
| 441 | * The client can either wait for control to be returned (which is indicated by the same |
| 442 | * callback) or close and reopen the tuner interface. |
| 443 | * @return {@code true} if this interface controls the tuner, |
| 444 | * {@code false} otherwise or if a problem occured retrieving the state. |
| 445 | */ |
| 446 | public abstract boolean hasControl(); |
| 447 | |
| 448 | /** Indicates a failure of radio IC or driver. |
| 449 | * The application must close and re open the tuner */ |
| 450 | public static final int ERROR_HARDWARE_FAILURE = 0; |
| 451 | /** Indicates a failure of the radio service. |
| 452 | * The application must close and re open the tuner */ |
| 453 | public static final int ERROR_SERVER_DIED = 1; |
| 454 | /** A pending seek or tune operation was cancelled */ |
| 455 | public static final int ERROR_CANCELLED = 2; |
| 456 | /** A pending seek or tune operation timed out */ |
| 457 | public static final int ERROR_SCAN_TIMEOUT = 3; |
| 458 | /** The requested configuration could not be applied */ |
| 459 | public static final int ERROR_CONFIG = 4; |
Tomasz Wasilczyk | 05392d6 | 2017-07-10 19:33:22 -0700 | [diff] [blame] | 460 | /** Background scan was interrupted due to hardware becoming temporarily unavailable. */ |
Tomasz Wasilczyk | c9a1ac7 | 2017-05-17 21:29:28 -0700 | [diff] [blame] | 461 | public static final int ERROR_BACKGROUND_SCAN_UNAVAILABLE = 5; |
Tomasz Wasilczyk | 05392d6 | 2017-07-10 19:33:22 -0700 | [diff] [blame] | 462 | /** Background scan failed due to other error, ie. HW failure. */ |
Tomasz Wasilczyk | c9a1ac7 | 2017-05-17 21:29:28 -0700 | [diff] [blame] | 463 | public static final int ERROR_BACKGROUND_SCAN_FAILED = 6; |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 464 | |
| 465 | /** |
| 466 | * Callback provided by the client application when opening a {@link RadioTuner} |
| 467 | * to receive asynchronous operation results, updates and error notifications. |
| 468 | */ |
| 469 | public static abstract class Callback { |
| 470 | /** |
| 471 | * onError() is called when an error occured while performing an asynchronous |
| 472 | * operation of when the hardware or system service experiences a problem. |
| 473 | * status is one of {@link #ERROR_HARDWARE_FAILURE}, {@link #ERROR_SERVER_DIED}, |
| 474 | * {@link #ERROR_CANCELLED}, {@link #ERROR_SCAN_TIMEOUT}, |
| 475 | * {@link #ERROR_CONFIG} |
| 476 | */ |
| 477 | public void onError(int status) {} |
| 478 | /** |
| 479 | * onConfigurationChanged() is called upon successful completion of |
| 480 | * {@link RadioManager#openTuner(int, RadioManager.BandConfig, boolean, Callback, Handler)} |
| 481 | * or {@link RadioTuner#setConfiguration(RadioManager.BandConfig)} |
| 482 | */ |
| 483 | public void onConfigurationChanged(RadioManager.BandConfig config) {} |
Tomasz Wasilczyk | 24250ef | 2017-07-13 15:59:08 -0700 | [diff] [blame] | 484 | |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 485 | /** |
Tomasz Wasilczyk | 24250ef | 2017-07-13 15:59:08 -0700 | [diff] [blame] | 486 | * Called when program info (including metadata) for the current program has changed. |
| 487 | * |
| 488 | * It happens either upon successful completion of {@link RadioTuner#step(int, boolean)}, |
| 489 | * {@link RadioTuner#scan(int, boolean)}, {@link RadioTuner#tune(int, int)}; when |
| 490 | * a switching to alternate frequency occurs; or when metadata is updated. |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 491 | */ |
| 492 | public void onProgramInfoChanged(RadioManager.ProgramInfo info) {} |
Tomasz Wasilczyk | 24250ef | 2017-07-13 15:59:08 -0700 | [diff] [blame] | 493 | |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 494 | /** |
Tomasz Wasilczyk | 24250ef | 2017-07-13 15:59:08 -0700 | [diff] [blame] | 495 | * Called when metadata is updated for the current program. |
| 496 | * |
| 497 | * @deprecated Use {@link #onProgramInfoChanged(RadioManager.ProgramInfo)} instead. |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 498 | */ |
Tomasz Wasilczyk | 24250ef | 2017-07-13 15:59:08 -0700 | [diff] [blame] | 499 | @Deprecated |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 500 | public void onMetadataChanged(RadioMetadata metadata) {} |
Tomasz Wasilczyk | 24250ef | 2017-07-13 15:59:08 -0700 | [diff] [blame] | 501 | |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 502 | /** |
| 503 | * onTrafficAnnouncement() is called when a traffic announcement starts and stops. |
| 504 | */ |
| 505 | public void onTrafficAnnouncement(boolean active) {} |
| 506 | /** |
Sanket Agarwal | 7058e4c | 2015-10-08 14:14:20 -0700 | [diff] [blame] | 507 | * onEmergencyAnnouncement() is called when an emergency annoucement starts and stops. |
| 508 | */ |
| 509 | public void onEmergencyAnnouncement(boolean active) {} |
| 510 | /** |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 511 | * onAntennaState() is called when the antenna is connected or disconnected. |
| 512 | */ |
| 513 | public void onAntennaState(boolean connected) {} |
| 514 | /** |
| 515 | * onControlChanged() is called when the client loses or gains control of the radio tuner. |
| 516 | * The control is always granted after a successful call to |
| 517 | * {@link RadioManager#openTuner(int, RadioManager.BandConfig, boolean, Callback, Handler)}. |
| 518 | * If another client opens the same tuner, onControlChanged() will be called with |
| 519 | * control set to {@code false} to indicate loss of control. |
| 520 | * At this point, RadioTuner APIs other than getters will return |
| 521 | * {@link RadioManager#STATUS_INVALID_OPERATION}. |
| 522 | * When the other client releases the tuner, onControlChanged() will be called |
| 523 | * with control set to {@code true}. |
| 524 | */ |
| 525 | public void onControlChanged(boolean control) {} |
Tomasz Wasilczyk | e597ce1 | 2017-03-24 13:50:53 -0700 | [diff] [blame] | 526 | |
| 527 | /** |
| 528 | * onBackgroundScanAvailabilityChange() is called when background scan |
| 529 | * feature becomes available or not. |
| 530 | * |
| 531 | * @param isAvailable true, if the tuner turned temporarily background- |
| 532 | * capable, false in the other case. |
Tomasz Wasilczyk | e597ce1 | 2017-03-24 13:50:53 -0700 | [diff] [blame] | 533 | */ |
| 534 | public void onBackgroundScanAvailabilityChange(boolean isAvailable) {} |
| 535 | |
| 536 | /** |
| 537 | * Called when a background scan completes successfully. |
Tomasz Wasilczyk | e597ce1 | 2017-03-24 13:50:53 -0700 | [diff] [blame] | 538 | */ |
| 539 | public void onBackgroundScanComplete() {} |
| 540 | |
| 541 | /** |
| 542 | * Called when available program list changed. |
| 543 | * |
Tomasz Wasilczyk | 24250ef | 2017-07-13 15:59:08 -0700 | [diff] [blame] | 544 | * Use {@link RadioTuner#getProgramList(String)} to get an actual list. |
Tomasz Wasilczyk | e597ce1 | 2017-03-24 13:50:53 -0700 | [diff] [blame] | 545 | */ |
| 546 | public void onProgramListChanged() {} |
Tomasz Wasilczyk | 8e932c6 | 2017-11-17 16:18:40 +0000 | [diff] [blame] | 547 | |
| 548 | /** |
| 549 | * Generic callback for passing updates to vendor-specific parameter values. |
| 550 | * The framework does not interpret the parameters, they are passed |
| 551 | * in an opaque manner between a vendor application and HAL. |
| 552 | * |
| 553 | * It's up to the HAL implementation if and how to implement this callback, |
| 554 | * as long as it obeys the prefix rule. In particular, only selected keys |
| 555 | * may be notified this way. However, setParameters must not trigger |
| 556 | * this callback, while an internal event can change parameters |
| 557 | * asynchronously. |
| 558 | * |
| 559 | * @param parameters Vendor-specific key-value pairs. |
Tomasz Wasilczyk | 8e932c6 | 2017-11-17 16:18:40 +0000 | [diff] [blame] | 560 | */ |
| 561 | public void onParametersUpdated(@NonNull Map<String, String> parameters) {} |
Eric Laurent | 2035ac8 | 2015-03-05 15:18:44 -0800 | [diff] [blame] | 562 | } |
| 563 | |
| 564 | } |
| 565 | |