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