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.radio@1.2;
18
19import @1.1::IRadio;
20import @1.1::RadioAccessNetworks;
21import @1.0::DataProfileInfo;
22import @1.0::RadioTechnology;
23
24/**
25 * This interface is used by telephony and telecom to talk to cellular radio.
26 * All the functions have minimum one parameter:
27 * serial: which corresponds to serial no. of request. Serial numbers must only be memorized for the
28 * duration of a method call. If clients provide colliding serials (including passing the same
29 * serial to different methods), multiple responses (one for each method call) must still be served.
30 * setResponseFunctions must work with @1.1::IRadioResponse and @1.1::IRadioIndication.
31 */
32interface IRadio extends @1.1::IRadio {
33
34    /**
35     * Starts a network scan
36     *
37     * @param serial Serial number of request.
38     * @param request Defines the radio networks/bands/channels which need to be scanned.
39     *
40     * Response function is IRadioResponse.startNetworkScanResponse() which may return
41     * RadioError:REQUEST_NOT_SUPPORTED if @1.4::IRadio or higher is supported.
42     *
43     * DEPRECATED in @1.4 or higher, use @1.4::IRadio.startNetworkScan_1_4() instead.
44     */
45    oneway startNetworkScan_1_2(int32_t serial, NetworkScanRequest request);
46
47    /**
48     * Sets the indication filter.
49     *
50     * Prevents the reporting of specified unsolicited indications from the radio. This is used
51     * for power saving in instances when those indications are not needed. If unset, defaults to
52     * @1.2::IndicationFilter:ALL.
53     *
54     * @param serial Serial number of request.
55     * @param indicationFilter 32-bit bitmap of IndicationFilter. Bits set to 1 indicate the
56     *     indications are enabled. See @1.2::IndicationFilter for the definition of each bit.
57     *
58     * Response callback is IRadioResponse.setIndicationFilterResponse()
59     */
60    oneway setIndicationFilter_1_2(int32_t serial, bitfield<IndicationFilter> indicationFilter);
61
62    /**
63     * Sets the signal strength reporting criteria.
64     *
65     * The resulting reporting rules are the AND of all the supplied criteria. For each RAN
66     * The thresholdsDbm and hysteresisDb apply to only the following measured quantities:
67     * -GERAN    - RSSI
68     * -CDMA2000 - RSSI
69     * -UTRAN    - RSCP
70     * -EUTRAN   - RSRP
71     *
72     * Note: Reporting criteria must be individually set for each RAN. For any unset reporting
73     * criteria, the value is implementation-defined.
74     *
75     * Note: As this mechanism generally only constrains reports based on one measured quantity per
76     * RAN, if multiple measured quantities must be used to trigger a report for a given RAN, the
77     * only valid field may be hysteresisMs: hysteresisDb and thresholdsDbm must be set to zero and
78     * length zero respectively. If either hysteresisDb or thresholdsDbm is set, then reports shall
79     * only be triggered by the respective measured quantity, subject to the applied constraints.
80     *
81     * Response callback is IRadioResponse.setSignalStrengthReportingCriteriaResponse()
82     *
83     * @param serial Serial number of request.
84     * @param hysteresisMs A hysteresis time in milliseconds to prevent flapping. A value of 0
85     *     disables hysteresis.
86     * @param hysteresisDb An interval in dB defining the required magnitude change between reports.
87     *     hysteresisDb must be smaller than the smallest threshold delta. An interval value of 0
88     *     disables hysteresis.
89     * @param thresholdsDbm A vector of trigger thresholds in dBm. A vector size of 0 disables the
90     *     use of thresholds for reporting.
91     * @param accessNetwork The type of network for which to apply these thresholds.
92     */
93    oneway setSignalStrengthReportingCriteria(int32_t serial, int32_t hysteresisMs,
94            int32_t hysteresisDb, vec<int32_t> thresholdsDbm, AccessNetwork accessNetwork);
95
96    /**
97     * Sets the link capacity reporting criteria.
98     *
99     * The resulting reporting criteria are the AND of all the supplied criteria.
100     *
101     * Note: Reporting criteria must be individually set for each RAN. If unset, reporting criteria
102     * for that RAN are implementation-defined.
103     *
104     * Response callback is IRadioResponse.setLinkCapacityReportingCriteriaResponse().
105     *
106     * @param serial Serial number of request.
107     * @param hysteresisMs A hysteresis time in milliseconds to prevent flapping. A value of 0
108     *     disables hysteresis.
109     * @param hysteresisDlKbps An interval in kbps defining the required magnitude change between DL
110     *     reports. hysteresisDlKbps must be smaller than the smallest threshold delta. A value of 0
111     *     disables hysteresis.
112     * @param hysteresisUlKbps An interval in kbps defining the required magnitude change between UL
113     *     reports. hysteresisUlKbps must be smaller than the smallest threshold delta. A value of 0
114     *     disables hysteresis.
115     * @param thresholdsDownlinkKbps A vector of trigger thresholds in kbps for downlink reports. A
116     *     vector size of 0 disables the use of DL thresholds for reporting.
117     * @param thresholdsUplinkKbps A vector of trigger thresholds in kbps for uplink reports. A
118     *     vector size of 0 disables the use of UL thresholds for reporting.
119     * @param accessNetwork The type of network for which to apply these thresholds.
120     */
121    oneway setLinkCapacityReportingCriteria(int32_t serial, int32_t hysteresisMs,
122            int32_t hysteresisDlKbps, int32_t hysteresisUlKbps, vec<int32_t> thresholdsDownlinkKbps,
123            vec<int32_t> thresholdsUplinkKbps, AccessNetwork accessNetwork);
124
125    /**
126     * Setup a packet data connection. If DataCallResponse.status returns DataCallFailCause:NONE,
127     * the data connection must be added to data calls and a unsolDataCallListChanged() must be
128     * sent. The call remains until removed by subsequent unsolDataCallIstChanged(). It may be
129     * lost due to many factors, including deactivateDataCall() being issued, the radio powered
130     * off, reception lost or even transient factors like congestion. This data call list is
131     * returned by getDataCallList() and dataCallListChanged().
132     *
133     * The Radio is expected to:
134     *   - Create one data call context.
135     *   - Create and configure a dedicated interface for the context.
136     *   - The interface must be point to point.
137     *   - The interface is configured with one or more addresses and is capable of sending and
138     *     receiving packets. The prefix length of the addresses must be /32 for IPv4 and /128
139     *     for IPv6.
140     *   - Must not modify routing configuration related to this interface; routing management is
141     *     exclusively within the purview of the Android OS.
142     *   - Support simultaneous data call contexts up to DataRegStateResult.maxDataCalls specified
143     *     in the response of getDataRegistrationState.
144     *
145     * @param serial Serial number of request.
146     * @param accessNetwork The access network to setup the data call. If the data connection cannot
147     *     be established on the specified access network, the setup request must be failed.
148     * @param dataProfileInfo Data profile info.
149     * @param modemCognitive Indicates that the requested profile has previously been provided via
150     *     setDataProfile().
151     * @param roamingAllowed Indicates whether or not data roaming is allowed by the user.
152     * @param isRoaming Indicates whether or not the framework has requested this setupDataCall for
153     *     a roaming network. The 'protocol' parameter in the old RIL API must be filled
154     *     accordingly based on the roaming condition. Note this is for backward compatibility with
155     *     the old radio modem. The modem must not use this param for any other reason.
156     * @param reason The request reason. Must be DataRequestReason.NORMAL or
157     *     DataRequestReason.HANDOVER.
158     * @param addresses If the reason is DataRequestReason.HANDOVER, this indicates the list of link
159     *     addresses of the existing data connection. The format is IP address with optional "/"
160     *     prefix length (The format is defined in RFC-4291 section 2.3). For example, "192.0.1.3",
161     *     "192.0.1.11/16", or "2001:db8::1/64". Typically one IPv4 or one IPv6 or one of each. If
162     *     the prefix length is absent, then the addresses are assumed to be point to point with
163     *     IPv4 with prefix length 32 or IPv6 with prefix length 128. This parameter must be ignored
164     *     unless reason is DataRequestReason.HANDOVER.
165     * @param dnses If the reason is DataRequestReason.HANDOVER, this indicates the list of DNS
166     *     addresses of the existing data connection. The format is defined in RFC-4291 section
167     *     2.2. For example, "192.0.1.3" or "2001:db8::1". This parameter must be ignored unless
168     *     reason is DataRequestReason.HANDOVER.
169     *
170     * Response function is IRadioResponse.setupDataCallResponse()
171     */
172    oneway setupDataCall_1_2(int32_t serial, AccessNetwork accessNetwork,
173            DataProfileInfo dataProfileInfo, bool modemCognitive, bool roamingAllowed,
174            bool isRoaming, DataRequestReason reason, vec<string> addresses, vec<string> dnses);
175
176    /**
177     * Deactivate packet data connection and remove from the data call list. An
178     * unsolDataCallListChanged() must be sent when data connection is deactivated.
179     *
180     * @param serial Serial number of request.
181     * @param cid Data call id.
182     * @param reason The request reason. Must be normal, handover, or shutdown.
183     *
184     * Response function is IRadioResponse.deactivateDataCallResponse()
185     */
186    oneway deactivateDataCall_1_2(int32_t serial, int32_t cid, DataRequestReason reason);
187};
188