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.radio@1.5;
18
19import @1.0::CdmaSmsMessage;
20import @1.2::DataRequestReason;
21import @1.4::IRadio;
22import @1.5::AccessNetwork;
23import @1.5::DataProfileInfo;
24import @1.5::IndicationFilter;
25import @1.5::LinkAddress;
26import @1.5::NetworkScanRequest;
27import @1.5::PersoSubstate;
28import @1.5::RadioAccessNetworks;
29import @1.5::RadioAccessSpecifier;
30import @1.5::SignalThresholdInfo;
31
32/**
33 * This interface is used by telephony and telecom to talk to cellular radio.
34 * All the functions have minimum one parameter:
35 * serial: which corresponds to serial no. of request. Serial numbers must only be memorized for the
36 * duration of a method call. If clients provide colliding serials (including passing the same
37 * serial to different methods), multiple responses (one for each method call) must still be served.
38 * setResponseFunctions must work with @1.5::IRadioResponse and @1.5::IRadioIndication.
39 */
40interface IRadio extends @1.4::IRadio {
41    /**
42     * Sets the signal strength reporting criteria.
43     *
44     * The resulting reporting rules are the AND of all the supplied criteria. For each RAN
45     * The hysteresisDb and thresholds apply to only the following measured quantities:
46     * -GERAN    - RSSI
47     * -CDMA2000 - RSSI
48     * -UTRAN    - RSCP
49     * -EUTRAN   - RSRP/RSRQ/RSSNR
50     * -NGRAN    - SSRSRP/SSRSRQ/SSSINR
51     *
52     * Note: Reporting criteria must be individually set for each RAN. For each RAN, if none of
53     * reporting criteria of any measurement is set enabled
54     * (see @1.5::SignalThresholdInfo.isEnabled), the reporting criteria for this RAN is
55     * implementation-defined. For each RAN, if any of reporting criteria of any measure is set
56     * enabled, the reporting criteria of the other measures in this RAN are set disabled
57     * (see @1.5::SignalThresholdInfo.isEnabled) until they are set enabled.
58     *
59     * Response callback is
60     * IRadioResponse.setSignalStrengthReportingCriteriaResponse_1_5()
61     *
62     * @param serial Serial number of request.
63     * @param signalThresholdInfo Signal threshold info including the threshold values,
64     *                            hysteresisDb, hysteresisMs and isEnabled.
65     *                            See @1.5::SignalThresholdInfo for details.
66     * @param accessNetwork The type of network for which to apply these thresholds.
67     */
68    oneway setSignalStrengthReportingCriteria_1_5(int32_t serial,
69            SignalThresholdInfo signalThresholdInfo, AccessNetwork accessNetwork);
70
71    /**
72     * Sets the link capacity reporting criteria.
73     *
74     * The resulting reporting criteria are the AND of all the supplied criteria.
75     *
76     * Note: Reporting criteria must be individually set for each RAN. If unset, reporting criteria
77     * for that RAN are implementation-defined.
78     *
79     * Response callback is IRadioResponse.setLinkCapacityReportingCriteriaResponse_1_5().
80     *
81     * @param serial Serial number of request.
82     * @param hysteresisMs A hysteresis time in milliseconds to prevent flapping. A value of 0
83     *     disables hysteresis.
84     * @param hysteresisDlKbps An interval in kbps defining the required magnitude change between DL
85     *     reports. hysteresisDlKbps must be smaller than the smallest threshold delta. A value of 0
86     *     disables hysteresis.
87     * @param hysteresisUlKbps An interval in kbps defining the required magnitude change between UL
88     *     reports. hysteresisUlKbps must be smaller than the smallest threshold delta. A value of 0
89     *     disables hysteresis.
90     * @param thresholdsDownlinkKbps A vector of trigger thresholds in kbps for downlink reports. A
91     *     vector size of 0 disables the use of DL thresholds for reporting.
92     * @param thresholdsUplinkKbps A vector of trigger thresholds in kbps for uplink reports. A
93     *     vector size of 0 disables the use of UL thresholds for reporting.
94     * @param accessNetwork The type of network for which to apply these thresholds.
95     */
96    oneway setLinkCapacityReportingCriteria_1_5(int32_t serial, int32_t hysteresisMs,
97            int32_t hysteresisDlKbps, int32_t hysteresisUlKbps, vec<int32_t> thresholdsDownlinkKbps,
98            vec<int32_t> thresholdsUplinkKbps, AccessNetwork accessNetwork);
99
100    /**
101     * Enable or disable UiccApplications on the SIM. If disabled:
102     *  - Modem will not register on any network.
103     *  - SIM must be PRESENT, and the IccId of the SIM must still be accessible.
104     *  - The corresponding modem stack is still functional, e.g. able to make emergency calls or
105     *    do network scan.
106     * By default if this API is not called, the uiccApplications must be enabled automatically.
107     * It must work for both single SIM and DSDS cases for UX consistency.
108     * The preference is per SIM, and must be remembered over power cycle, modem reboot, or SIM
109     * insertion / unplug.
110     *
111     * @param serial Serial number of request.
112     * @param enable true if to enable uiccApplications, false to disable.
113
114     * Response callback is IRadioResponse.enableUiccApplicationsResponse()
115     */
116    oneway enableUiccApplications(int32_t serial, bool enable);
117
118    /**
119     * Whether uiccApplications are enabled, or disabled.
120     *
121     * By default uiccApplications must be enabled, unless enableUiccApplications() with enable
122     * being false is called.
123     *
124     * @param serial Serial number of request.
125     *
126     * Response callback is IRadioResponse.areUiccApplicationsEnabledResponse()
127     */
128    oneway areUiccApplicationsEnabled(int32_t serial);
129
130    /**
131     * Specify which bands modem's background scan must act on.
132     * If specifyChannels is true, it only scans bands specified in specifiers.
133     * If specifyChannels is false, it scans all bands.
134     *
135     * For example, CBRS is only on LTE band 48. By specifying this band,
136     * modem saves more power.
137     *
138     * @param serial Serial number of request.
139     * @param specifyChannels whether to scan bands defined in specifiers.
140     * @param specifiers which bands to scan. Only used if specifyChannels is true.
141     *
142     * Response callback is IRadioResponse.setSystemSelectionChannelsResponse()
143     */
144    oneway setSystemSelectionChannels_1_5(int32_t serial, bool specifyChannels,
145            vec<RadioAccessSpecifier> specifiers);
146
147    /**
148     * Starts a network scan.
149     *
150     * @param serial Serial number of request.
151     * @param request Defines the radio networks/bands/channels which need to be scanned.
152     *
153     * Same API as @1.4::IRadio.startNetworkScan_1_4, except using the
154     * 1.5 NetworkScanRequest as the input param.
155     */
156    oneway startNetworkScan_1_5(int32_t serial, NetworkScanRequest request);
157
158    /**
159     * Setup a packet data connection. If DataCallResponse.status returns DataCallFailCause:NONE,
160     * the data connection must be added to data calls and a unsolDataCallListChanged() must be
161     * sent. The call remains until removed by subsequent unsolDataCallIstChanged(). It may be
162     * lost due to many factors, including deactivateDataCall() being issued, the radio powered
163     * off, reception lost or even transient factors like congestion. This data call list is
164     * returned by getDataCallList() and dataCallListChanged().
165     *
166     * The Radio is expected to:
167     *   - Create one data call context.
168     *   - Create and configure a dedicated interface for the context.
169     *   - The interface must be point to point.
170     *   - The interface is configured with one or more addresses and is capable of sending and
171     *     receiving packets. The prefix length of the addresses must be /32 for IPv4 and /128
172     *     for IPv6.
173     *   - Must not modify routing configuration related to this interface; routing management is
174     *     exclusively within the purview of the Android OS.
175     *   - Support simultaneous data call contexts up to DataRegStateResult.maxDataCalls specified
176     *     in the response of getDataRegistrationState.
177     *
178     * @param serial Serial number of request.
179     * @param accessNetwork The access network to setup the data call. If the data connection cannot
180     *     be established on the specified access network, the setup request must be failed.
181     * @param dataProfileInfo Data profile info.
182     * @param roamingAllowed Indicates whether or not data roaming is allowed by the user.
183     * @param reason The request reason. Must be DataRequestReason.NORMAL or
184     *     DataRequestReason.HANDOVER.
185     * @param addresses If the reason is DataRequestReason.HANDOVER, this indicates the list of link
186     *     addresses of the existing data connection. This parameter must be ignored unless reason
187     *     is DataRequestReason.HANDOVER.
188     * @param dnses If the reason is DataRequestReason.HANDOVER, this indicates the list of DNS
189     *     addresses of the existing data connection. The format is defined in RFC-4291 section
190     *     2.2. For example, "192.0.1.3" or "2001:db8::1". This parameter must be ignored unless
191     *     reason is DataRequestReason.HANDOVER.
192     *
193     * Response function is IRadioResponse.setupDataCallResponse_1_5()
194     *
195     * Note this API is the same as the 1.4 version except using the
196     * 1.5 AccessNetwork, DataProfileInto, and LinkAddress as the input param.
197     */
198    oneway setupDataCall_1_5(int32_t serial, AccessNetwork accessNetwork,
199            DataProfileInfo dataProfileInfo, bool roamingAllowed,
200            DataRequestReason reason, vec<LinkAddress> addresses, vec<string> dnses);
201
202    /**
203     * Set an APN to initial attach network.
204     *
205     * @param serial Serial number of request.
206     * @param dataProfileInfo data profile containing APN settings
207     *
208     * Response callback is IRadioResponse.setInitialAttachApnResponse_1_5()
209     *
210     * Note this API is the same as the 1.4 version except using the 1.5 DataProfileInfo
211     * as the input param.
212     */
213    oneway setInitialAttachApn_1_5(int32_t serial, DataProfileInfo dataProfileInfo);
214
215    /**
216     * Send data profiles of the current carrier to the modem.
217     *
218     * @param serial Serial number of request.
219     * @param profiles Array of DataProfileInfo to set.
220     *
221     * Response callback is IRadioResponse.setDataProfileResponse_1_5()
222     *
223     * Note this API is the same as the 1.4 version except using the 1.5 DataProfileInfo
224     * as the input param.
225     */
226    oneway setDataProfile_1_5(int32_t serial, vec<DataProfileInfo> profiles);
227
228    /**
229     * Toggle radio on and off (for "airplane" mode)
230     * If the radio is turned off/on the radio modem subsystem
231     * is expected return to an initialized state. For instance,
232     * any voice and data calls must be terminated and all associated
233     * lists emptied.
234     *
235     * When setting radio power on to exit from airplane mode to place an emergency call on this
236     * logical modem, powerOn, forEmergencyCall and preferredForEmergencyCall must be true. In
237     * this case, this modem is optimized to scan only emergency call bands, until:
238     * 1) Emergency call is completed; or
239     * 2) Another setRadioPower_1_5 is issued with forEmergencyCall being false or
240     * preferredForEmergencyCall being false; or
241     * 3) Timeout after 30 seconds if dial or emergencyDial is not called.
242     * Once one of these conditions is reached, the modem should move into normal operation.
243     *
244     * @param serial Serial number of request.
245     * @param powerOn To turn on radio -> on = true, to turn off radio -> on = false.
246     * @param forEmergencyCall To indication to radio if this request is due to emergency call.
247     *      No effect if powerOn is false.
248     * @param preferredForEmergencyCall indicate whether the following emergency call will be sent
249     *      on this modem or not. No effect if forEmergencyCall is false, or powerOn is false.
250     *
251     * Response callback is IRadioConfigResponse. setRadioPowerResponse_1_5.
252     */
253    oneway setRadioPower_1_5(int32_t serial, bool powerOn, bool forEmergencyCall,
254            bool preferredForEmergencyCall);
255
256    /**
257     * Sets the indication filter.
258     *
259     * Prevents the reporting of specified unsolicited indications from the radio. This is used
260     * for power saving in instances when those indications are not needed. If unset, defaults to
261     * @1.5::IndicationFilter:ALL.
262     *
263     * @param serial Serial number of request.
264     * @param indicationFilter 32-bit bitmap of IndicationFilter. Bits set to 1 indicate the
265     *     indications are enabled. See @1.5::IndicationFilter for the definition of each bit.
266     *
267     * Response callback is IRadioResponse.setIndicationFilterResponse()
268     */
269    oneway setIndicationFilter_1_5(int32_t serial, bitfield<IndicationFilter> indicationFilter);
270
271    /**
272     * Get all the barring info for the current camped cell applicable to the current user.
273     *
274     * @param serial Serial number of request.
275     *
276     * Response callback is IRadioResponse.getBarringInfoResponse()
277     */
278    oneway getBarringInfo(int32_t serial);
279
280    /**
281     * Request current voice registration state.
282     *
283     * @param serial Serial number of request.
284     *
285     * Response function is IRadioResponse.getVoiceRegistrationStateResponse_1_5()
286     */
287    oneway getVoiceRegistrationState_1_5(int32_t serial);
288
289    /**
290     * Request current data registration state.
291     *
292     * @param serial Serial number of request.
293     *
294     * Response function is IRadioResponse.getDataRegistrationStateResponse_1_5()
295     */
296    oneway getDataRegistrationState_1_5(int32_t serial);
297
298    /*
299     * Manually select a specified network.
300     * This request must not respond until the new operator is selected and registered.
301     * Per TS 23.122, the RAN is just the initial suggested value.
302     * If registration fails, the RAN is not available afterwards, or the RAN is not within
303     * the network types specified by IRadio::setPreferredNetworkTypeBitmap, then the modem
304     * will need to select the next best RAN for network registration.
305     *
306     * @param serial Serial number of request.
307     * @param operatorNumeric String specifying MCCMNC of network to select (eg "310170").
308     * @param ran Initial suggested radio access network type. If value is UNKNOWN, the modem
309     *     will select the next best RAN for network registration.
310     *
311     * Response function is IRadioResponse.setNetworkSelectionModeManualResponse_1_5()
312     */
313    oneway setNetworkSelectionModeManual_1_5(int32_t serial, string operatorNumeric,
314            RadioAccessNetworks ran);
315
316    /**
317     * Send an SMS message. Identical to sendCdmaSms,
318     * except that more messages are expected to be sent soon.
319     *
320     * @param serial Serial number of request.
321     * @param sms Cdma Sms to be sent described by CdmaSmsMessage in types.hal
322     *
323     * Response callback is IRadioResponse.sendCdmaSMSExpectMoreResponse()
324     */
325    oneway sendCdmaSmsExpectMore(int32_t serial, CdmaSmsMessage sms);
326
327    /**
328     * Request that deactivates one category of device personalization. Device personalization
329     * generally binds the device so it can only be used on one carrier or even one carrier subnet
330     * (See TS 22.022). When the user has gained the rights to unbind the device (at the end of a
331     * contract period or other event), the controlKey will be delivered to either the user for
332     * manual entry or to a carrier app on the device for automatic entry.
333     *
334     * @param serial Serial number of request.
335     * @param persoType SIM personalization type.
336     * @param controlKey the unlock code for removing persoType personalization from this device
337     *
338     * Response function is IRadioResponse.supplySimDepersonalizationResponse()
339     */
340    oneway supplySimDepersonalization(int32_t serial, PersoSubstate persoType, string controlKey);
341};
342