Home | History | Annotate | Download | only in euicc 
      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.os.Parcel;
     22 import android.os.Parcelable;
     23 import android.telephony.UiccAccessRule;
     24 import java.util.ArrayList;
     25 import java.util.Arrays;
     26 import java.util.List;
     27 
     28 import 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  */
     38 public 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