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
17package android.hardware.broadcastradio@1.0;
18
19import ITunerCallback;
20
21interface 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};
112