1ec4f1859504aa8f7cb819b6c8c34b694a3b816d
[android/platform/frameworks/opt/telephony.git] / src / java / com / android / internal / telephony / IccCard.java
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
17 package com.android.internal.telephony;
18
19 import android.os.Handler;
20 import android.os.Message;
21
22 import com.android.internal.telephony.IccCardConstants.State;
23 import com.android.internal.telephony.uicc.IccCardApplicationStatus;
24 import com.android.internal.telephony.uicc.IccFileHandler;
25 import com.android.internal.telephony.uicc.IccRecords;
26
27 /**
28  * {@hide}
29  * @Deprecated use UiccController.getUiccCard instead.
30  *
31  * Integrated Circuit Card (ICC) interface
32  * An object of a class implementing this interface is used by external
33  * apps (specifically PhoneApp) to perform icc card related functionality.
34  *
35  * Apps (those that have access to Phone object) can retrieve this object
36  * by calling phone.getIccCard()
37  *
38  * This interface is implemented by IccCardProxy and the object PhoneApp
39  * gets when it calls getIccCard is IccCardProxy.
40  */
41 public interface IccCard {
42     /**
43      * @return combined Card and current App state
44      */
45     public State getState();
46
47     /**
48      * @return IccRecords object belonging to current UiccCardApplication
49      */
50     public IccRecords getIccRecords();
51
52     /**
53      * @return IccFileHandler object belonging to current UiccCardApplication
54      */
55     public IccFileHandler getIccFileHandler();
56
57     /**
58      * Notifies handler of any transition into IccCardConstants.State.ABSENT
59      */
60     public void registerForAbsent(Handler h, int what, Object obj);
61     public void unregisterForAbsent(Handler h);
62
63     /**
64      * Notifies handler of any transition into IccCardConstants.State.NETWORK_LOCKED
65      */
66     public void registerForNetworkLocked(Handler h, int what, Object obj);
67     public void unregisterForNetworkLocked(Handler h);
68
69     /**
70      * Notifies handler of any transition into IccCardConstants.State.isPinLocked()
71      */
72     public void registerForLocked(Handler h, int what, Object obj);
73     public void unregisterForLocked(Handler h);
74
75     /**
76      * Supply the ICC PIN to the ICC
77      *
78      * When the operation is complete, onComplete will be sent to its
79      * Handler.
80      *
81      * onComplete.obj will be an AsyncResult
82      *
83      * ((AsyncResult)onComplete.obj).exception == null on success
84      * ((AsyncResult)onComplete.obj).exception != null on fail
85      *
86      * If the supplied PIN is incorrect:
87      * ((AsyncResult)onComplete.obj).exception != null
88      * && ((AsyncResult)onComplete.obj).exception
89      *       instanceof com.android.internal.telephony.gsm.CommandException)
90      * && ((CommandException)(((AsyncResult)onComplete.obj).exception))
91      *          .getCommandError() == CommandException.Error.PASSWORD_INCORRECT
92      */
93     public void supplyPin (String pin, Message onComplete);
94
95     /**
96      * Supply the ICC PUK to the ICC
97      */
98     public void supplyPuk (String puk, String newPin, Message onComplete);
99
100     /**
101      * Supply the ICC PIN2 to the ICC
102      */
103     public void supplyPin2 (String pin2, Message onComplete);
104
105     /**
106      * Supply the ICC PUK2 to the ICC
107      */
108     public void supplyPuk2 (String puk2, String newPin2, Message onComplete);
109
110     /**
111      * Supply Network depersonalization code to the RIL
112      */
113     public void supplyNetworkDepersonalization (String pin, 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     public boolean getIccLockEnabled();
123
124     /**
125      * Check whether ICC fdn (fixed dialing number) is enabled
126      * This is a sync call which returns the cached pin enabled state
127      *
128      * @return true for ICC fdn enabled
129      *         false for ICC fdn disabled
130      */
131     public boolean getIccFdnEnabled();
132
133      /**
134       * Set the ICC pin lock enabled or disabled
135       * When the operation is complete, onComplete will be sent to its handler
136       *
137       * @param enabled "true" for locked "false" for unlocked.
138       * @param password needed to change the ICC pin state, aka. Pin1
139       * @param onComplete
140       *        onComplete.obj will be an AsyncResult
141       *        ((AsyncResult)onComplete.obj).exception == null on success
142       *        ((AsyncResult)onComplete.obj).exception != null on fail
143       */
144      public void setIccLockEnabled (boolean enabled,
145              String password, Message onComplete);
146
147      /**
148       * Set the ICC fdn enabled or disabled
149       * When the operation is complete, onComplete will be sent to its handler
150       *
151       * @param enabled "true" for locked "false" for unlocked.
152       * @param password needed to change the ICC fdn enable, aka Pin2
153       * @param onComplete
154       *        onComplete.obj will be an AsyncResult
155       *        ((AsyncResult)onComplete.obj).exception == null on success
156       *        ((AsyncResult)onComplete.obj).exception != null on fail
157       */
158      public void setIccFdnEnabled (boolean enabled,
159              String password, Message onComplete);
160
161      /**
162       * Change the ICC password used in ICC pin lock
163       * When the operation is complete, onComplete will be sent to its handler
164       *
165       * @param oldPassword is the old password
166       * @param newPassword is the new password
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      public void changeIccLockPassword(String oldPassword, String newPassword,
173              Message onComplete);
174
175      /**
176       * Change the ICC password used in ICC fdn enable
177       * When the operation is complete, onComplete will be sent to its handler
178       *
179       * @param oldPassword is the old password
180       * @param newPassword is the new password
181       * @param onComplete
182       *        onComplete.obj will be an AsyncResult
183       *        ((AsyncResult)onComplete.obj).exception == null on success
184       *        ((AsyncResult)onComplete.obj).exception != null on fail
185       */
186      public void changeIccFdnPassword(String oldPassword, String newPassword,
187              Message onComplete);
188
189     /**
190      * Returns service provider name stored in ICC card.
191      * If there is no service provider name associated or the record is not
192      * yet available, null will be returned <p>
193      *
194      * Please use this value when display Service Provider Name in idle mode <p>
195      *
196      * Usage of this provider name in the UI is a common carrier requirement.
197      *
198      * Also available via Android property "gsm.sim.operator.alpha"
199      *
200      * @return Service Provider Name stored in ICC card
201      *         null if no service provider name associated or the record is not
202      *         yet available
203      *
204      */
205     public String getServiceProviderName ();
206
207     /**
208      * Checks if an Application of specified type present on the card
209      * @param type is AppType to look for
210      */
211     public boolean isApplicationOnIcc(IccCardApplicationStatus.AppType type);
212
213     /**
214      * @return true if a ICC card is present
215      */
216     public boolean hasIccCard();
217 }