1/*
2 * Copyright (C) 2019 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.tv.tuner@1.0;
18
19import IFrontendCallback;
20import ILnb;
21
22/**
23 * A Tuner Frontend is used to tune to a frequency and lock signal.
24 *
25 * IFrontend provides a bit stream to the Tuner Demux interface.
26 */
27interface IFrontend {
28    /**
29     * Set the frontend callback.
30     *
31     * IFrontendCallback is used by the client to receive events from the Frontend.
32     * Only one callback per IFrontend instance is supported. The callback
33     * will be replaced if it's set again.
34     *
35     * @param callback Callback object to pass Frontend events to the system.
36     *        The previously registered callback must be replaced with this one.
37     *        It can be null.
38     * @return result Result status of the operation.
39     *         SUCCESS if successful,
40     *         INVALID_STATE if callback can't be set at current stage,
41     *         UNKNOWN_ERROR if callback setting failed for other reasons.
42     */
43    setCallback(IFrontendCallback callback) generates (Result result);
44
45    /**
46     * Tunes the frontend to using the settings given.
47     *
48     * This locks the frontend to a frequency by providing signal
49     * delivery information. If previous tuning isn't completed, this call MUST
50     * stop previous tuning, and start a new tuning.
51     * Tune is an async call, with LOCKED or NO_SIGNAL events sent via callback.
52     *
53     * @param settings Signal delivery information the frontend uses to
54     * search and lock the signal.
55     *
56     * @return result Result status of the operation.
57     *         SUCCESS if successful,
58     *         INVALID_STATE if tuning can't be applied at current stage,
59     *         UNKNOWN_ERROR if tuning failed for other reasons.
60     */
61    tune(FrontendSettings settings) generates (Result result);
62
63    /**
64     * Stops a previous tuning.
65     *
66     * If the method completes successfully the frontend is no longer tuned and no data
67     * will be sent to attached demuxes.
68     *
69     * @return result Result status of the operation.
70     *         SUCCESS if successfully stop tuning.
71     *         UNKNOWN_ERROR if failed for other reasons.
72     */
73    stopTune() generates (Result result);
74
75    /**
76     * Releases the Frontend instance
77     *
78     * Associated resources are released.  close may be called more than once.
79     * Calls to any other method after this will return an error
80     *
81     * @return result Result status of the operation.
82     *         SUCCESS if successful,
83     *         UNKNOWN_ERROR if failed for other reasons.
84     */
85    close() generates (Result result);
86
87    /**
88     * Scan the frontend to use the settings given.
89     *
90     * This uses the frontend to start a scan from signal delivery information.
91     * If previous scan isn't completed, this call MUST stop previous scan,
92     * and start a new scan.
93     * Scan is an async call, with FrontendScanMessage sent via callback.
94     *
95     * @param settings Signal delivery information which the frontend uses to
96     * scan the signal.
97     * @param type the type which the frontend uses to scan the signal.
98     *
99     * @return result Result status of the operation.
100     *         SUCCESS if successful,
101     *         INVALID_STATE if tuning can't be applied at current stage,
102     *         UNKNOWN_ERROR if tuning failed for other reasons.
103     */
104    scan(FrontendSettings settings, FrontendScanType type) generates (Result result);
105
106    /**
107     * Stops a previous scanning.
108     *
109     * If the method completes successfully, the frontend stop previous
110     * scanning.
111     *
112     * @return result Result status of the operation.
113     *         SUCCESS if successfully stop tuning.
114     *         UNKNOWN_ERROR if failed for other reasons.
115     */
116    stopScan() generates (Result result);
117
118    /**
119     * Gets the statuses of the frontend.
120     *
121     * This retrieve the statuses of the frontend for given status types.
122     *
123     * @param statusTypes an array of status type which the caller request.
124     *
125     * @return result Result status of the operation.
126     *         SUCCESS if successful,
127     *         INVALID_STATE if tuning can't be applied at current stage,
128     *         UNKNOWN_ERROR if tuning failed for other reasons.
129     * @return statuses an array of statuses which response the caller's
130     *         request.
131     */
132    getStatus(vec<FrontendStatusType> statusTypes)
133        generates (Result result, vec<FrontendStatus> statuses);
134
135    /**
136     * Sets Low-Noise Block downconverter (LNB) for satellite frontend.
137     *
138     * This assigns a hardware LNB resource to the satellite frontend. It can be
139     * called multiple times to update LNB assignment. The LNB resource must be
140     * released when the frontend is closed.
141     *
142     * @param lnbId the Id of assigned LNB resource.
143     *
144     * @return result Result status of the operation.
145     *         SUCCESS if successful,
146     *         INVALID_STATE if the frontend can't be set with a LNB, such as
147     *         cable frontend.
148     *         UNKNOWN_ERROR if failed for other reasons.
149     */
150    setLnb(LnbId lnbId) generates (Result result);
151
152    /**
153     * Enable or Disable Low Noise Amplifier (LNA).
154     *
155     * @param bEnable true if activate LNA module; false if deactivate LNA
156     *
157     * @return result Result status of the operation.
158     *         SUCCESS if successful,
159     *         INVALID_STATE if the frontend doesn't support LNA.
160     *         UNKNOWN_ERROR if failed for other reasons.
161     */
162    setLna(bool bEnable) generates (Result result);
163};
164