broadcastradio/1.0/ITuner.hal

   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.broadcastradio@1.0;
  18
  19 import ITunerCallback;
  20
  21 interface ITuner {
  22
  23     /**
  24      * Apply current radio band configuration (band, range, channel spacing...).
  25      * Automatically cancels pending scan, step or tune.
  26      * ITunerCallback.configChange() method MUST be called once the
  27      * configuration is applied or a failure occurs or after a time out.
  28      * @param config The band configuration to apply.
  29      * @return result OK if configuration could be applied
  30      *                NOT_INITIALIZED in case of initialization error.
  31      *                INVALID_ARGUMENTS if configuration requested is invalid
  32      *
  33      */
  34     setConfiguration(BandConfig config) generates(Result result);
  35
  36     /**
  37      * Retrieve current radio band configuration.
  38      * @return result OK if valid configuration is returned,
  39      *                NOT_INITIALIZED in case of initialization error.
  40      * @param config Current band configuration
  41      */
  42     getConfiguration() generates(Result result, BandConfig config);
  43
  44     /**
  45      * Start scanning up to next valid station.
  46      * Shall be called only when a valid configuration has been applied.
  47      * Automatically cancels pending scan, step or tune.
  48      * ITunerCallback.tuneComplete() MUST be called once locked on a station
  49      * or after a time out or full band scan if no station found.
  50      * The status should indicate if a valid station is tuned or not.
  51      * @param direction UP or DOWN.
  52      * @param skipSubChannel valid for HD radio or digital radios only:
  53      *                       ignore sub channels (e.g SPS for HD radio).
  54      * @return result OK if scan successfully started
  55      *                INVALID_STATE if called out of sequence
  56      *                NOT_INITIALIZED if another error occurs
  57      */
  58     scan(Direction direction, bool skipSubChannel) generates(Result result);
  59
  60     /**
  61      * Move one channel spacing up or down.
  62      * Must be called when a valid configuration has been applied.
  63      * Automatically cancels pending scan, step or tune.
  64      * ITunerCallback.tuneComplete() MUST be called once locked on a station
  65      * or after a time out or full band scan if no station found.
  66      * The status should indicate if a valid station is tuned or not.
  67      * @param direction UP or DOWN.
  68      * @param skipSubChannel valid for HD radio or digital radios only:
  69      *                       ignore sub channels (e.g SPS for HD radio).
  70      * @return result OK if scan successfully started
  71      *                INVALID_STATE if called out of sequence
  72      *                NOT_INITIALIZED if another error occurs
  73      */
  74     step(Direction direction, bool skipSubChannel) generates(Result result);
  75
  76     /**
  77      * Tune to specified channel.
  78      * Must be called when a valid configuration has been applied.
  79      * Automatically cancels pending scan, step or tune.
  80      * ITunerCallback.tuneComplete() MUST be called once locked on a station
  81      * or after a time out or full band scan if no station found.
  82      * The status should indicate if a valid station is tuned or not.
  83      * @param channel Channel to tune to. A frequency in kHz for AM/FM/HD Radio
  84      *                bands.
  85      * @param subChannel Valid for HD radio or digital radios only
  86      *                   (e.g SPS number for HD radio)..
  87      * @return result OK if scan successfully started
  88      *                INVALID_ARGUMENTS if invalid arguments are passed
  89      *                INVALID_STATE if called out of sequence
  90      *                NOT_INITIALIZED if another error occurs
  91      */
  92     tune(uint32_t channel, uint32_t subChannel) generates(Result result);
  93
  94     /**
  95      * Cancel a scan, step or tune operation.
  96      * Shall be called only while a scan, step or tune operation is pending.
  97      * ITunerCallback.tuneComplete() MUST NOT be sent by the HAL.
  98      * @return result OK if scan successfully started
  99      *                INVALID_STATE if called out of sequence
 100      *                NOT_INITIALIZED if another error occurs
 101      */
 102     cancel() generates(Result result);
 103
 104     /**
 105      * Retrieve current station information.
 106      * @return result OK if scan successfully started
 107      *                NOT_INITIALIZED if another error occurs
 108      * @return info Current program information.
 109      */
 110     getProgramInformation() generates(Result result, ProgramInfo info);
 111 };