1 /*
2  * Copyright (C) 2020 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 package android.telephony;
17 
18 import android.annotation.IntDef;
19 import android.annotation.NonNull;
20 import android.annotation.Nullable;
21 import android.annotation.SystemApi;
22 import android.os.Parcel;
23 import android.os.Parcelable;
24 
25 import java.lang.annotation.Retention;
26 import java.lang.annotation.RetentionPolicy;
27 
28 
29 /**
30  * Class stores information related to the type of data throttling request to be sent to {@link
31  * TelephonyManager#sendThermalMitigationRequest(ThermalMitigationResult)}.
32  * @hide
33  */
34 @SystemApi
35 public final class ThermalMitigationRequest implements Parcelable {
36     /**
37      * Sent as a thermal mititgation action to {@link
38      * TelephonyManager#sendThermalMitigationRequest(ThermalMitigationResult)} to start data
39      * throttling. {@link TelephonyManager#InvalidThermalMitigationRequestException} will be thrown
40      * if dataThrottlingRequest is {@code null} or if completion duration is < 0.
41      *
42      * @hide
43      */
44     @SystemApi
45     public static final int THERMAL_MITIGATION_ACTION_DATA_THROTTLING = 0;
46 
47     /**
48      * Sent as a thermal mititgation action to {@link
49      * TelephonyManager#sendThermalMitigationRequest(ThermalMitigationResult)} to allow only voice
50      * calls and internet data will not be available. This attempts to enable radio if currently
51      * disabled for thermal mitigation with no guarantee of it actually turning on.
52      * dataThrottlingRequest must be {@code null} or {@link
53      * TelephonyManager#InvalidThermalMitigationRequestException} will be thrown.
54      *
55      * @hide
56      */
57     @SystemApi
58     public static final int THERMAL_MITIGATION_ACTION_VOICE_ONLY = 1;
59 
60     /**
61      * Sent as a thermal mititgation action to {@link'
62      * TelephonyManager#sendThermalMitigationRequest(ThermalMitigationResult)} to turn radio off. If
63      * radio is not able to be powered off because of an ongoing voice call, pending emergency call,
64      * or any other state that wouldn't allow radio off, {@link
65      * TelephonyManager#THERMAL_MITIGATION_RESULT_INVALID_STATE}.
66      * dataThrottlingRequest must be {@code null} or
67      * {@link TelephonyManager#InvalidThermalMitigationRequestException} will be returned.
68      *
69      * @hide
70      */
71     @SystemApi
72     public static final int THERMAL_MITIGATION_ACTION_RADIO_OFF = 2;
73 
74     /**
75      * Type of thermal mitigation action.
76      * @hide
77      */
78     @Retention(RetentionPolicy.SOURCE)
79     @IntDef(prefix = { "THERMAL_MITIGATION_ACTION_" }, value = {
80         THERMAL_MITIGATION_ACTION_DATA_THROTTLING,
81         THERMAL_MITIGATION_ACTION_VOICE_ONLY,
82         THERMAL_MITIGATION_ACTION_RADIO_OFF})
83     public @interface ThermalMitigationAction {}
84 
85     private @ThermalMitigationAction int mThermalMitigationAction;
86     private DataThrottlingRequest mDataThrottlingRequest;
87 
88     /**
89      * @param thermalMitigationAction thermal mitigation action.
90      * @param dataThrottlingRequest is the parameters for more fine-controlled data throttling. This
91      * is only applicable if thermalMitigationAction is
92      * {@link #THERMAL_MITIGATION_ACTION_DATA_THROTTLING}. Otherwise, it must be set to
93      * {@code null}. See {@link DataThrottlingRequest} for more details.
94      */
ThermalMitigationRequest(@hermalMitigationAction int thermalMitigationAction, @Nullable DataThrottlingRequest dataThrottlingRequest)95     private ThermalMitigationRequest(@ThermalMitigationAction int thermalMitigationAction,
96             @Nullable DataThrottlingRequest dataThrottlingRequest) {
97         mThermalMitigationAction = thermalMitigationAction;
98         mDataThrottlingRequest = dataThrottlingRequest;
99     }
100 
ThermalMitigationRequest(Parcel in)101     private ThermalMitigationRequest(Parcel in) {
102         mThermalMitigationAction = in.readInt();
103         mDataThrottlingRequest = in.readParcelable(DataThrottlingRequest.class.getClassLoader());
104     }
105 
106      /**
107      * Implement the Parcelable interface
108      */
109     @Override
writeToParcel(@onNull Parcel dest, int flags)110     public void writeToParcel(@NonNull Parcel dest, int flags) {
111         dest.writeInt(mThermalMitigationAction);
112         dest.writeParcelable(mDataThrottlingRequest, 0);
113     }
114 
115     @Override
describeContents()116     public int describeContents() {
117         return 0;
118     }
119 
120     @Override
toString()121     public String toString() {
122         return "[ThermalMitigationRequest "
123             + ", thermalMitigationAction=" + mThermalMitigationAction
124             + ", dataThrottlingRequest=" + mDataThrottlingRequest
125             + "]";
126     }
127 
128     /**
129      * @return the thermal mitigation action.
130      */
getThermalMitigationAction()131     public @ThermalMitigationAction int getThermalMitigationAction() {
132         return mThermalMitigationAction;
133     }
134 
135     /**
136      * @return the data throttling request.
137      */
138     @Nullable
getDataThrottlingRequest()139     public DataThrottlingRequest getDataThrottlingRequest() {
140         return mDataThrottlingRequest;
141     }
142 
143     public static final @NonNull Parcelable.Creator<ThermalMitigationRequest> CREATOR =
144             new Parcelable.Creator<ThermalMitigationRequest>() {
145 
146         @Override
147         public ThermalMitigationRequest createFromParcel(Parcel in) {
148             return new ThermalMitigationRequest(in);
149         }
150 
151         @Override
152         public ThermalMitigationRequest[] newArray(int size) {
153             return new ThermalMitigationRequest[size];
154         }
155     };
156 
157     /**
158      * Provides a convenient way to set the fields of a {@link ThermalMitigationRequest} when
159      * creating a new instance.
160      *
161      * <p>The example below shows how you might create a new {@code ThermalMitigationRequest}:
162      *
163      * <pre><code>
164      *
165      * ThermalMitigationRequest dp = new ThermalMitigationRequest.Builder()
166      *     .setThermalMitigationAction(
167      *          ThermalMitigationRequest.THERMAL_MITIGATION_ACTION_DATA_THROTTLING)
168      *     .setDataThrottlingRequest(new DataThrottlingRequest.Builder()
169      *          .setDataThrottlingAction(
170      *              DataThrottlingRequest.DATA_THROTTLING_ACTION_THROTTLE_SECONDARY_CARRIER)
171      *          .setCompletionDurationMillis(10000L)
172      *          .build())
173      *     .build();
174      * </code></pre>
175      *
176      * @hide
177      */
178     @SystemApi
179     public static final class Builder {
180         private @ThermalMitigationAction int mThermalMitigationAction = -1;
181         private DataThrottlingRequest mDataThrottlingRequest;
182 
183         /**
184          * Default constructor for Builder.
185          */
Builder()186         public Builder() {}
187 
188         /**
189          * Set the thermal mitigation action.
190          *
191          * @param thermalMitigationAction thermal mitigation action. See {@link
192          *      #THERMAL_MITIGATION_ACTION_DATA_THROTTLING}, {@link
193          *      #THERMAL_MITIGATION_ACTION_VOICE_ONLY}, and {@link
194          *      #THERMAL_MITIGATION_ACTION_RADIO_OFF} for more details.
195          *
196          * @return The same instance of the builder.
197          */
setThermalMitigationAction( @hermalMitigationAction int thermalMitigationAction)198         public @NonNull Builder setThermalMitigationAction(
199                 @ThermalMitigationAction int thermalMitigationAction) {
200             mThermalMitigationAction = thermalMitigationAction;
201             return this;
202         }
203 
204         /**
205          * Set the data throttling request.
206          *
207          * @param dataThrottlingRequest is the parameters for more fine-controlled data throttling.
208          *      This is only applicable if thermalMitigationAction is {@link
209          *      #THERMAL_MITIGATION_ACTION_DATA_THROTTLING}. Otherwise, it should not be set and
210          *      will throw an IllegalArgumentException if it is. See {@link DataThrottlingRequest}
211          *      for more details.
212          *
213          * @return The same instance of the builder.
214          */
setDataThrottlingRequest( @onNull DataThrottlingRequest dataThrottlingRequest)215         public @NonNull Builder setDataThrottlingRequest(
216                 @NonNull DataThrottlingRequest dataThrottlingRequest) {
217             mDataThrottlingRequest = dataThrottlingRequest;
218             return this;
219         }
220 
221         /**
222          * Build the ThermalMitigationRequest.
223          *
224          * @return the ThermalMitigationRequest object.
225          */
build()226         public @NonNull ThermalMitigationRequest build() {
227             if (mThermalMitigationAction < 0) {
228                 throw new IllegalArgumentException("thermalMitigationAction was "
229                         + " not set");
230             }
231 
232             if (mThermalMitigationAction == THERMAL_MITIGATION_ACTION_DATA_THROTTLING) {
233                 if (mDataThrottlingRequest == null) {
234                     throw new IllegalArgumentException("dataThrottlingRequest  cannot be null for "
235                             + "THERMAL_MITIGATION_ACTION_DATA_THROTTLING");
236                 }
237 
238 
239             } else if (mDataThrottlingRequest != null) {
240                 throw new IllegalArgumentException("dataThrottlingRequest must be null for "
241                         + "THERMAL_MITIGATION_ACTION_VOICE_ONLY and "
242                         + "THERMAL_MITIGATION_ACTION_RADIO_OFF");
243             }
244 
245             return new ThermalMitigationRequest(mThermalMitigationAction, mDataThrottlingRequest);
246         }
247     }
248 }
249