1 /* 2 * Copyright (C) 2016 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 #ifndef ANDROID_HARDWARE_TUNER_INTERFACE_H 18 #define ANDROID_HARDWARE_TUNER_INTERFACE_H 19 20 #include <utils/RefBase.h> 21 #include <system/radio.h> 22 23 namespace android { 24 25 class TunerInterface : public virtual RefBase 26 { 27 public: 28 /* 29 * Apply current radio band configuration (band, range, channel spacing ...). 30 * 31 * arguments: 32 * - config: the band configuration to apply 33 * 34 * returns: 35 * 0 if configuration could be applied 36 * -EINVAL if configuration requested is invalid 37 * 38 * Automatically cancels pending scan, step or tune. 39 * 40 * Callback function with event RADIO_EVENT_CONFIG MUST be called once the 41 * configuration is applied or a failure occurs or after a time out. 42 */ 43 virtual int setConfiguration(const radio_hal_band_config_t *config) = 0; 44 45 /* 46 * Retrieve current radio band configuration. 47 * 48 * arguments: 49 * - config: where to return the band configuration 50 * 51 * returns: 52 * 0 if valid configuration is returned 53 * -EINVAL if invalid arguments are passed 54 */ 55 virtual int getConfiguration(radio_hal_band_config_t *config) = 0; 56 57 /* 58 * Start scanning up to next valid station. 59 * Must be called when a valid configuration has been applied. 60 * 61 * arguments: 62 * - direction: RADIO_DIRECTION_UP or RADIO_DIRECTION_DOWN 63 * - skip_sub_channel: valid for HD radio or digital radios only: ignore sub channels 64 * (e.g SPS for HD radio). 65 * 66 * returns: 67 * 0 if scan successfully started 68 * -ENOSYS if called out of sequence 69 * -ENODEV if another error occurs 70 * 71 * Automatically cancels pending scan, step or tune. 72 * 73 * Callback function with event RADIO_EVENT_TUNED MUST be called once 74 * locked on a station or after a time out or full frequency scan if 75 * no station found. The event status should indicate if a valid station 76 * is tuned or not. 77 */ 78 virtual int scan(radio_direction_t direction, bool skip_sub_channel) = 0; 79 80 /* 81 * Move one channel spacing up or down. 82 * Must be called when a valid configuration has been applied. 83 * 84 * arguments: 85 * - direction: RADIO_DIRECTION_UP or RADIO_DIRECTION_DOWN 86 * - skip_sub_channel: valid for HD radio or digital radios only: ignore sub channels 87 * (e.g SPS for HD radio). 88 * 89 * returns: 90 * 0 if step successfully started 91 * -ENOSYS if called out of sequence 92 * -ENODEV if another error occurs 93 * 94 * Automatically cancels pending scan, step or tune. 95 * 96 * Callback function with event RADIO_EVENT_TUNED MUST be called once 97 * step completed or after a time out. The event status should indicate 98 * if a valid station is tuned or not. 99 */ 100 virtual int step(radio_direction_t direction, bool skip_sub_channel) = 0; 101 102 /* 103 * Tune to specified frequency. 104 * Must be called when a valid configuration has been applied. 105 * 106 * arguments: 107 * - channel: channel to tune to. A frequency in kHz for AM/FM/HD Radio bands. 108 * - sub_channel: valid for HD radio or digital radios only: (e.g SPS number for HD radio). 109 * 110 * returns: 111 * 0 if tune successfully started 112 * -ENOSYS if called out of sequence 113 * -EINVAL if invalid arguments are passed 114 * -ENODEV if another error occurs 115 * 116 * Automatically cancels pending scan, step or tune. 117 * 118 * Callback function with event RADIO_EVENT_TUNED MUST be called once 119 * tuned or after a time out. The event status should indicate 120 * if a valid station is tuned or not. 121 */ 122 virtual int tune(unsigned int channel, unsigned int sub_channel) = 0; 123 124 /* 125 * Cancel a scan, step or tune operation. 126 * Must be called while a scan, step or tune operation is pending 127 * (callback not yet sent). 128 * 129 * returns: 130 * 0 if successful 131 * -ENOSYS if called out of sequence 132 * -ENODEV if another error occurs 133 * 134 * The callback is not sent. 135 */ 136 virtual int cancel() = 0; 137 138 /* 139 * Retrieve current station information. 140 * 141 * arguments: 142 * - info: where to return the program info. 143 * If info->metadata is NULL. no meta data should be returned. 144 * If meta data must be returned, they should be added to or cloned to 145 * info->metadata, not passed from a newly created meta data buffer. 146 * 147 * returns: 148 * 0 if tuned and information available 149 * -EINVAL if invalid arguments are passed 150 * -ENODEV if another error occurs 151 */ 152 virtual int getProgramInformation(radio_program_info_t *info) = 0; 153 154 protected: TunerInterface()155 TunerInterface() {} ~TunerInterface()156 virtual ~TunerInterface() {} 157 158 }; 159 160 } // namespace android 161 162 #endif // ANDROID_HARDWARE_TUNER_INTERFACE_H 163