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