1/*
2 * Copyright (C) 2006 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
17package com.android.internal.telephony;
18
19import android.os.Message;
20import android.os.Handler;
21
22/**
23 * {@hide}
24 */
25public interface IccCard {
26    /* The extra data for broacasting intent INTENT_ICC_STATE_CHANGE */
27    static public final String INTENT_KEY_ICC_STATE = "ss";
28    /* NOT_READY means the ICC interface is not ready (eg, radio is off or powering on) */
29    static public final String INTENT_VALUE_ICC_NOT_READY = "NOT_READY";
30    /* ABSENT means ICC is missing */
31    static public final String INTENT_VALUE_ICC_ABSENT = "ABSENT";
32    /* LOCKED means ICC is locked by pin or by network */
33    static public final String INTENT_VALUE_ICC_LOCKED = "LOCKED";
34    /* READY means ICC is ready to access */
35    static public final String INTENT_VALUE_ICC_READY = "READY";
36    /* IMSI means ICC IMSI is ready in property */
37    static public final String INTENT_VALUE_ICC_IMSI = "IMSI";
38    /* LOADED means all ICC records, including IMSI, are loaded */
39    static public final String INTENT_VALUE_ICC_LOADED = "LOADED";
40    /* The extra data for broacasting intent INTENT_ICC_STATE_CHANGE */
41    static public final String INTENT_KEY_LOCKED_REASON = "reason";
42    /* PIN means ICC is locked on PIN1 */
43    static public final String INTENT_VALUE_LOCKED_ON_PIN = "PIN";
44    /* PUK means ICC is locked on PUK1 */
45    static public final String INTENT_VALUE_LOCKED_ON_PUK = "PUK";
46    /* NETWORK means ICC is locked on NETWORK PERSONALIZATION */
47    static public final String INTENT_VALUE_LOCKED_NETWORK = "NETWORK";
48
49
50    /*
51      UNKNOWN is a transient state, for example, after uesr inputs ICC pin under
52      PIN_REQUIRED state, the query for ICC status returns UNKNOWN before it
53      turns to READY
54     */
55    public enum State {
56        UNKNOWN,
57        ABSENT,
58        PIN_REQUIRED,
59        PUK_REQUIRED,
60        NETWORK_LOCKED,
61        READY;
62
63        public boolean isPinLocked() {
64            return ((this == PIN_REQUIRED) || (this == PUK_REQUIRED));
65        }
66    }
67
68    State getState();
69
70
71    /**
72     * Notifies handler of any transition into State.ABSENT
73     */
74    void registerForAbsent(Handler h, int what, Object obj);
75    void unregisterForAbsent(Handler h);
76
77    /**
78     * Notifies handler of any transition into State.isPinLocked()
79     */
80    void registerForLocked(Handler h, int what, Object obj);
81    void unregisterForLocked(Handler h);
82
83    /**
84     * Notifies handler of any transition into State.NETWORK_LOCKED
85     */
86    void registerForNetworkLocked(Handler h, int what, Object obj);
87    void unregisterForNetworkLocked(Handler h);
88
89    /**
90     * Supply the ICC PIN to the ICC
91     *
92     * When the operation is complete, onComplete will be sent to it's
93     * Handler.
94     *
95     * onComplete.obj will be an AsyncResult
96     *
97     * ((AsyncResult)onComplete.obj).exception == null on success
98     * ((AsyncResult)onComplete.obj).exception != null on fail
99     *
100     * If the supplied PIN is incorrect:
101     * ((AsyncResult)onComplete.obj).exception != null
102     * && ((AsyncResult)onComplete.obj).exception
103     *       instanceof com.android.internal.telephony.gsm.CommandException)
104     * && ((CommandException)(((AsyncResult)onComplete.obj).exception))
105     *          .getCommandError() == CommandException.Error.PASSWORD_INCORRECT
106     *
107     *
108     */
109
110    void supplyPin (String pin, Message onComplete);
111    void supplyPuk (String puk, String newPin, Message onComplete);
112    void supplyPin2 (String pin2, Message onComplete);
113    void supplyPuk2 (String puk2, String newPin2, Message onComplete);
114
115    /**
116     * Check whether ICC pin lock is enabled
117     * This is a sync call which returns the cached pin enabled state
118     *
119     * @return true for ICC locked enabled
120     *         false for ICC locked disabled
121     */
122    boolean getIccLockEnabled ();
123
124    /**
125     * Set the ICC pin lock enabled or disabled
126     * When the operation is complete, onComplete will be sent to its handler
127     *
128     * @param enabled "true" for locked "false" for unlocked.
129     * @param password needed to change the ICC pin state, aka. Pin1
130     * @param onComplete
131     *        onComplete.obj will be an AsyncResult
132     *        ((AsyncResult)onComplete.obj).exception == null on success
133     *        ((AsyncResult)onComplete.obj).exception != null on fail
134     */
135    void setIccLockEnabled(boolean enabled, String password, Message onComplete);
136
137
138    /**
139     * Change the ICC password used in ICC pin lock
140     * When the operation is complete, onComplete will be sent to its handler
141     *
142     * @param oldPassword is the old password
143     * @param newPassword is the new password
144     * @param onComplete
145     *        onComplete.obj will be an AsyncResult
146     *        ((AsyncResult)onComplete.obj).exception == null on success
147     *        ((AsyncResult)onComplete.obj).exception != null on fail
148     */
149    void changeIccLockPassword(String oldPassword, String newPassword,
150                           Message onComplete);
151
152    /**
153     * Check whether ICC fdn (fixed dialing number) is enabled
154     * This is a sync call which returns the cached pin enabled state
155     *
156     * @return true for ICC fdn enabled
157     *         false for ICC fdn disabled
158     */
159    boolean getIccFdnEnabled ();
160
161    /**
162     * Set the ICC fdn enabled or disabled
163     * When the operation is complete, onComplete will be sent to its handler
164     *
165     * @param enabled "true" for locked "false" for unlocked.
166     * @param password needed to change the ICC fdn enable, aka Pin2
167     * @param onComplete
168     *        onComplete.obj will be an AsyncResult
169     *        ((AsyncResult)onComplete.obj).exception == null on success
170     *        ((AsyncResult)onComplete.obj).exception != null on fail
171     */
172    void setIccFdnEnabled(boolean enabled, String password, Message onComplete);
173
174    /**
175     * Change the ICC password used in ICC fdn enable
176     * When the operation is complete, onComplete will be sent to its handler
177     *
178     * @param oldPassword is the old password
179     * @param newPassword is the new password
180     * @param onComplete
181     *        onComplete.obj will be an AsyncResult
182     *        ((AsyncResult)onComplete.obj).exception == null on success
183     *        ((AsyncResult)onComplete.obj).exception != null on fail
184     */
185    void changeIccFdnPassword(String oldPassword, String newPassword,
186                           Message onComplete);
187
188    void supplyNetworkDepersonalization (String pin, Message onComplete);
189
190    /**
191     * Returns service provider name stored in ICC card.
192     * If there is no service provider name associated or the record is not
193     * yet available, null will be returned <p>
194     *
195     * Please use this value when display Service Provider Name in idle mode <p>
196     *
197     * Usage of this provider name in the UI is a common carrier requirement.
198     *
199     * Also available via Android property "gsm.sim.operator.alpha"
200     *
201     * @return Service Provider Name stored in ICC card
202     *         null if no service provider name associated or the record is not
203     *         yet available
204     *
205     */
206    String getServiceProviderName();
207}
208