1/*
2 * Copyright (C) 2018 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.4;
18
19import @1.0::Dial;
20import @1.2::DataRequestReason;
21import @1.2::NetworkScanRequest;
22import @1.3::IRadio;
23import @1.4::AccessNetwork;
24import @1.4::CarrierRestrictionsWithPriority;
25import @1.4::DataProfileInfo;
26import @1.4::EmergencyCallRouting;
27import @1.4::EmergencyServiceCategory;
28import @1.4::RadioAccessFamily;
29import @1.4::SimLockMultiSimPolicy;
30
31/**
32 * This interface is used by telephony and telecom to talk to cellular radio.
33 * All the functions have minimum one parameter:
34 * serial: which corresponds to serial no. of request. Serial numbers must only be memorized for the
35 * duration of a method call. If clients provide colliding serials (including passing the same
36 * serial to different methods), multiple responses (one for each method call) must still be served.
37 * setResponseFunctions must work with @1.1::IRadioResponse and @1.1::IRadioIndication.
38 */
39interface IRadio extends @1.3::IRadio {
40    /**
41     * Setup a packet data connection. If DataCallResponse.status returns DataCallFailCause:NONE,
42     * the data connection must be added to data calls and a unsolDataCallListChanged() must be
43     * sent. The call remains until removed by subsequent unsolDataCallIstChanged(). It may be
44     * lost due to many factors, including deactivateDataCall() being issued, the radio powered
45     * off, reception lost or even transient factors like congestion. This data call list is
46     * returned by getDataCallList() and dataCallListChanged().
47     *
48     * The Radio is expected to:
49     *   - Create one data call context.
50     *   - Create and configure a dedicated interface for the context.
51     *   - The interface must be point to point.
52     *   - The interface is configured with one or more addresses and is capable of sending and
53     *     receiving packets. The prefix length of the addresses must be /32 for IPv4 and /128
54     *     for IPv6.
55     *   - Must not modify routing configuration related to this interface; routing management is
56     *     exclusively within the purview of the Android OS.
57     *   - Support simultaneous data call contexts up to DataRegStateResult.maxDataCalls specified
58     *     in the response of getDataRegistrationState.
59     *
60     * @param serial Serial number of request.
61     * @param accessNetwork The access network to setup the data call. If the data connection cannot
62     *     be established on the specified access network, the setup request must be failed.
63     * @param dataProfileInfo Data profile info.
64     * @param roamingAllowed Indicates whether or not data roaming is allowed by the user.
65     * @param reason The request reason. Must be DataRequestReason.NORMAL or
66     *     DataRequestReason.HANDOVER.
67     * @param addresses If the reason is DataRequestReason.HANDOVER, this indicates the list of link
68     *     addresses of the existing data connection. The format is IP address with optional "/"
69     *     prefix length (The format is defined in RFC-4291 section 2.3). For example, "192.0.1.3",
70     *     "192.0.1.11/16", or "2001:db8::1/64". Typically one IPv4 or one IPv6 or one of each. If
71     *     the prefix length is absent, then the addresses are assumed to be point to point with
72     *     IPv4 with prefix length 32 or IPv6 with prefix length 128. This parameter must be ignored
73     *     unless reason is DataRequestReason.HANDOVER.
74     * @param dnses If the reason is DataRequestReason.HANDOVER, this indicates the list of DNS
75     *     addresses of the existing data connection. The format is defined in RFC-4291 section
76     *     2.2. For example, "192.0.1.3" or "2001:db8::1". This parameter must be ignored unless
77     *     reason is DataRequestReason.HANDOVER.
78     *
79     * Response function is IRadioResponse.setupDataCallResponse()
80     *
81     * Note this API is same as 1.2 version except using the 1.4 AccessNetwork as the input param.
82     */
83    oneway setupDataCall_1_4(int32_t serial, AccessNetwork accessNetwork,
84            DataProfileInfo dataProfileInfo, bool roamingAllowed,
85            DataRequestReason reason, vec<string> addresses, vec<string> dnses);
86
87    /**
88     * Set an apn to initial attach network
89     *
90     * @param serial Serial number of request.
91     * @param dataProfileInfo data profile containing APN settings
92     *
93     * Response callback is IRadioResponse.setInitialAttachApnResponse()
94     */
95    oneway setInitialAttachApn_1_4(int32_t serial, DataProfileInfo dataProfileInfo);
96
97    /**
98     * Send data profiles of the current carrier to the modem.
99     *
100     * @param serial Serial number of request.
101     * @param profiles Array of DataProfile to set.
102     *
103     * Response callback is IRadioResponse.setDataProfileResponse()
104     */
105    oneway setDataProfile_1_4(int32_t serial, vec<DataProfileInfo> profiles);
106
107    /**
108     * Initiate emergency voice call, with zero or more emergency service category(s), zero or
109     * more emergency Uniform Resource Names (URN), and routing information for handling the call.
110     * Android uses this request to make its emergency call instead of using @1.0::IRadio.dial
111     * if the 'address' in the 'dialInfo' field is identified as an emergency number by Android.
112     *
113     * In multi-sim scenario, if the emergency number is from a specific subscription, this radio
114     * request is sent through the IRadio service that serves the subscription, no matter of the
115     * PUK/PIN state of the subscription and the service state of the radio.
116     *
117     * Some countries or carriers require some emergency numbers that must be handled with normal
118     * call routing if possible or emergency routing. 1) if the 'routing' field is specified as
119     * @1.4::EmergencyNumberRouting#NORMAL, the implementation must try the full radio service to
120     * use normal call routing to handle the call; if service cannot support normal routing, the
121     * implementation must use emergency routing to handle the call. 2) if 'routing' is specified
122     * as @1.4::EmergencyNumberRouting#EMERGENCY, the implementation must use emergency routing to
123     * handle the call. 3) if 'routing' is specified as @1.4::EmergencyNumberRouting#UNKNOWN,
124     * Android does not know how to handle the call.
125     *
126     * If the dialed emergency number does not have a specified emergency service category, the
127     * 'categories' field is set to @1.4::EmergencyServiceCategory#UNSPECIFIED; if the dialed
128     * emergency number does not have specified emergency Uniform Resource Names, the 'urns' field
129     * is set to an empty list. If the underlying technology used to request emergency services
130     * does not support the emergency service category or emergency uniform resource names, the
131     * field 'categories' or 'urns' may be ignored.
132     *
133     * In the scenarios that the 'address' in the 'dialInfo' field has other functions besides the
134     * emergency number function, if the 'hasKnownUserIntentEmergency' field is true, the user's
135     * intent for this dial request is emergency call, and the modem must treat this as an actual
136     * emergency dial; if the 'hasKnownUserIntentEmergency' field is false, Android does not know
137     * user's intent for this call.
138     *
139     * If 'isTesting' is true, this request is for testing purpose, and must not be sent to a real
140     * emergency service; otherwise it's for a real emergency call request.
141     *
142     * Reference: 3gpp 22.101, Section 10 - Emergency Calls;
143     *            3gpp 23.167, Section 6 - Functional description;
144     *            3gpp 24.503, Section 5.1.6.8.1 - General;
145     *            RFC 5031
146     *
147     * @param serial Serial number of request.
148     * @param dialInfo the same @1.0::Dial information used by @1.0::IRadio.dial.
149     * @param categories bitfield<@1.4::EmergencyServiceCategory> the Emergency Service Category(s)
150     *     of the call.
151     * @param urns the emergency Uniform Resource Names (URN)
152     * @param routing @1.4::EmergencyCallRouting the emergency call routing information.
153     * @param hasKnownUserIntentEmergency Flag indicating if user's intent for the emergency call
154     *     is known.
155     * @param isTesting Flag indicating if this request is for testing purpose.
156     *
157     * Response function is IRadioResponse.emergencyDialResponse()
158     */
159    oneway emergencyDial(int32_t serial, Dial dialInfo,
160            bitfield<EmergencyServiceCategory> categories, vec<string> urns,
161            EmergencyCallRouting routing, bool hasKnownUserIntentEmergency, bool isTesting);
162
163    /**
164     * Starts a network scan
165     *
166     * @param serial Serial number of request.
167     * @param request Defines the radio networks/bands/channels which need to be scanned.
168     *
169     * Same API as @1.2::IRadio.startNetworkScan_1_2, except using the
170     * @1.4::IRadioResponse.startNetworkScanResponse_1_4 as the response.
171     */
172    oneway startNetworkScan_1_4(int32_t serial, NetworkScanRequest request);
173
174    /**
175     * Query the preferred network type bitmap.
176     *
177     * @param serial Serial number of request.
178     *
179     * Response callback is IRadioResponse.getPreferredNetworkTypeBitmapResponse()
180     */
181    oneway getPreferredNetworkTypeBitmap(int32_t serial);
182
183    /**
184     * Requests to set the preferred network type for searching and registering.
185     *
186     * @param serial Serial number of request.
187     * @param networkTypeBitmap a 32-bit bitmap of RadioAccessFamily.
188     *
189     * Response callback is IRadioResponse.setPreferredNetworkTypeBitmapResponse()
190     */
191    oneway setPreferredNetworkTypeBitmap(
192            int32_t serial, bitfield<RadioAccessFamily> networkTypeBitmap);
193
194    /**
195     * Set carrier restrictions. Expected modem behavior:
196     *  If never receives this command:
197     *  - Must allow all carriers
198     *  Receives this command:
199     *  - Only allow carriers specified in carriers. The restriction persists across power cycles
200     *    and FDR. If a present SIM is allowed, modem must not reload the SIM. If a present SIM is
201     *    *not* allowed, modem must detach from the registered network and only keep emergency
202     *    service, and notify Android SIM refresh reset with new SIM state being
203     *    CardState:RESTRICTED. Emergency service must be enabled.
204     *
205     * @param serial Serial number of request.
206     * @param carriers CarrierRestrictionsWithPriority consisting allowed and excluded carriers
207     *        as defined in types.hal
208     * @param multiSimPolicy Policy to be used for devices with multiple SIMs.
209     *
210     * Response callback is IRadioResponse.setAllowedCarriersResponse_1_4()
211     */
212    oneway setAllowedCarriers_1_4(int32_t serial, CarrierRestrictionsWithPriority carriers,
213            SimLockMultiSimPolicy multiSimPolicy);
214
215    /**
216     * Get carrier restrictions.
217     *
218     * @param serial Serial number of request.
219     *
220     * Response callback is IRadioResponse.getAllowedCarriersResponse_1_4()
221     */
222    oneway getAllowedCarriers_1_4(int32_t serial);
223
224    /**
225     * Requests current signal strength and associated information.  Must succeed if radio is on.
226     *
227     * @param serial Serial number of request.
228     *
229     * Response function is IRadioResponse.getSignalStrengthResponse_1_4()
230     */
231    oneway getSignalStrength_1_4(int32_t serial);
232};
233