summaryrefslogtreecommitdiffstats
blob: 67ce56c582c2bab4b05df452acda62106be5de71 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
/*
 * Copyright (C) 2017 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package android.hardware.radio@1.2;

import @1.1::IRadio;
import @1.1::RadioAccessNetworks;
import @1.0::DataProfileInfo;
import @1.0::RadioTechnology;

/**
 * This interface is used by telephony and telecom to talk to cellular radio.
 * All the functions have minimum one parameter:
 * serial: which corresponds to serial no. of request. Serial numbers must only be memorized for the
 * duration of a method call. If clients provide colliding serials (including passing the same
 * serial to different methods), multiple responses (one for each method call) must still be served.
 * setResponseFunctions must work with @1.1::IRadioResponse and @1.1::IRadioIndication.
 */
interface IRadio extends @1.1::IRadio {

    /**
     * Starts a network scan
     *
     * @param serial Serial number of request.
     * @param request Defines the radio networks/bands/channels which need to be scanned.
     *
     * Response function is IRadioResponse.startNetworkScanResponse()
     */
    oneway startNetworkScan_1_2(int32_t serial, NetworkScanRequest request);

    /**
     * Sets the indication filter.
     *
     * Prevents the reporting of specified unsolicited indications from the radio. This is used
     * for power saving in instances when those indications are not needed. If unset, defaults to
     * @1.2::IndicationFilter:ALL.
     *
     * @param serial Serial number of request.
     * @param indicationFilter 32-bit bitmap of IndicationFilter. Bits set to 1 indicate the
     *        indications are enabled. See @1.2::IndicationFilter for the definition of each bit.
     *
     * Response callback is IRadioResponse.setIndicationFilterResponse()
     */
    oneway setIndicationFilter_1_2(int32_t serial, bitfield<IndicationFilter> indicationFilter);

    /**
     * Sets the signal strength reporting criteria.
     *
     * The resulting reporting criteria are the AND of all the supplied criteria.
     *
     * Note: Reporting criteria must be individually set for each RAN. If unset, reporting criteria
     * for that RAN are implementation-defined.
     *
     * Response callback is IRadioResponse.setSignalStrengthReportingCriteriaResponse().
     *
     * @param serial Serial number of request.
     * @param hysteresisMs A hysteresis time in milliseconds to prevent flapping. A value of 0
     *                     disables hysteresis.
     * @param hysteresisDb An interval in dB defining the required magnitude change between reports.
     *                     hysteresisDb must be smaller than the smallest threshold delta. An
     *                     interval value of 0 disables hysteresis.
     * @param thresholdsDbm A vector of trigger thresholds in dBm. A vector size of 0 disables the
     *                      use of thresholds for reporting.
     * @param ran The type of network for which to apply these thresholds.
     */
    oneway setSignalStrengthReportingCriteria(int32_t serial, int32_t hysteresisMs,
            int32_t hysteresisDb, vec<int32_t> thresholdsDbm, RadioAccessNetworks ran);

    /**
     * Sets the link capacity reporting criteria.
     *
     * The resulting reporting criteria are the AND of all the supplied criteria.
     *
     * Note: Reporting criteria must be individually set for each RAN. If unset, reporting criteria
     * for that RAN are implementation-defined.
     *
     * Response callback is IRadioResponse.setLinkCapacityReportingCriteriaResponse().
     *
     * @param serial Serial number of request.
     * @param hysteresisMs A hysteresis time in milliseconds to prevent flapping. A value of 0
     *                     disables hysteresis.
     * @param hysteresisDlKbps An interval in kbps defining the required magnitude change between DL
     *                         reports. hysteresisDlKbps must be smaller than the smallest threshold
     *                         delta. A value of 0 disables hysteresis.
     * @param hysteresisUlKbps An interval in kbps defining the required magnitude change between UL
     *                         reports. hysteresisUlKbps must be smaller than the smallest threshold
     *                         delta. A value of 0 disables hysteresis.
     * @param thresholdsDownlinkKbps A vector of trigger thresholds in kbps for downlink reports. A
     *                               vector size of 0 disables the use of DL thresholds for
     *                               reporting.
     * @param thresholdsUplinkKbps A vector of trigger thresholds in kbps for uplink reports. A
     *                             vector size of 0 disables the use of UL thresholds for reporting.
     * @param ran The type of network for which to apply these thresholds.
     */
    oneway setLinkCapacityReportingCriteria(int32_t serial, int32_t hysteresisMs,
            int32_t hysteresisDlKbps, int32_t hysteresisUlKbps, vec<int32_t> thresholdsDownlinkKbps,
            vec<int32_t> thresholdsUplinkKbps, RadioAccessNetworks ran);

    /**
     * Setup a packet data connection. If DataCallResponse.status returns DataCallFailCause:NONE,
     * the data connection must be added to data calls and a unsolDataCallListChanged() must be
     * sent. The call remains until removed by subsequent unsolDataCallIstChanged(). It may be
     * lost due to many factors, including deactivateDataCall() being issued, the radio powered
     * off, reception lost or even transient factors like congestion. This data call list is
     * returned by getDataCallList() and dataCallListChanged().
     *
     * The Radio is expected to:
     *   - Create one data call context.
     *   - Create and configure a dedicated interface for the context.
     *   - The interface must be point to point.
     *   - The interface is configured with one or more addresses and is capable of sending and
     *     receiving packets. The prefix length of the addresses must be /32 for IPv4 and /128
     *     for IPv6.
     *   - Must not modify routing configuration related to this interface; routing management is
     *     exclusively within the purview of the Android OS.
     *   - Support simultaneous data call contexts up to DataRegStateResult.maxDataCalls specified
     *     in the response of getDataRegistrationState.
     *
     * @param serial Serial number of request.
     * @param accessNetwork The access network to setup the data call. If the data connection cannot
     *     be established on the specified access network, the setup request must be failed.
     * @param dataProfileInfo Data profile info.
     * @param modemCognitive Indicates that the requested profile has previously been provided via
     *     setDataProfile().
     * @param roamingAllowed Indicates whether or not data roaming is allowed by the user.
     * @param isRoaming Indicates whether or not the framework has requested this setupDataCall for
     *     a roaming network. The 'protocol' parameter in the old RIL API must be filled
     *     accordingly based on the roaming condition. Note this is for backward compatibility with
     *     the old radio modem. The modem must not use this param for any other reason.
     * @param reason The request reason. Must be DataRequestReason.NORMAL or
     *     DataRequestReason.HANDOVER.
     * @param addresses If the reason is DataRequestReason.HANDOVER, this indicates the list of link
     *     addresses of the existing data connection. The format is IP address with optional "/"
     *     prefix length (The format is defined in RFC-4291 section 2.3). For example, "192.0.1.3",
     *     "192.0.1.11/16", or "2001:db8::1/64". Typically one IPv4 or one IPv6 or one of each. If
     *     the prefix length is absent, then the addresses are assumed to be point to point with
     *     IPv4 with prefix length 32 or IPv6 with prefix length 128. This parameter must be ignored
     *     unless reason is DataRequestReason.HANDOVER.
     * @param dnses If the reason is DataRequestReason.HANDOVER, this indicates the list of DNS
     *     addresses of the existing data connection. The format is defined in RFC-4291 section
     *     2.2. For example, "192.0.1.3" or "2001:db8::1". This parameter must be ignored unless
     *     reason is DataRequestReason.HANDOVER.
     *
     * Response function is IRadioResponse.setupDataCallResponse()
     */
    oneway setupDataCall_1_2(int32_t serial, AccessNetwork accessNetwork,
            DataProfileInfo dataProfileInfo, bool modemCognitive, bool roamingAllowed,
            bool isRoaming, DataRequestReason reason, vec<string> addresses, vec<string> dnses);

    /**
     * Deactivate packet data connection and remove from the data call list. An
     * unsolDataCallListChanged() must be sent when data connection is deactivated.
     *
     * @param serial Serial number of request.
     * @param cid Data call id.
     * @param reason The request reason. Must be normal, handover, or shutdown.
     *
     * Response function is IRadioResponse.deactivateDataCallResponse()
     */
    oneway deactivateDataCall_1_2(int32_t serial, int32_t cid, DataRequestReason reason);
};