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 
17 package android.telephony;
18 
19 import android.annotation.IntDef;
20 import android.annotation.NonNull;
21 import android.annotation.Nullable;
22 import android.annotation.SystemApi;
23 import android.os.Parcel;
24 import android.os.Parcelable;
25 
26 import com.android.internal.telephony.PhoneConstants;
27 
28 import java.util.Objects;
29 
30 /**
31  * Holds the result from a PIN attempt.
32  *
33  * @see TelephonyManager#supplyIccLockPin
34  * @see TelephonyManager#supplyIccLockPuk
35  * @see TelephonyManager#setIccLockEnabled
36  * @see TelephonyManager#changeIccLockPin
37  *
38  * @hide
39  */
40 @SystemApi
41 public final class PinResult implements Parcelable {
42     /** @hide */
43     @IntDef({
44             PIN_RESULT_TYPE_SUCCESS,
45             PIN_RESULT_TYPE_INCORRECT,
46             PIN_RESULT_TYPE_FAILURE,
47             PIN_RESULT_TYPE_ABORTED,
48     })
49     public @interface PinResultType {}
50 
51     /**
52      * Indicates that the pin attempt was a success.
53      */
54     public static final int PIN_RESULT_TYPE_SUCCESS = PhoneConstants.PIN_RESULT_SUCCESS;
55 
56     /**
57      * Indicates that the pin attempt was incorrect.
58      */
59     public static final int PIN_RESULT_TYPE_INCORRECT = PhoneConstants.PIN_PASSWORD_INCORRECT;
60 
61     /**
62      * Indicates that the pin attempt was a failure.
63      */
64     public static final int PIN_RESULT_TYPE_FAILURE = PhoneConstants.PIN_GENERAL_FAILURE;
65 
66     /**
67      * Indicates that the pin attempt was aborted.
68      */
69     public static final int PIN_RESULT_TYPE_ABORTED = PhoneConstants.PIN_OPERATION_ABORTED;
70 
71     private static final PinResult sFailedResult =
72             new PinResult(PinResult.PIN_RESULT_TYPE_FAILURE, -1);
73 
74     private final @PinResultType int mResult;
75 
76     private final int mAttemptsRemaining;
77 
78     /**
79      * Returns the result of the PIN attempt.
80      *
81      * @return The result of the PIN attempt.
82      */
getResult()83     public @PinResultType int getResult() {
84         return mResult;
85     }
86 
87     /**
88      * Returns the number of PIN attempts remaining.
89      * This will be set when {@link #getResult} is {@link #PIN_RESULT_TYPE_INCORRECT}.
90      * Indicates the number of attempts at entering the PIN before the SIM will be locked and
91      * require a PUK unlock to be performed.
92      *
93      * @return Number of attempts remaining.
94      */
getAttemptsRemaining()95     public int getAttemptsRemaining() {
96         return mAttemptsRemaining;
97     }
98 
99     /**
100      * Used to indicate a failed PIN attempt result.
101      *
102      * @return default PinResult for failure.
103      *
104      * @hide
105      */
106     @NonNull
getDefaultFailedResult()107     public static PinResult getDefaultFailedResult() {
108         return sFailedResult;
109     }
110 
111     /**
112      * PinResult constructor.
113      *
114      * @param result The pin result value.
115      * @see #PIN_RESULT_TYPE_SUCCESS
116      * @see #PIN_RESULT_TYPE_INCORRECT
117      * @see #PIN_RESULT_TYPE_FAILURE
118      * @see #PIN_RESULT_TYPE_ABORTED
119      * @param attemptsRemaining Number of pin attempts remaining.
120      *
121      * @hide
122      */
PinResult(@inResultType int result, int attemptsRemaining)123     public PinResult(@PinResultType int result, int attemptsRemaining) {
124         mResult = result;
125         mAttemptsRemaining = attemptsRemaining;
126     }
127 
128     /**
129      * Construct a PinResult object from the given parcel.
130      *
131      * @hide
132      */
PinResult(Parcel in)133     private PinResult(Parcel in) {
134         mResult = in.readInt();
135         mAttemptsRemaining = in.readInt();
136     }
137 
138     /**
139      * String representation of the Pin Result.
140      */
141     @NonNull
142     @Override
toString()143     public String toString() {
144         return "result: " + getResult() + ", attempts remaining: " + getAttemptsRemaining();
145     }
146 
147     /**
148      * Describe the contents of this object.
149      */
150     @Override
describeContents()151     public int describeContents() {
152         return 0;
153     }
154 
155     /**
156      * Write this object to a Parcel.
157      */
158     @Override
writeToParcel(@onNull Parcel out, int flags)159     public void writeToParcel(@NonNull Parcel out, int flags) {
160         out.writeInt(mResult);
161         out.writeInt(mAttemptsRemaining);
162     }
163 
164     /**
165      * Parcel creator class.
166      */
167     public static final @NonNull Parcelable.Creator<PinResult> CREATOR = new Creator<PinResult>() {
168         public PinResult createFromParcel(Parcel in) {
169             return new PinResult(in);
170         }
171         public PinResult[] newArray(int size) {
172             return new PinResult[size];
173         }
174     };
175 
176     @Override
hashCode()177     public int hashCode() {
178         return Objects.hash(mAttemptsRemaining, mResult);
179     }
180 
181     @Override
equals(@ullable Object obj)182     public boolean equals(@Nullable Object obj) {
183         if (this == obj) {
184             return true;
185         }
186         if (obj == null) {
187             return false;
188         }
189         if (getClass() != obj.getClass()) {
190             return false;
191         }
192         PinResult other = (PinResult) obj;
193         return (mResult == other.mResult
194                 && mAttemptsRemaining == other.mAttemptsRemaining);
195     }
196 }
197