1/*
2 * Copyright (C) 2017 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.1;
18
19import @1.0::ITunerCallback;
20
21/**
22 * Some methods of @1.1::ITunerCallback are updated versions of those from
23 * @1.0:ITunerCallback. All 1.1 HAL implementations must call both
24 * (eg. tuneComplete and tuneComplete_1_1), while 1.1 clients may ignore 1.0
25 * ones, to avoid receiving a callback twice.
26 */
27interface ITunerCallback extends @1.0::ITunerCallback {
28    /**
29     * Method called by the HAL when a tuning operation completes
30     * following a step(), scan() or tune() command.
31     *
32     * This callback supersedes V1_0::tuneComplete.
33     * The 1.0 callback must not be called when HAL implementation detects
34     * 1.1 client (by casting V1_0::ITunerCallback to V1_1::ITunerCallback).
35     *
36     * In case of success, currentProgramInfoChanged must be called too.
37     * It means the success case may (or may not) be handled by the client in
38     * currentProgramInfoChanged, instead of here.
39     *
40     * @param result OK if tune succeeded or TIMEOUT in case of time out.
41     * @param selector A ProgramSelector structure describing the tuned station.
42     */
43    oneway tuneComplete_1_1(Result result, ProgramSelector selector);
44
45    /**
46     * Called by the HAL when background scan feature becomes available or not.
47     *
48     * @param isAvailable true, if the tuner turned temporarily background-
49     *                    capable, false in the other case.
50     */
51    oneway backgroundScanAvailable(bool isAvailable);
52
53    /**
54     * Called by the HAL when background scan initiated by startBackgroundScan
55     * finishes. If the list was changed, programListChanged must be called too.
56     * @param result OK if the scan succeeded, client may retrieve the actual
57     *               list with ITuner::getProgramList.
58     *               UNAVAILABLE if the scan was interrupted due to
59     *               hardware becoming temporarily unavailable.
60     *               NOT_INITIALIZED other error, ie. HW failure.
61     */
62    oneway backgroundScanComplete(ProgramListResult result);
63
64    /**
65     * Called each time the internally cached program list changes. HAL may not
66     * call it immediately, ie. it may wait for a short time to accumulate
67     * multiple list change notifications into a single event.
68     *
69     * This callback is only for notifying about insertions and deletions,
70     * not about metadata changes.
71     *
72     * It may be triggered either by an explicitly issued background scan,
73     * or a scan issued by the device internally.
74     *
75     * Client may retrieve the actual list with ITuner::getProgramList.
76     */
77    oneway programListChanged();
78
79    /**
80     * Method called by the HAL when current program information (including
81     * metadata) is updated.
82     *
83     * Client may retrieve the actual program info with
84     * ITuner::getProgramInformation_1_1.
85     *
86     * This may be called together with tuneComplete_1_1 or afSwitch_1_1.
87     *
88     * This callback supersedes V1_0::newMetadata and V1_0::afSwitch;
89     * partly V1_0::tuneComplete.
90     * 1.0 callbacks must not be called when HAL implementation detects
91     * 1.1 client (by casting V1_0::ITunerCallback to V1_1::ITunerCallback).
92     *
93     * @param info current program information
94     */
95    oneway currentProgramInfoChanged(ProgramInfo info);
96};
97