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 19 import android.Manifest; 20 import android.annotation.FlaggedApi; 21 import android.annotation.IntDef; 22 import android.annotation.NonNull; 23 import android.annotation.Nullable; 24 import android.annotation.RequiresPermission; 25 import android.annotation.SystemApi; 26 import android.graphics.Bitmap; 27 import android.os.Handler; 28 29 import java.lang.annotation.Retention; 30 import java.lang.annotation.RetentionPolicy; 31 import java.util.List; 32 import java.util.Map; 33 import java.util.concurrent.Executor; 34 35 /** 36 * RadioTuner interface provides methods to control a radio tuner on the device: selecting and 37 * configuring the active band, muting/unmuting, scanning and tuning, etc... 38 * 39 * Obtain a RadioTuner interface by calling {@link RadioManager#openTuner(int, 40 * RadioManager.BandConfig, boolean, RadioTuner.Callback, Handler)}. 41 * @hide 42 */ 43 @SystemApi 44 public abstract class RadioTuner { 45 46 /** Scanning direction UP for {@link #step(int, boolean)}, {@link #scan(int, boolean)} */ 47 public static final int DIRECTION_UP = 0; 48 49 /** Scanning directions DOWN for {@link #step(int, boolean)}, {@link #scan(int, boolean)} */ 50 public static final int DIRECTION_DOWN = 1; 51 52 /** 53 * Close the tuner interface. 54 * 55 * <p>The {@link Callback} callback will not be called anymore and associated resources will be 56 * released. Must be called when the tuner is not needed to make hardware resources available 57 * to others. 58 * */ 59 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) close()60 public abstract void close(); 61 62 /** 63 * Set the active band configuration for this module. 64 * 65 * <p>Must be a valid configuration obtained via buildConfig() from a valid BandDescriptor 66 * listed in the ModuleProperties of the module with the specified ID. 67 * 68 * @param config The desired band configuration (FmBandConfig or AmBandConfig). 69 * @return 70 * <ul> 71 * <li>{@link RadioManager#STATUS_OK} in case of success, </li> 72 * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> 73 * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> 74 * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> 75 * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> 76 * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native 77 * service fails, </li> 78 * </ul> 79 * @deprecated Only applicable for HAL 1.x. 80 */ 81 @Deprecated 82 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) 83 @RadioManager.RadioStatusType setConfiguration(RadioManager.BandConfig config)84 public abstract int setConfiguration(RadioManager.BandConfig config); 85 86 /** 87 * Get current configuration. 88 * 89 * @param config a BandConfig array of lengh 1 where the configuration is returned. 90 * @return 91 * <ul> 92 * <li>{@link RadioManager#STATUS_OK} in case of success, </li> 93 * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> 94 * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> 95 * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> 96 * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> 97 * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native 98 * service fails, </li> 99 * </ul> 100 * 101 * @deprecated Only applicable for HAL 1.x. 102 */ 103 @Deprecated 104 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) 105 @RadioManager.RadioStatusType getConfiguration(RadioManager.BandConfig[] config)106 public abstract int getConfiguration(RadioManager.BandConfig[] config); 107 108 109 /** 110 * Set mute state. 111 * 112 * <p>When muted, the radio tuner audio source is not available for playback on 113 * any audio device. when unmuted, the radio tuner audio source is output as a media source 114 * and renderd over the audio device selected for media use case. 115 * The radio tuner audio source is muted by default when the tuner is first attached. 116 * Only effective if the tuner is attached with audio enabled. 117 * 118 * @param mute the requested mute state. 119 * @return 120 * <ul> 121 * <li>{@link RadioManager#STATUS_OK} in case of success, </li> 122 * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> 123 * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> 124 * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> 125 * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native 126 * service fails, </li> 127 * </ul> 128 */ 129 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) 130 @RadioManager.RadioStatusType setMute(boolean mute)131 public abstract int setMute(boolean mute); 132 133 /** 134 * Get mute state. 135 * 136 * @return {@code true} if the radio tuner audio source is muted or a problem occured 137 * retrieving the mute state, {@code false} otherwise. 138 */ 139 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) getMute()140 public abstract boolean getMute(); 141 142 /** 143 * Step up or down by one channel spacing. 144 * 145 * <p>The operation is asynchronous and {@link Callback#onProgramInfoChanged} 146 * will be called when step completes or {@link Callback#onTuneFailed} 147 * when timeout or canceled. 148 * 149 * <p>When this operation is called by users other than current user or system user, it is 150 * ignored silently. 151 * 152 * @param direction {@link #DIRECTION_UP} or {@link #DIRECTION_DOWN}. 153 * @param skipSubChannel indicates to skip sub channels when the configuration currently 154 * selected supports sub channel (e.g HD Radio). N/A otherwise. 155 * @return 156 * <ul> 157 * <li>{@link RadioManager#STATUS_OK} in case of success, </li> 158 * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> 159 * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> 160 * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> 161 * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> 162 * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native 163 * service fails, </li> 164 * </ul> 165 */ 166 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) 167 @RadioManager.RadioStatusType step(int direction, boolean skipSubChannel)168 public abstract int step(int direction, boolean skipSubChannel); 169 170 /** 171 * Scan up or down to next valid station. 172 * 173 * <p>The operation is asynchronous and {@link Callback#onProgramInfoChanged} 174 * will be called when scan completes or {@link Callback#onTuneFailed} 175 * when timeout or canceled. 176 * 177 * <p>When this operation is called by users other than current user or system user, it is 178 * ignored silently. 179 * 180 * @param direction {@link #DIRECTION_UP} or {@link #DIRECTION_DOWN}. 181 * @param skipSubChannel indicates to skip sub channels when the configuration currently 182 * selected supports sub channel (e.g HD Radio). N/A otherwise. 183 * @return 184 * <ul> 185 * <li>{@link RadioManager#STATUS_OK} in case of success, </li> 186 * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> 187 * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> 188 * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> 189 * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> 190 * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native 191 * service fails, </li> 192 * </ul> 193 * @deprecated Use {@link #seek(int, boolean)} instead. 194 */ 195 @Deprecated 196 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) 197 @RadioManager.RadioStatusType scan(int direction, boolean skipSubChannel)198 public abstract int scan(int direction, boolean skipSubChannel); 199 200 /** 201 * Seek up or down to next valid station. 202 * 203 * <p>The operation is asynchronous and {@link Callback#onProgramInfoChanged} 204 * will be called when seek completes or {@link Callback#onTuneFailed} 205 * when timeout or canceled. 206 * 207 * <p>When this operation is called by users other than current user or system user, it is 208 * ignore silently. 209 * 210 * @param direction {@link #DIRECTION_UP} or {@link #DIRECTION_DOWN}. 211 * @param skipSubChannel indicates to skip sub channels when the configuration currently 212 * selected supports sub channel (e.g HD Radio). N/A otherwise. 213 * @return 214 * <ul> 215 * <li>{@link RadioManager#STATUS_OK} in case of success, </li> 216 * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> 217 * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> 218 * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> 219 * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> 220 * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native 221 * service fails, </li> 222 * </ul> 223 */ 224 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) 225 @RadioManager.RadioStatusType seek(int direction, boolean skipSubChannel)226 public int seek(int direction, boolean skipSubChannel) { 227 throw new UnsupportedOperationException("Seeking is not supported"); 228 } 229 230 /** 231 * Tune to a specific frequency. 232 * 233 * <p>The operation is asynchronous and {@link Callback#onProgramInfoChanged} 234 * will be called when tune completes or {@link Callback#onTuneFailed} 235 * when timeout or canceled. 236 * 237 * <p>When this operation is called by users other than current user or system user, it is 238 * ignored silently. 239 * 240 * @param channel the specific channel or frequency to tune to. 241 * @param subChannel the specific sub-channel to tune to. N/A if the selected configuration 242 * does not support cub channels. 243 * @return 244 * <ul> 245 * <li>{@link RadioManager#STATUS_OK} in case of success, </li> 246 * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> 247 * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> 248 * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> 249 * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> 250 * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native 251 * service fails, </li> 252 * </ul> 253 * @deprecated Use {@link #tune(ProgramSelector)} instead. 254 */ 255 @Deprecated 256 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) 257 @RadioManager.RadioStatusType tune(int channel, int subChannel)258 public abstract int tune(int channel, int subChannel); 259 260 /** 261 * Tune to a program. 262 * 263 * <p>The operation is asynchronous and {@link Callback#onProgramInfoChanged} 264 * will be called when tune completes or {@link Callback#onTuneFailed} 265 * when timeout or canceled. 266 * 267 * <p>When this operation is called by users other than current user or system user, it is 268 * ignored silently. 269 * 270 * @throws IllegalArgumentException if the provided selector is invalid 271 */ 272 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) tune(@onNull ProgramSelector selector)273 public abstract void tune(@NonNull ProgramSelector selector); 274 275 /** 276 * Cancel a pending scan or tune operation. 277 * 278 * <p>If an operation is pending, {@link Callback#onTuneFailed} will be called with 279 * {@link #ERROR_CANCELLED}. 280 * 281 * <p>When this operation is called by users other than current user or system 282 * user, it is ignored silently. 283 * 284 * @return 285 * <ul> 286 * <li>{@link RadioManager#STATUS_OK} in case of success, </li> 287 * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> 288 * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> 289 * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> 290 * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> 291 * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native 292 * service fails, </li> 293 * </ul> 294 */ 295 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) 296 @RadioManager.RadioStatusType cancel()297 public abstract int cancel(); 298 299 /** 300 * Cancels traffic or emergency announcement. 301 * 302 * <p>If there was no announcement to cancel, no action is taken. 303 * 304 * <p>There is a race condition between calling cancelAnnouncement and the actual announcement 305 * being finished, so onTrafficAnnouncement / onEmergencyAnnouncement callback should be 306 * tracked with proper locking. 307 * @deprecated Only applicable for HAL 1.x. 308 */ 309 @Deprecated 310 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) cancelAnnouncement()311 public abstract void cancelAnnouncement(); 312 313 /** 314 * Get current station information. 315 * 316 * @param info a ProgramInfo array of lengh 1 where the information is returned. 317 * @return 318 * <ul> 319 * <li>{@link RadioManager#STATUS_OK} in case of success, </li> 320 * <li>{@link RadioManager#STATUS_ERROR} in case of unspecified error, </li> 321 * <li>{@link RadioManager#STATUS_NO_INIT} if the native service cannot be reached, </li> 322 * <li>{@link RadioManager#STATUS_BAD_VALUE} if parameters are invalid, </li> 323 * <li>{@link RadioManager#STATUS_INVALID_OPERATION} if the call is out of sequence, </li> 324 * <li>{@link RadioManager#STATUS_DEAD_OBJECT} if the binder transaction to the native 325 * service fails, </li> 326 * </ul> 327 * @deprecated Use {@link Callback#onProgramInfoChanged(RadioManager.ProgramInfo)} callback 328 * instead. 329 */ 330 @Deprecated 331 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) 332 @RadioManager.RadioStatusType getProgramInformation(RadioManager.ProgramInfo[] info)333 public abstract int getProgramInformation(RadioManager.ProgramInfo[] info); 334 335 /** 336 * Retrieves a {@link Bitmap} for the given image ID or throw {@link IllegalArgumentException}, 337 * if the image was missing from the tuner. 338 * 339 * <p>This involves doing a call to the tuner, so the bitmap should be cached 340 * on the application side. 341 * 342 * <p>If the method throws {@link IllegalArgumentException} for non-zero ID, it 343 * means the image was updated on the tuner side. There is a race condition between 344 * fetching image for an old ID and tuner updating the image (and cleaning up the 345 * old image). In such case, a new ProgramInfo with updated image id will 346 * be sent with a {@link Callback#onProgramInfoChanged(RadioManager.ProgramInfo)} 347 * callback. 348 * 349 * @param id The image identifier, retrieved with 350 * {@link RadioMetadata#getBitmapId(String)}. 351 * @return A {@link Bitmap} for the given image ID. 352 * @throws IllegalArgumentException if id is 0 or the referenced image id no longer exists. 353 */ 354 @FlaggedApi(Flags.FLAG_HD_RADIO_IMPROVED) 355 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) getMetadataImage(int id)356 public @NonNull Bitmap getMetadataImage(int id) { 357 throw new UnsupportedOperationException( 358 "Getting metadata image must be implemented in child classes"); 359 } 360 /** 361 * Initiates a background scan to update internally cached program list. 362 * 363 * <p>It may not be necessary to initiate the scan explicitly - the scan MAY be performed on 364 * boot. 365 * 366 * <p>The operation is asynchronous and {@link Callback} backgroundScanComplete or onError will 367 * be called if the return value of this call was {@code true}. As result of this call 368 * programListChanged may be triggered (if the scanned list differs). 369 * 370 * @return {@code true} if the scan was properly scheduled, {@code false} if the scan feature 371 * is unavailable; ie. temporarily due to ongoing foreground playback in single-tuner device 372 * or permanently if the feature is not supported 373 * (see ModuleProperties#isBackgroundScanningSupported()). 374 * @deprecated Only applicable for HAL 1.x. 375 */ 376 @Deprecated 377 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) startBackgroundScan()378 public abstract boolean startBackgroundScan(); 379 380 /** 381 * Get the list of discovered radio stations. 382 * 383 * <p>To get the full list, set filter to null or empty map. 384 * Keys must be prefixed with unique vendor Java-style namespace, 385 * eg. 'com.somecompany.parameter1'. 386 * 387 * @param vendorFilter vendor-specific selector for radio stations. 388 * @return a list of radio stations. 389 * @throws IllegalStateException if the scan is in progress or has not been started, 390 * startBackgroundScan() call may fix it. 391 * @throws IllegalArgumentException if the vendorFilter argument is not valid. 392 * @deprecated Use {@link #getDynamicProgramList(ProgramList.Filter)} instead. 393 */ 394 @Deprecated 395 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) 396 public abstract @NonNull List<RadioManager.ProgramInfo> getProgramList(@ullable Map<String, String> vendorFilter)397 getProgramList(@Nullable Map<String, String> vendorFilter); 398 399 /** 400 * Get the dynamic list of discovered radio stations. 401 * 402 * <p>The list object is updated asynchronously; to get the updates register 403 * with {@link ProgramList#registerListCallback(ProgramList.ListCallback)} 404 * or {@link ProgramList#registerListCallback(Executor, ProgramList.ListCallback)}. 405 * 406 * <p>When the returned object is no longer used, it must be closed. 407 * 408 * @param filter filter for the list, or null to get the full list. 409 * @return the dynamic program list object, close it after use 410 * or {@code null} if program list is not supported by the tuner 411 */ 412 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) getDynamicProgramList(@ullable ProgramList.Filter filter)413 public @Nullable ProgramList getDynamicProgramList(@Nullable ProgramList.Filter filter) { 414 return null; 415 } 416 417 /** 418 * Checks, if the analog playback is forced, see setAnalogForced. 419 * 420 * @throws IllegalStateException if the switch is not supported at current 421 * configuration. 422 * @return {@code true} if analog is forced, {@code false} otherwise. 423 * @deprecated Use {@link #isConfigFlagSet(int)} instead. 424 */ 425 @Deprecated 426 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) isAnalogForced()427 public abstract boolean isAnalogForced(); 428 429 /** 430 * Forces the analog playback for the supporting radio technology. 431 * 432 * <p>User may disable digital playback for FM HD Radio or hybrid FM/DAB with 433 * this option. This is purely user choice, ie. does not reflect digital- 434 * analog handover managed from the HAL implementation side. 435 * 436 * <p>Some radio technologies may not support this, ie. DAB. 437 * 438 * @param isForced {@code true} to force analog, {@code false} for a default behaviour. 439 * @throws IllegalStateException if the switch is not supported at current 440 * configuration. 441 * @deprecated Use {@link #setConfigFlag(int, boolean)} instead. 442 */ 443 @Deprecated 444 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) setAnalogForced(boolean isForced)445 public abstract void setAnalogForced(boolean isForced); 446 447 /** 448 * Checks, if a given config flag is supported 449 * 450 * @param flag Flag to check. 451 * @return True, if the flag is supported. 452 */ 453 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) isConfigFlagSupported(@adioManager.ConfigFlag int flag)454 public boolean isConfigFlagSupported(@RadioManager.ConfigFlag int flag) { 455 return false; 456 } 457 458 /** 459 * Fetches the current setting of a given config flag. 460 * 461 * <p>The success/failure result is consistent with isConfigFlagSupported. 462 * 463 * @param flag Flag to fetch. 464 * @return The current value of the flag. 465 * @throws IllegalStateException if the flag is not applicable right now. 466 * @throws UnsupportedOperationException if the flag is not supported at all. 467 */ 468 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) isConfigFlagSet(@adioManager.ConfigFlag int flag)469 public boolean isConfigFlagSet(@RadioManager.ConfigFlag int flag) { 470 throw new UnsupportedOperationException("isConfigFlagSet is not supported"); 471 } 472 473 /** 474 * Sets the config flag. 475 * 476 * <p>The success/failure result is consistent with isConfigFlagSupported. 477 * 478 * <p>When this operation is called by users other than current user or system user, 479 * it is ignored silently. 480 * 481 * @param flag Flag to set. 482 * @param value The new value of a given flag. 483 * @throws IllegalStateException if the flag is not applicable right now. 484 * @throws UnsupportedOperationException if the flag is not supported at all. 485 */ 486 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) setConfigFlag(@adioManager.ConfigFlag int flag, boolean value)487 public void setConfigFlag(@RadioManager.ConfigFlag int flag, boolean value) { 488 throw new UnsupportedOperationException("Setting config flag is not supported"); 489 } 490 491 /** 492 * Generic method for setting vendor-specific parameter values. 493 * The framework does not interpret the parameters, they are passed 494 * in an opaque manner between a vendor application and HAL. 495 * 496 * <p>Framework does not make any assumptions on the keys or values, other than 497 * ones stated in VendorKeyValue documentation (a requirement of key 498 * prefixes). 499 * See VendorKeyValue at hardware/interfaces/broadcastradio/2.0/types.hal for 500 * HIDL 2.0 HAL or 501 * hardware/interfaces/broadcastradio/aidl/android/hardware/broadcastradio/VendorKeyValue.aidl 502 * for AIDL HAL. 503 * 504 * <p>For each pair in the result map, the key will be one of the keys 505 * contained in the input (possibly with wildcards expanded), and the value 506 * will be a vendor-specific result status (such as "OK" or an error code). 507 * The implementation may choose to return an empty map, or only return 508 * a status for a subset of the provided inputs, at its discretion. 509 * 510 * <p>Application and HAL must not use keys with unknown prefix. In particular, 511 * it must not place a key-value pair in results vector for unknown key from 512 * parameters vector - instead, an unknown key should simply be ignored. 513 * In other words, results vector may contain a subset of parameter keys 514 * (however, the framework doesn't enforce a strict subset - the only 515 * formal requirement is vendor domain prefix for keys). 516 * 517 * <p>When this operation is called by users other than current user or system user, 518 * it is ignored silently. 519 * 520 * @param parameters Vendor-specific key-value pairs. 521 * @return Operation completion status for parameters being set. 522 */ 523 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) 524 public @NonNull Map<String, String> setParameters(@onNull Map<String, String> parameters)525 setParameters(@NonNull Map<String, String> parameters) { 526 throw new UnsupportedOperationException("Setting parameters is not supported"); 527 } 528 529 /** 530 * Generic method for retrieving vendor-specific parameter values. 531 * The framework does not interpret the parameters, they are passed 532 * in an opaque manner between a vendor application and HAL. 533 * 534 * <p>Framework does not cache set/get requests, so it's possible for 535 * getParameter to return a different value than previous setParameter call. 536 * 537 * <p>The syntax and semantics of keys are up to the vendor (as long as prefix 538 * rules are obeyed). For instance, vendors may include some form of 539 * wildcard support. In such case, result vector may be of different size 540 * than requested keys vector. However, wildcards are not recognized by 541 * framework and they are passed as-is to the HAL implementation. 542 * 543 * <p>Unknown keys must be ignored and not placed into results vector. 544 * 545 * @param keys Parameter keys to fetch. 546 * @return Vendor-specific key-value pairs. 547 */ 548 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) 549 public @NonNull Map<String, String> getParameters(@onNull List<String> keys)550 getParameters(@NonNull List<String> keys) { 551 throw new UnsupportedOperationException("Getting parameters is not supported"); 552 } 553 554 /** 555 * Get current antenna connection state for current configuration. 556 * Only valid if a configuration has been applied. 557 * @return {@code true} if the antenna is connected, {@code false} otherwise. 558 * 559 * @deprecated Use {@link Callback#onAntennaState(boolean)} callback instead 560 */ 561 @Deprecated 562 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) isAntennaConnected()563 public abstract boolean isAntennaConnected(); 564 565 /** 566 * Indicates if this client actually controls the tuner. 567 * 568 * <p>Control is always granted after 569 * {@link RadioManager#openTuner(int, 570 * RadioManager.BandConfig, boolean, Callback, Handler)} 571 * returns a non null tuner interface. 572 * Control is lost when another client opens an interface on the same tuner. 573 * When this happens, {@link Callback#onControlChanged(boolean)} is received. 574 * The client can either wait for control to be returned (which is indicated by the same 575 * callback) or close and reopen the tuner interface. 576 * 577 * @return {@code true} if this interface controls the tuner, 578 * {@code false} otherwise or if a problem occured retrieving the state. 579 */ 580 @RequiresPermission(Manifest.permission.ACCESS_BROADCAST_RADIO) hasControl()581 public abstract boolean hasControl(); 582 583 /** Indicates a failure of radio IC or driver. 584 * 585 * <p>The application must close and re open the tuner 586 * 587 * @deprecated See {@link RadioTuner.Callback#onError(int)} callback. 588 */ 589 @Deprecated 590 public static final int ERROR_HARDWARE_FAILURE = 0; 591 /** Indicates a failure of the radio service. 592 * 593 * <p>The application must close and re open the tuner 594 * @deprecated See {@link RadioTuner.Callback#onError(int)} callback. 595 */ 596 @Deprecated 597 public static final int ERROR_SERVER_DIED = 1; 598 /** A pending seek or tune operation was cancelled 599 * @deprecated See {@link RadioTuner.Callback#onError(int)} callback. 600 */ 601 @Deprecated 602 public static final int ERROR_CANCELLED = 2; 603 /** A pending seek or tune operation timed out 604 * @deprecated See {@link RadioTuner.Callback#onError(int)} callback. 605 */ 606 @Deprecated 607 public static final int ERROR_SCAN_TIMEOUT = 3; 608 /** The requested configuration could not be applied 609 * @deprecated See {@link RadioTuner.Callback#onError(int)} callback. 610 */ 611 @Deprecated 612 public static final int ERROR_CONFIG = 4; 613 /** Background scan was interrupted due to hardware becoming temporarily unavailable. 614 * @deprecated See {@link RadioTuner.Callback#onError(int)} callback. 615 */ 616 @Deprecated 617 public static final int ERROR_BACKGROUND_SCAN_UNAVAILABLE = 5; 618 /** Background scan failed due to other error, ie. HW failure. 619 * @deprecated See {@link RadioTuner.Callback#onError(int)} callback. 620 */ 621 @Deprecated 622 public static final int ERROR_BACKGROUND_SCAN_FAILED = 6; 623 /** Result when a tune, seek, or step operation runs without error. 624 */ 625 public static final int TUNER_RESULT_OK = 0; 626 /** Result when internal error occurs in HAL. 627 * See {@link RadioTuner.Callback#onTuneFailed(int, ProgramSelector)} callback. 628 */ 629 public static final int TUNER_RESULT_INTERNAL_ERROR = 1; 630 /** Result used when the input argument for the method is invalid. 631 * See {@link RadioTuner.Callback#onTuneFailed(int, ProgramSelector)} callback. 632 */ 633 public static final int TUNER_RESULT_INVALID_ARGUMENTS = 2; 634 /** Result when HAL is of invalid state. 635 * See {@link RadioTuner.Callback#onTuneFailed(int, ProgramSelector)} callback. 636 */ 637 public static final int TUNER_RESULT_INVALID_STATE = 3; 638 /** Result when the operation is not supported. 639 * See {@link RadioTuner.Callback#onTuneFailed(int, ProgramSelector)} callback. 640 */ 641 public static final int TUNER_RESULT_NOT_SUPPORTED = 4; 642 /** Result when a tune, seek, or step operation is timeout 643 * See {@link RadioTuner.Callback#onTuneFailed(int, ProgramSelector)} callback. 644 */ 645 public static final int TUNER_RESULT_TIMEOUT = 5; 646 /** Result when a tune, seek, or step operation is canceled before processed. 647 * See {@link RadioTuner.Callback#onTuneFailed(int, ProgramSelector)} callback. 648 */ 649 public static final int TUNER_RESULT_CANCELED = 6; 650 /** Result when a tune, seek, or step operation fails due to unknown error. 651 * See {@link RadioTuner.Callback#onTuneFailed(int, ProgramSelector)} callback. 652 */ 653 public static final int TUNER_RESULT_UNKNOWN_ERROR = 7; 654 655 /** 656 * Tuning operation result types 657 * 658 * @hide 659 */ 660 @IntDef(prefix = { "TUNER_RESULT_" }, value = { 661 TUNER_RESULT_OK, 662 TUNER_RESULT_INTERNAL_ERROR, 663 TUNER_RESULT_INVALID_ARGUMENTS, 664 TUNER_RESULT_INVALID_STATE, 665 TUNER_RESULT_NOT_SUPPORTED, 666 TUNER_RESULT_TIMEOUT, 667 TUNER_RESULT_CANCELED, 668 TUNER_RESULT_UNKNOWN_ERROR, 669 }) 670 @Retention(RetentionPolicy.SOURCE) 671 public @interface TunerResultType{} 672 673 /** 674 * Callback provided by the client application when opening a {@link RadioTuner} 675 * to receive asynchronous operation results, updates and error notifications. 676 */ 677 public static abstract class Callback { 678 /** 679 * onError() is called when an error occured while performing an asynchronous 680 * operation of when the hardware or system service experiences a problem. 681 * status is one of {@link #ERROR_HARDWARE_FAILURE}, {@link #ERROR_SERVER_DIED}, 682 * {@link #ERROR_CANCELLED}, {@link #ERROR_SCAN_TIMEOUT}, 683 * {@link #ERROR_CONFIG} 684 * 685 * @deprecated Use {@link RadioTuner.Callback#onTuneFailed(int, ProgramSelector)} for 686 * tune, scan and step; other use cases (configuration, background scan) 687 * are already deprecated. 688 */ onError(int status)689 public void onError(int status) {} 690 691 /** 692 * Called when tune, scan or step operation fails. 693 * 694 * @param result cause of the failure 695 * @param selector ProgramSelector argument of tune that failed; 696 * null for scan and step. 697 */ onTuneFailed(@unerResultType int result, @Nullable ProgramSelector selector)698 public void onTuneFailed(@TunerResultType int result, @Nullable ProgramSelector selector) {} 699 700 /** 701 * onConfigurationChanged() is called upon successful completion of 702 * {@link RadioManager#openTuner(int, RadioManager.BandConfig, boolean, Callback, Handler)} 703 * or {@link RadioTuner#setConfiguration(RadioManager.BandConfig)} 704 * 705 * @deprecated Only applicable for HAL 1.x. 706 */ 707 @Deprecated onConfigurationChanged(RadioManager.BandConfig config)708 public void onConfigurationChanged(RadioManager.BandConfig config) {} 709 710 /** 711 * Called when program info (including metadata) for the current program has changed. 712 * 713 * <p>It happens either upon successful completion of {@link RadioTuner#step(int, boolean)}, 714 * {@link RadioTuner#scan(int, boolean)}, {@link RadioTuner#tune(int, int)}; when 715 * a switching to alternate frequency occurs; or when metadata is updated. 716 */ onProgramInfoChanged(RadioManager.ProgramInfo info)717 public void onProgramInfoChanged(RadioManager.ProgramInfo info) {} 718 719 /** 720 * Called when metadata is updated for the current program. 721 * 722 * @deprecated Use {@link #onProgramInfoChanged(RadioManager.ProgramInfo)} instead. 723 */ 724 @Deprecated onMetadataChanged(RadioMetadata metadata)725 public void onMetadataChanged(RadioMetadata metadata) {} 726 727 /** 728 * onTrafficAnnouncement() is called when a traffic announcement starts and stops. 729 */ onTrafficAnnouncement(boolean active)730 public void onTrafficAnnouncement(boolean active) {} 731 /** 732 * onEmergencyAnnouncement() is called when an emergency annoucement starts and stops. 733 */ onEmergencyAnnouncement(boolean active)734 public void onEmergencyAnnouncement(boolean active) {} 735 /** 736 * onAntennaState() is called when the antenna is connected or disconnected. 737 */ onAntennaState(boolean connected)738 public void onAntennaState(boolean connected) {} 739 /** 740 * onControlChanged() is called when the client loses or gains control of the radio tuner. 741 * The control is always granted after a successful call to 742 * {@link RadioManager#openTuner(int, RadioManager.BandConfig, boolean, Callback, Handler)}. 743 * If another client opens the same tuner, onControlChanged() will be called with 744 * control set to {@code false} to indicate loss of control. 745 * At this point, RadioTuner APIs other than getters will return 746 * {@link RadioManager#STATUS_INVALID_OPERATION}. 747 * When the other client releases the tuner, onControlChanged() will be called 748 * with control set to {@code true}. 749 */ onControlChanged(boolean control)750 public void onControlChanged(boolean control) {} 751 752 /** 753 * onBackgroundScanAvailabilityChange() is called when background scan 754 * feature becomes available or not. 755 * 756 * @param isAvailable true, if the tuner turned temporarily background- 757 * capable, false in the other case. 758 */ onBackgroundScanAvailabilityChange(boolean isAvailable)759 public void onBackgroundScanAvailabilityChange(boolean isAvailable) {} 760 761 /** 762 * Called when a background scan completes successfully. 763 */ onBackgroundScanComplete()764 public void onBackgroundScanComplete() {} 765 766 /** 767 * Called when available program list changed. 768 * 769 * Use {@link RadioTuner#getProgramList(Map)} to get an actual list. 770 */ onProgramListChanged()771 public void onProgramListChanged() {} 772 773 /** 774 * Called when config flags are updated asynchronously due to internal events 775 * in broadcast radio HAL. 776 * 777 * {@link RadioTuner#setConfigFlag(int, boolean)} must not trigger this 778 * callback. 779 * 780 * @param flag Config flag updated 781 * @param value Value of the updated config flag 782 */ onConfigFlagUpdated(@adioManager.ConfigFlag int flag, boolean value)783 public void onConfigFlagUpdated(@RadioManager.ConfigFlag int flag, boolean value) {} 784 785 /** 786 * Generic callback for passing updates to vendor-specific parameter values. 787 * 788 * <p>The framework does not interpret the parameters, they are passed 789 * in an opaque manner between a vendor application and HAL. 790 * 791 * <p>It's up to the HAL implementation if and how to implement this callback, 792 * as long as it obeys the prefix rule. In particular, only selected keys 793 * may be notified this way. However, setParameters must not trigger 794 * this callback, while an internal event can change parameters 795 * asynchronously. 796 * 797 * @param parameters Vendor-specific key-value pairs. 798 */ onParametersUpdated(@onNull Map<String, String> parameters)799 public void onParametersUpdated(@NonNull Map<String, String> parameters) {} 800 } 801 802 } 803 804