1/* Copyright (C) 2017 The Android Open Source Project
2 *
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *      http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16package android.hardware.broadcastradio@2.0;
17
18interface ITunerCallback {
19    /**
20     * Method called by the HAL when a tuning operation fails asynchronously
21     * following ITunerSession::tune(), ITunerSession::scan() or
22     * ITunerSession::step().
23     *
24     * This callback is only called when the step(), scan() or tune() command
25     * returned OK at first.
26     *
27     * @param result TIMEOUT in case of time out.
28     * @param selector A ProgramSelector structure passed from tune() call;
29     *                 empty for step() and scan().
30     */
31    oneway onTuneFailed(Result result, ProgramSelector selector);
32
33    /**
34     * Method called by the HAL when current program information (including
35     * metadata) is updated.
36     *
37     * This is also called when the radio tuned to the static (not a valid
38     * station), see the TUNED flag of ProgramInfoFlags.
39     *
40     * @param info Current program information.
41     */
42    oneway onCurrentProgramInfoChanged(ProgramInfo info);
43
44    /**
45     * A delta update of the program list, called whenever there's a change in
46     * the list.
47     *
48     * If there are frequent changes, HAL implementation must throttle the rate
49     * of the updates.
50     *
51     * There is a hard limit on binder transaction buffer, and the list must
52     * not exceed it. For large lists, HAL implementation must split them to
53     * multiple chunks, no larger than 500kiB each.
54     *
55     * @param chunk A chunk of the program list update.
56     */
57    oneway onProgramListUpdated(ProgramListChunk chunk);
58
59    /**
60     * Method called by the HAL when the antenna gets connected or disconnected.
61     *
62     * For a new tuner session, client must assume the antenna is connected.
63     * If it's not, then antennaStateChange must be called within
64     * Constants::ANTENNA_DISCONNECTED_TIMEOUT_MS to indicate that.
65     *
66     * @param connected True if the antenna is now connected, false otherwise.
67     */
68    oneway onAntennaStateChange(bool connected);
69
70    /**
71     * Generic callback for passing updates to vendor-specific parameter values.
72     * The framework does not interpret the parameters, they are passed
73     * in an opaque manner between a vendor application and HAL.
74     *
75     * It's up to the HAL implementation if and how to implement this callback,
76     * as long as it obeys the prefix rule. In particular, only selected keys
77     * may be notified this way. However, setParameters must not trigger
78     * this callback, while an internal event can change parameters
79     * asynchronously.
80     *
81     * @param parameters Vendor-specific key-value pairs,
82     *                   opaque to Android framework.
83     */
84    oneway onParametersUpdated(vec<VendorKeyValue> parameters);
85};
86