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 ITunerSession {
19    /**
20     * Tune to a specified program.
21     *
22     * Automatically cancels pending tune(), scan() or step().
23     * If the method returns OK, tuneFailed or currentProgramInfoChanged
24     * callback must be called.
25     *
26     * @param program Program to tune to.
27     * @return result OK if successfully started tuning.
28     *                NOT_SUPPORTED if the program selector doesn't contain any
29     *                supported identifier.
30     *                INVALID_ARGUMENTS if the program selector contains
31     *                identifiers in invalid format (i.e. out of range).
32     */
33    tune(ProgramSelector program) generates (Result result);
34
35    /**
36     * Tune (seek) to the next valid program on the "air".
37     *
38     * This might more naturally be called "seek" but for legacy reasons, the
39     * entry point remains "scan". This should not be confused with the actual
40     * scan operation (where the radio seeks through programs in a loop until
41     * user chooses to stay on one of them) nor background scan operation (that
42     * a tuner may do in order to locate all available programs.  This function
43     * is meant to advance to the next detected program and stay there.
44     *
45     * Automatically cancels pending tune(), scan() or step().
46     * If the method returns OK, tuneFailed or currentProgramInfoChanged
47     * callback must be called.
48     *
49     * The skipSubChannel parameter is used to skip digital radio subchannels:
50     *  - HD Radio SPS;
51     *  - DAB secondary service.
52     *
53     * As an implementation detail, the HAL has the option to perform an actual
54     * seek or select the next program from the list retrieved in the
55     * background, if one is not stale.
56     *
57     * @param directionUp True to change towards higher numeric values
58     *                    (frequency, channel number), false towards lower.
59     * @param skipSubChannel Don't tune to subchannels.
60     * @return result OK if the operation has successfully started.
61     */
62    scan(bool directionUp, bool skipSubChannel) generates (Result result);
63
64    /**
65     * Tune to the adjacent channel, which may not be occupied by any program.
66     *
67     * Automatically cancels pending tune(), scan() or step().
68     * If the method returns OK, tuneFailed or currentProgramInfoChanged
69     * callback must be called.
70     *
71     * @param directionUp True to change towards higher numeric values
72     *                    (frequency, channel number), false towards lower.
73     * @return result OK successfully started tuning.
74     *                NOT_SUPPORTED if tuning to an unoccupied channel is not
75     *                supported (i.e. for satellite radio).
76     */
77    step(bool directionUp) generates (Result result);
78
79    /**
80     * Cancel a pending tune(), scan() or step().
81     *
82     * If there is no such operation running, the call must be ignored.
83     */
84    cancel();
85
86    /**
87     * Applies a filter to the program list and starts sending program list
88     * updates over onProgramListUpdated callback.
89     *
90     * There may be only one updates stream active at the moment. Calling this
91     * method again must result in cancelling the previous update request.
92     *
93     * This call clears the program list on the client side, the HAL must send
94     * the whole list again.
95     *
96     * If the program list scanning hardware (i.e. background tuner) is
97     * unavailable at the moment, the call must succeed and start updates
98     * when it becomes available.
99     *
100     * @param filter Filter to apply on the fetched program list.
101     * @return result OK successfully started fetching list updates.
102     *                NOT_SUPPORTED program list scanning is not supported
103     *                by the hardware.
104     */
105    startProgramListUpdates(ProgramFilter filter) generates (Result result);
106
107    /**
108     * Stops sending program list updates.
109     */
110    stopProgramListUpdates();
111
112    /**
113     * Fetches the current setting of a given config flag.
114     *
115     * The success/failure result must be consistent with setConfigFlag.
116     *
117     * @param flag Flag to fetch.
118     * @return result OK successfully fetched the flag.
119     *                INVALID_STATE if the flag is not applicable right now.
120     *                NOT_SUPPORTED if the flag is not supported at all.
121     * @return value The current value of the flag, if result is OK.
122     */
123    isConfigFlagSet(ConfigFlag flag) generates (Result result, bool value);
124
125    /**
126     * Sets the config flag.
127     *
128     * The success/failure result must be consistent with isConfigFlagSet.
129     *
130     * @param flag Flag to set.
131     * @param value The new value of a given flag.
132     * @return result OK successfully set the flag.
133     *                INVALID_STATE if the flag is not applicable right now.
134     *                NOT_SUPPORTED if the flag is not supported at all.
135     */
136    setConfigFlag(ConfigFlag flag, bool value) generates (Result result);
137
138    /**
139     * Generic method for setting vendor-specific parameter values.
140     * The framework does not interpret the parameters, they are passed
141     * in an opaque manner between a vendor application and HAL.
142     *
143     * Framework does not make any assumptions on the keys or values, other than
144     * ones stated in VendorKeyValue documentation (a requirement of key
145     * prefixes).
146     *
147     * For each pair in the result vector, the key must be one of the keys
148     * contained in the input (possibly with wildcards expanded), and the value
149     * must be a vendor-specific result status (i.e. the string "OK" or an error
150     * code). The implementation may choose to return an empty vector, or only
151     * return a status for a subset of the provided inputs, at its discretion.
152     *
153     * Application and HAL must not use keys with unknown prefix. In particular,
154     * it must not place a key-value pair in results vector for unknown key from
155     * parameters vector - instead, an unknown key should simply be ignored.
156     * In other words, results vector may contain a subset of parameter keys
157     * (however, the framework doesn't enforce a strict subset - the only
158     * formal requirement is vendor domain prefix for keys).
159     *
160     * @param parameters Vendor-specific key-value pairs.
161     * @return results Operation completion status for parameters being set.
162     */
163    setParameters(vec<VendorKeyValue> parameters)
164        generates (vec<VendorKeyValue> results);
165
166    /**
167     * Generic method for retrieving vendor-specific parameter values.
168     * The framework does not interpret the parameters, they are passed
169     * in an opaque manner between a vendor application and HAL.
170     *
171     * Framework does not cache set/get requests, so it's allowed for
172     * getParameter to return a different value than previous setParameter call.
173     *
174     * The syntax and semantics of keys are up to the vendor (as long as prefix
175     * rules are obeyed). For instance, vendors may include some form of
176     * wildcard support. In such case, result vector may be of different size
177     * than requested keys vector. However, wildcards are not recognized by
178     * framework and they are passed as-is to the HAL implementation.
179     *
180     * Unknown keys must be ignored and not placed into results vector.
181     *
182     * @param keys Parameter keys to fetch.
183     * @return parameters Vendor-specific key-value pairs.
184     */
185    getParameters(vec<string> keys) generates (vec<VendorKeyValue> parameters);
186
187    /**
188     * Closes the session.
189     *
190     * The call must not fail and must only be issued once.
191     *
192     * After the close call is executed, no other calls to this interface
193     * are allowed.
194     */
195    close();
196};
197