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 package android.telephony.euicc;
17 
18 import android.annotation.Nullable;
19 import android.annotation.SystemApi;
20 import android.app.PendingIntent;
21 import android.compat.annotation.UnsupportedAppUsage;
22 import android.os.Parcel;
23 import android.os.Parcelable;
24 import android.telephony.UiccAccessRule;
25 
26 import com.android.internal.util.Preconditions;
27 
28 import java.util.ArrayList;
29 import java.util.Arrays;
30 import java.util.List;
31 
32 /**
33  * Information about a subscription which is downloadable to an eUICC using
34  * {@link EuiccManager#downloadSubscription(DownloadableSubscription, boolean, PendingIntent).
35  *
36  * <p>For example, a DownloadableSubscription can be created through an activation code parsed from
37  * a QR code. A server address can be parsed from the activation code to download more information
38  * about the profile, such as carrier name, access rules, etc.
39  */
40 public final class DownloadableSubscription implements Parcelable {
41 
42     public static final @android.annotation.NonNull Creator<DownloadableSubscription> CREATOR =
43             new Creator<DownloadableSubscription>() {
44                 @Override
45                 public DownloadableSubscription createFromParcel(Parcel in) {
46                     return new DownloadableSubscription(in);
47                 }
48 
49                 @Override
50                 public DownloadableSubscription[] newArray(int size) {
51                     return new DownloadableSubscription[size];
52                 }
53             };
54 
55     /**
56      * Activation code. May be null for subscriptions which are not based on activation codes, e.g.
57      * to download a default subscription assigned to this device.
58      * Should use getEncodedActivationCode() instead.
59      * @hide
60      * @deprecated - Do not use. This will be private. Use getEncodedActivationCode() instead.
61      */
62     @Nullable
63     @Deprecated
64     @UnsupportedAppUsage
65     public final String encodedActivationCode;
66 
67     @Nullable private String confirmationCode;
68 
69     // see getCarrierName and setCarrierName
70     @Nullable
71     private String carrierName;
72 
73     // see getAccessRules and setAccessRules
74     @Nullable
75     private List<UiccAccessRule> accessRules;
76 
77     /** Gets the activation code. */
78     @Nullable
getEncodedActivationCode()79     public String getEncodedActivationCode() {
80         return encodedActivationCode;
81     }
82 
83     /** @hide */
DownloadableSubscription(String encodedActivationCode)84     private DownloadableSubscription(String encodedActivationCode) {
85         this.encodedActivationCode = encodedActivationCode;
86     }
87 
DownloadableSubscription(Parcel in)88     private DownloadableSubscription(Parcel in) {
89         encodedActivationCode = in.readString();
90         confirmationCode = in.readString();
91         carrierName = in.readString();
92         accessRules = new ArrayList<UiccAccessRule>();
93         in.readTypedList(accessRules, UiccAccessRule.CREATOR);
94     }
95 
DownloadableSubscription(String encodedActivationCode, String confirmationCode, String carrierName, List<UiccAccessRule> accessRules)96     private DownloadableSubscription(String encodedActivationCode, String confirmationCode,
97             String carrierName, List<UiccAccessRule> accessRules) {
98         this.encodedActivationCode = encodedActivationCode;
99         this.confirmationCode = confirmationCode;
100         this.carrierName = carrierName;
101         this.accessRules = accessRules;
102     }
103 
104     /** @hide */
105     @SystemApi
106     public static final class Builder {
107         @Nullable private String encodedActivationCode;
108         @Nullable private String confirmationCode;
109         @Nullable private String carrierName;
110         List<UiccAccessRule> accessRules;
111 
Builder()112         public Builder() {}
113 
Builder(DownloadableSubscription baseSubscription)114         public Builder(DownloadableSubscription baseSubscription) {
115             encodedActivationCode = baseSubscription.getEncodedActivationCode();
116             confirmationCode = baseSubscription.getConfirmationCode();
117             carrierName = baseSubscription.getCarrierName();
118             accessRules = baseSubscription.getAccessRules();
119         }
120 
build()121         public DownloadableSubscription build() {
122             return new DownloadableSubscription(encodedActivationCode, confirmationCode,
123                     carrierName, accessRules);
124         }
125 
setEncodedActivationCode(String value)126         public Builder setEncodedActivationCode(String value) {
127             encodedActivationCode = value;
128             return this;
129         }
130 
setConfirmationCode(String value)131         public Builder setConfirmationCode(String value) {
132             confirmationCode = value;
133             return this;
134         }
135 
setCarrierName(String value)136         public Builder setCarrierName(String value) {
137             carrierName = value;
138             return this;
139         }
140 
setAccessRules(List<UiccAccessRule> value)141         public Builder setAccessRules(List<UiccAccessRule> value) {
142             accessRules = value;
143             return this;
144         }
145     }
146 
147     /**
148      * Create a DownloadableSubscription for the given activation code.
149      *
150      * <p>This fills the encodedActivationCode field. Other fields like confirmationCode,
151      * carrierName and accessRules may be filled in the implementation of
152      * {@code android.service.euicc.EuiccService} if exists.
153      *
154      * @param encodedActivationCode the activation code to use. An activation code can be parsed
155      *         from a user scanned QR code. The format of activation code is defined in SGP.22. For
156      *         example, "1$SMDP.GSMA.COM$04386-AGYFT-A74Y8-3F815$1.3.6.1.4.1.31746". For detail, see
157      *         {@code com.android.euicc.data.ActivationCode}. Must not be null.
158      *
159      * @return the {@link DownloadableSubscription} which may be passed to
160      *     {@link EuiccManager#downloadSubscription}.
161      */
forActivationCode(String encodedActivationCode)162     public static DownloadableSubscription forActivationCode(String encodedActivationCode) {
163         Preconditions.checkNotNull(encodedActivationCode, "Activation code may not be null");
164         return new DownloadableSubscription(encodedActivationCode);
165     }
166 
167     /**
168      * Sets the confirmation code.
169      * @hide
170      * @deprecated - Do not use.
171      */
172     @Deprecated
setConfirmationCode(String confirmationCode)173     public void setConfirmationCode(String confirmationCode) {
174         this.confirmationCode = confirmationCode;
175     }
176 
177     /**
178      * Returns the confirmation code.
179      *
180      * <p>As an example, the confirmation code can be input by the user through a carrier app or the
181      * UI component of the eUICC local profile assistant (LPA) application.
182      */
183     @Nullable
getConfirmationCode()184     public String getConfirmationCode() {
185         return confirmationCode;
186     }
187 
188     /**
189      * Set the user-visible carrier name.
190      * @hide
191      * @deprecated - Do not use.
192      */
193     @Deprecated
194     @UnsupportedAppUsage
setCarrierName(String carrierName)195     public void setCarrierName(String carrierName) {
196         this.carrierName = carrierName;
197     }
198 
199     /**
200      * Returns the user-visible carrier name.
201      *
202      * <p>Only present for downloadable subscriptions that were queried from a server (as opposed to
203      * those created with {@link #forActivationCode}). May be populated with
204      * {@link EuiccManager#getDownloadableSubscriptionMetadata}.
205      * @hide
206      */
207     @SystemApi
208     @Nullable
getCarrierName()209     public String getCarrierName() {
210         return carrierName;
211     }
212 
213     /**
214      * Returns the {@link UiccAccessRule}s in list dictating access to this subscription.
215      *
216      * <p>Only present for downloadable subscriptions that were queried from a server (as opposed to
217      * those created with {@link #forActivationCode}). May be populated with
218      * {@link EuiccManager#getDownloadableSubscriptionMetadata}.
219      * @hide
220      */
221     @SystemApi
getAccessRules()222     public List<UiccAccessRule> getAccessRules() {
223         return accessRules;
224     }
225 
226     /**
227      * Set the {@link UiccAccessRule}s dictating access to this subscription.
228      * @hide
229      * @deprecated - Do not use.
230      */
231     @Deprecated
setAccessRules(List<UiccAccessRule> accessRules)232     public void setAccessRules(List<UiccAccessRule> accessRules) {
233         this.accessRules = accessRules;
234     }
235 
236     /**
237      * @hide
238      * @deprecated - Do not use.
239      */
240     @Deprecated
241     @UnsupportedAppUsage
setAccessRules(UiccAccessRule[] accessRules)242     public void setAccessRules(UiccAccessRule[] accessRules) {
243         this.accessRules = Arrays.asList(accessRules);
244     }
245 
246     @Override
writeToParcel(Parcel dest, int flags)247     public void writeToParcel(Parcel dest, int flags) {
248         dest.writeString(encodedActivationCode);
249         dest.writeString(confirmationCode);
250         dest.writeString(carrierName);
251         dest.writeTypedList(accessRules);
252     }
253 
254     @Override
describeContents()255     public int describeContents() {
256         return 0;
257     }
258 }
259