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::ITuner;
20
21interface ITuner extends @1.0::ITuner {
22
23    /**
24     * Retrieve current station information.
25     * @return result OK if scan successfully started
26     *                NOT_INITIALIZED if another error occurs
27     * @return info Current program information.
28     */
29    getProgramInformation_1_1() generates (Result result, ProgramInfo info);
30
31    /**
32     * Initiates a background scan to update internally cached program list.
33     *
34     * HAL client may not need to initiate the scan explicitly with this call,
35     * ie. HAL implementation MAY perform the scan on boot. It's a common
36     * practice in devices with two physical tuners with background scanning.
37     *
38     * Device must call backgroundScanComplete if the result is OK, even if the
39     * scan fails later (it must pass proper result through the callback).
40     * Otherwise, backgroundScanComplete must not be called as a result of this
41     * certain attempt. It may still be called as a response to another call to
42     * startBackgroundScan, former or latter.
43     *
44     * Device may utilize an already running (but not finished) scan for
45     * subsequent calls to startBackgroundScan, issuing a single
46     * backgroundScanComplete callback.
47     *
48     * @return result OK if the scan was properly scheduled (this does not mean
49     *                it successfully finished).
50     *                TEMPORARILY_UNAVAILABLE if the background scan is
51     *                temporarily unavailable, ie. due to ongoing foreground
52     *                playback in single-tuner device.
53     *                NOT_INITIALIZED other error, ie. HW failure.
54     */
55    startBackgroundScan() generates (ProgramListResult result);
56
57    /**
58     * Retrieve station list.
59     *
60     * This call does not trigger actual scan, but operates on the list cached
61     * internally at the driver level.
62     *
63     * @param filter vendor-specific filter for the stations to be retrieved.
64     *               An empty string MUST result in full list.
65     *               Client application MUST verify vendor/product name
66     *               before setting this parameter to anything else.
67     * @return result OK if the list was successfully retrieved.
68     *                NOT_READY if the scan is in progress.
69     *                NOT_STARTED if the scan has not been started, client may
70     *                call startBackgroundScan to fix this.
71     *                NOT_INITIALIZED if any other error occurs.
72     * @return programList List of stations available for user.
73     */
74    getProgramList(string filter)
75        generates (ProgramListResult result, vec<ProgramInfo> programList);
76
77};
78