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
18import IAnnouncementListener;
19import ICloseHandle;
20import ITunerCallback;
21import ITunerSession;
22
23/**
24 * Represents a hardware broadcast radio module. A single module may contain
25 * multiple hardware tuners (i.e. with an additional background tuner), but the
26 * layers above the HAL see them as a single logical unit.
27 */
28interface IBroadcastRadio {
29    /**
30     * Returns module properties: a description of a module and its
31     * capabilities. This method must not fail.
32     *
33     * @return properties Module description.
34     */
35    getProperties() generates (Properties properties);
36
37    /**
38     * Fetches current or possible AM/FM region configuration.
39     *
40     * @param full If true, returns full hardware capabilities.
41     *             If false, returns current regional configuration.
42     * @return result OK in case of success.
43     *                NOT_SUPPORTED if the tuner doesn't support AM/FM.
44     * @return config Hardware capabilities (full=true) or
45     *                current configuration (full=false).
46     */
47    getAmFmRegionConfig(bool full)
48            generates (Result result, AmFmRegionConfig config);
49
50    /**
51     * Fetches current DAB region configuration.
52     *
53     * @return result OK in case of success.
54     *                NOT_SUPPORTED if the tuner doesn't support DAB.
55     * @return config Current configuration.
56     */
57    getDabRegionConfig() generates (Result result, vec<DabTableEntry> config);
58
59    /**
60     * Opens a new tuner session.
61     *
62     * There may be only one session active at a time. If the new session was
63     * requested when the old one was active, the old must be terminated
64     * (aggressive open).
65     *
66     * @param callback The callback interface.
67     * @return result OK in case of success.
68     * @return session The session interface.
69     */
70    openSession(ITunerCallback callback)
71        generates (Result result, ITunerSession session);
72
73    /**
74     * Fetch image from radio module cache.
75     *
76     * This is out-of-band transport mechanism for images carried with metadata.
77     * The metadata vector only passes the identifier, so the client may cache
78     * images or even not fetch them.
79     *
80     * The identifier may be any arbitrary number (i.e. sha256 prefix) selected
81     * by the vendor. It must be stable across sessions so the application may
82     * cache it.
83     *
84     * The data must be a valid PNG, JPEG, GIF or BMP file.
85     * Image data with an invalid format must be handled gracefully in the same
86     * way as a missing image.
87     *
88     * The image identifier may become invalid after some time from passing it
89     * with metadata struct (due to resource cleanup at the HAL implementation).
90     * However, it must remain valid for a currently tuned program at least
91     * until onCurrentProgramInfoChanged is called.
92     *
93     * There is still a race condition possible between
94     * onCurrentProgramInfoChanged callback and the HAL implementation eagerly
95     * clearing the cache (because the next onCurrentProgramInfoChanged came).
96     * In such case, client application may expect the new
97     * onCurrentProgramInfoChanged callback with updated image identifier.
98     *
99     * @param id Identifier of an image (value of Constants::INVALID_IMAGE is
100     *           reserved and must be treated as invalid image).
101     * @return image A binary blob with image data
102     *               or a zero-length vector if identifier doesn't exist.
103     */
104    getImage(uint32_t id) generates (vec<uint8_t> image);
105
106    /**
107     * Registers announcement listener.
108     *
109     * If there is at least one observer registered, HAL implementation must
110     * notify about announcements even if no sessions are active.
111     *
112     * If the observer dies, the HAL implementation must unregister observer
113     * automatically.
114     *
115     * @param enabled The list of announcement types to watch for.
116     * @param listener The listener interface.
117     * @return result OK in case of success.
118     *                NOT_SUPPORTED if the tuner doesn't support announcements.
119     * @return closeHandle A handle to unregister observer,
120     *                     nullptr if result was not OK.
121     */
122    registerAnnouncementListener(
123            vec<AnnouncementType> enabled,
124            IAnnouncementListener listener
125        ) generates (
126            Result result,
127            ICloseHandle closeHandle
128        );
129};
130