1 /* 2 * Copyright (C) 2007 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.annotation.IntDef; 20 import android.annotation.NonNull; 21 import android.compat.annotation.UnsupportedAppUsage; 22 import android.os.Build; 23 import android.os.Bundle; 24 import android.os.Handler; 25 import android.os.Message; 26 import android.os.ResultReceiver; 27 import android.os.WorkSource; 28 import android.telecom.VideoProfile; 29 import android.telephony.ImsiEncryptionInfo; 30 import android.telephony.NetworkScanRequest; 31 import android.telephony.PreciseDataConnectionState; 32 import android.telephony.ServiceState; 33 import android.telephony.TelephonyManager; 34 import android.telephony.emergency.EmergencyNumber; 35 36 import com.android.internal.telephony.PhoneConstants.DataState; 37 38 import java.lang.annotation.Retention; 39 import java.lang.annotation.RetentionPolicy; 40 import java.util.List; 41 import java.util.function.Consumer; 42 43 /** 44 * Internal interface used to control the phone; SDK developers cannot 45 * obtain this interface. 46 * 47 * {@hide} 48 * 49 */ 50 public interface PhoneInternalInterface { 51 52 /** used to enable additional debug messages */ 53 static final boolean DEBUG_PHONE = true; 54 55 public enum DataActivityState { 56 /** 57 * The state of a data activity. 58 * <ul> 59 * <li>NONE = No traffic</li> 60 * <li>DATAIN = Receiving IP ppp traffic</li> 61 * <li>DATAOUT = Sending IP ppp traffic</li> 62 * <li>DATAINANDOUT = Both receiving and sending IP ppp traffic</li> 63 * <li>DORMANT = The data connection is still active, 64 but physical link is down</li> 65 * </ul> 66 */ 67 @UnsupportedAppUsage 68 NONE, DATAIN, DATAOUT, DATAINANDOUT, DORMANT; 69 } 70 71 enum SuppService { 72 UNKNOWN, SWITCH, SEPARATE, TRANSFER, CONFERENCE, REJECT, HANGUP, RESUME, HOLD; 73 } 74 75 /** 76 * Arguments that control behavior of dialing a call. 77 */ 78 public static class DialArgs { 79 public static class Builder<T extends Builder<T>> { 80 protected UUSInfo mUusInfo; 81 protected int mClirMode = CommandsInterface.CLIR_DEFAULT; 82 protected boolean mIsEmergency; 83 protected int mVideoState = VideoProfile.STATE_AUDIO_ONLY; 84 protected Bundle mIntentExtras; 85 protected int mEccCategory = EmergencyNumber.EMERGENCY_SERVICE_CATEGORY_UNSPECIFIED; 86 from(DialArgs dialArgs)87 public static DialArgs.Builder from(DialArgs dialArgs) { 88 return new DialArgs.Builder() 89 .setUusInfo(dialArgs.uusInfo) 90 .setClirMode(dialArgs.clirMode) 91 .setIsEmergency(dialArgs.isEmergency) 92 .setVideoState(dialArgs.videoState) 93 .setIntentExtras(dialArgs.intentExtras) 94 .setEccCategory(dialArgs.eccCategory); 95 } 96 setUusInfo(UUSInfo uusInfo)97 public T setUusInfo(UUSInfo uusInfo) { 98 mUusInfo = uusInfo; 99 return (T) this; 100 } 101 setClirMode(int clirMode)102 public T setClirMode(int clirMode) { 103 mClirMode = clirMode; 104 return (T) this; 105 } 106 setIsEmergency(boolean isEmergency)107 public T setIsEmergency(boolean isEmergency) { 108 mIsEmergency = isEmergency; 109 return (T) this; 110 } 111 setVideoState(int videoState)112 public T setVideoState(int videoState) { 113 mVideoState = videoState; 114 return (T) this; 115 } 116 setIntentExtras(Bundle intentExtras)117 public T setIntentExtras(Bundle intentExtras) { 118 this.mIntentExtras = intentExtras; 119 return (T) this; 120 } 121 setEccCategory(int eccCategory)122 public T setEccCategory(int eccCategory) { 123 mEccCategory = eccCategory; 124 return (T) this; 125 } 126 build()127 public PhoneInternalInterface.DialArgs build() { 128 return new DialArgs(this); 129 } 130 } 131 132 /** The UUSInfo */ 133 public final UUSInfo uusInfo; 134 135 /** The CLIR mode to use */ 136 public final int clirMode; 137 138 /** Indicates emergency call */ 139 public final boolean isEmergency; 140 141 /** The desired video state for the connection. */ 142 public final int videoState; 143 144 /** The extras from the original CALL intent. */ 145 public final Bundle intentExtras; 146 147 /** Indicates emergency service category */ 148 public final int eccCategory; 149 DialArgs(Builder b)150 protected DialArgs(Builder b) { 151 this.uusInfo = b.mUusInfo; 152 this.clirMode = b.mClirMode; 153 this.isEmergency = b.mIsEmergency; 154 this.videoState = b.mVideoState; 155 this.intentExtras = b.mIntentExtras; 156 this.eccCategory = b.mEccCategory; 157 } 158 } 159 160 // "Features" accessible through the connectivity manager 161 static final String FEATURE_ENABLE_MMS = "enableMMS"; 162 static final String FEATURE_ENABLE_SUPL = "enableSUPL"; 163 static final String FEATURE_ENABLE_DUN = "enableDUN"; 164 static final String FEATURE_ENABLE_HIPRI = "enableHIPRI"; 165 static final String FEATURE_ENABLE_DUN_ALWAYS = "enableDUNAlways"; 166 static final String FEATURE_ENABLE_FOTA = "enableFOTA"; 167 static final String FEATURE_ENABLE_IMS = "enableIMS"; 168 static final String FEATURE_ENABLE_CBS = "enableCBS"; 169 static final String FEATURE_ENABLE_EMERGENCY = "enableEmergency"; 170 171 /** 172 * Optional reasons for disconnect and connect 173 */ 174 static final String REASON_ROAMING_ON = "roamingOn"; 175 static final String REASON_ROAMING_OFF = "roamingOff"; 176 static final String REASON_DATA_DISABLED_INTERNAL = "dataDisabledInternal"; 177 static final String REASON_DATA_ENABLED = "dataEnabled"; 178 static final String REASON_DATA_ATTACHED = "dataAttached"; 179 static final String REASON_DATA_DETACHED = "dataDetached"; 180 static final String REASON_CDMA_DATA_ATTACHED = "cdmaDataAttached"; 181 static final String REASON_CDMA_DATA_DETACHED = "cdmaDataDetached"; 182 static final String REASON_APN_CHANGED = "apnChanged"; 183 static final String REASON_APN_SWITCHED = "apnSwitched"; 184 static final String REASON_APN_FAILED = "apnFailed"; 185 static final String REASON_RESTORE_DEFAULT_APN = "restoreDefaultApn"; 186 static final String REASON_RADIO_TURNED_OFF = "radioTurnedOff"; 187 static final String REASON_PDP_RESET = "pdpReset"; 188 static final String REASON_VOICE_CALL_ENDED = "2GVoiceCallEnded"; 189 static final String REASON_VOICE_CALL_STARTED = "2GVoiceCallStarted"; 190 static final String REASON_PS_RESTRICT_ENABLED = "psRestrictEnabled"; 191 static final String REASON_PS_RESTRICT_DISABLED = "psRestrictDisabled"; 192 static final String REASON_SIM_LOADED = "simLoaded"; 193 static final String REASON_NW_TYPE_CHANGED = "nwTypeChanged"; 194 static final String REASON_DATA_DEPENDENCY_MET = "dependencyMet"; 195 static final String REASON_DATA_DEPENDENCY_UNMET = "dependencyUnmet"; 196 static final String REASON_LOST_DATA_CONNECTION = "lostDataConnection"; 197 static final String REASON_CONNECTED = "connected"; 198 static final String REASON_SINGLE_PDN_ARBITRATION = "SinglePdnArbitration"; 199 static final String REASON_DATA_SPECIFIC_DISABLED = "specificDisabled"; 200 static final String REASON_SIM_NOT_READY = "simNotReady"; 201 static final String REASON_IWLAN_AVAILABLE = "iwlanAvailable"; 202 static final String REASON_CARRIER_CHANGE = "carrierChange"; 203 static final String REASON_CARRIER_ACTION_DISABLE_METERED_APN = 204 "carrierActionDisableMeteredApn"; 205 static final String REASON_CSS_INDICATOR_CHANGED = "cssIndicatorChanged"; 206 static final String REASON_RELEASED_BY_CONNECTIVITY_SERVICE = "releasedByConnectivityService"; 207 static final String REASON_DATA_ENABLED_OVERRIDE = "dataEnabledOverride"; 208 static final String REASON_IWLAN_DATA_SERVICE_DIED = "iwlanDataServiceDied"; 209 static final String REASON_VCN_REQUESTED_TEARDOWN = "vcnRequestedTeardown"; 210 static final String REASON_DATA_UNTHROTTLED = "dataUnthrottled"; 211 212 // Reasons for Radio being powered off 213 int RADIO_POWER_REASON_USER = 0; 214 int RADIO_POWER_REASON_THERMAL = 1; 215 @Retention(RetentionPolicy.SOURCE) 216 @IntDef(prefix = {"RADIO_POWER_REASON_"}, 217 value = { 218 RADIO_POWER_REASON_USER, 219 RADIO_POWER_REASON_THERMAL}) 220 public @interface RadioPowerReason {} 221 222 // Used for band mode selection methods 223 static final int BM_UNSPECIFIED = RILConstants.BAND_MODE_UNSPECIFIED; // automatic 224 static final int BM_EURO_BAND = RILConstants.BAND_MODE_EURO; 225 static final int BM_US_BAND = RILConstants.BAND_MODE_USA; 226 static final int BM_JPN_BAND = RILConstants.BAND_MODE_JPN; 227 static final int BM_AUS_BAND = RILConstants.BAND_MODE_AUS; 228 static final int BM_AUS2_BAND = RILConstants.BAND_MODE_AUS_2; 229 static final int BM_CELL_800 = RILConstants.BAND_MODE_CELL_800; 230 static final int BM_PCS = RILConstants.BAND_MODE_PCS; 231 static final int BM_JTACS = RILConstants.BAND_MODE_JTACS; 232 static final int BM_KOREA_PCS = RILConstants.BAND_MODE_KOREA_PCS; 233 static final int BM_4_450M = RILConstants.BAND_MODE_5_450M; 234 static final int BM_IMT2000 = RILConstants.BAND_MODE_IMT2000; 235 static final int BM_7_700M2 = RILConstants.BAND_MODE_7_700M_2; 236 static final int BM_8_1800M = RILConstants.BAND_MODE_8_1800M; 237 static final int BM_9_900M = RILConstants.BAND_MODE_9_900M; 238 static final int BM_10_800M_2 = RILConstants.BAND_MODE_10_800M_2; 239 static final int BM_EURO_PAMR = RILConstants.BAND_MODE_EURO_PAMR_400M; 240 static final int BM_AWS = RILConstants.BAND_MODE_AWS; 241 static final int BM_US_2500M = RILConstants.BAND_MODE_USA_2500M; 242 static final int BM_NUM_BAND_MODES = 19; //Total number of band modes 243 244 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 245 int PREFERRED_NT_MODE = RILConstants.PREFERRED_NETWORK_MODE; 246 247 // Used for CDMA roaming mode 248 // Home Networks only, as defined in PRL 249 int CDMA_RM_HOME = TelephonyManager.CDMA_ROAMING_MODE_HOME; 250 // Roaming an Affiliated networks, as defined in PRL 251 int CDMA_RM_AFFILIATED = TelephonyManager.CDMA_ROAMING_MODE_AFFILIATED; 252 // Roaming on Any Network, as defined in PRL 253 int CDMA_RM_ANY = TelephonyManager.CDMA_ROAMING_MODE_ANY; 254 255 // Used for CDMA subscription mode 256 // Unknown 257 static final int CDMA_SUBSCRIPTION_UNKNOWN = TelephonyManager.CDMA_SUBSCRIPTION_UNKNOWN; 258 // RUIM/SIM (default) 259 static final int CDMA_SUBSCRIPTION_RUIM_SIM = TelephonyManager.CDMA_SUBSCRIPTION_RUIM_SIM; 260 // NV -> non-volatile memory 261 static final int CDMA_SUBSCRIPTION_NV = TelephonyManager.CDMA_SUBSCRIPTION_NV; 262 263 static final int PREFERRED_CDMA_SUBSCRIPTION = CDMA_SUBSCRIPTION_RUIM_SIM; 264 265 static final int TTY_MODE_OFF = 0; 266 static final int TTY_MODE_FULL = 1; 267 static final int TTY_MODE_HCO = 2; 268 static final int TTY_MODE_VCO = 3; 269 270 /** 271 * CDMA OTA PROVISION STATUS, the same as RIL_CDMA_OTA_Status in ril.h 272 */ 273 274 public static final int CDMA_OTA_PROVISION_STATUS_SPL_UNLOCKED = 0; 275 public static final int CDMA_OTA_PROVISION_STATUS_SPC_RETRIES_EXCEEDED = 1; 276 public static final int CDMA_OTA_PROVISION_STATUS_A_KEY_EXCHANGED = 2; 277 public static final int CDMA_OTA_PROVISION_STATUS_SSD_UPDATED = 3; 278 public static final int CDMA_OTA_PROVISION_STATUS_NAM_DOWNLOADED = 4; 279 public static final int CDMA_OTA_PROVISION_STATUS_MDN_DOWNLOADED = 5; 280 public static final int CDMA_OTA_PROVISION_STATUS_IMSI_DOWNLOADED = 6; 281 public static final int CDMA_OTA_PROVISION_STATUS_PRL_DOWNLOADED = 7; 282 public static final int CDMA_OTA_PROVISION_STATUS_COMMITTED = 8; 283 public static final int CDMA_OTA_PROVISION_STATUS_OTAPA_STARTED = 9; 284 public static final int CDMA_OTA_PROVISION_STATUS_OTAPA_STOPPED = 10; 285 public static final int CDMA_OTA_PROVISION_STATUS_OTAPA_ABORTED = 11; 286 287 288 /** 289 * Get the current ServiceState. Use 290 * <code>registerForServiceStateChanged</code> to be informed of 291 * updates. 292 */ getServiceState()293 ServiceState getServiceState(); 294 295 /** 296 * Get the current DataState. No change notification exists at this 297 * interface -- use 298 * {@link android.telephony.PhoneStateListener} instead. 299 * @param apnType specify for which apn to get connection state info. 300 */ getDataConnectionState(String apnType)301 DataState getDataConnectionState(String apnType); 302 303 /** 304 * Get the current Precise DataState. No change notification exists at this 305 * interface -- use 306 * {@link android.telephony.PhoneStateListener} instead. 307 * 308 * @param apnType specify for which apn to get connection state info. 309 * @return the PreciseDataConnectionState for the data connection supporting apnType 310 */ getPreciseDataConnectionState(String apnType)311 PreciseDataConnectionState getPreciseDataConnectionState(String apnType); 312 313 /** 314 * Get the current DataActivityState. No change notification exists at this 315 * interface -- use 316 * {@link android.telephony.TelephonyManager} instead. 317 */ getDataActivityState()318 DataActivityState getDataActivityState(); 319 320 /** 321 * Returns a list of MMI codes that are pending. (They have initiated 322 * but have not yet completed). 323 * Presently there is only ever one. 324 * Use <code>registerForMmiInitiate</code> 325 * and <code>registerForMmiComplete</code> for change notification. 326 */ getPendingMmiCodes()327 public List<? extends MmiCode> getPendingMmiCodes(); 328 329 /** 330 * Sends user response to a USSD REQUEST message. An MmiCode instance 331 * representing this response is sent to handlers registered with 332 * registerForMmiInitiate. 333 * 334 * @param ussdMessge Message to send in the response. 335 */ sendUssdResponse(String ussdMessge)336 public void sendUssdResponse(String ussdMessge); 337 338 /** 339 * Register for Supplementary Service notifications from the network. 340 * Message.obj will contain an AsyncResult. 341 * AsyncResult.result will be a SuppServiceNotification instance. 342 * 343 * @param h Handler that receives the notification message. 344 * @param what User-defined message code. 345 * @param obj User object. 346 */ registerForSuppServiceNotification(Handler h, int what, Object obj)347 void registerForSuppServiceNotification(Handler h, int what, Object obj); 348 349 /** 350 * Unregisters for Supplementary Service notifications. 351 * Extraneous calls are tolerated silently 352 * 353 * @param h Handler to be removed from the registrant list. 354 */ unregisterForSuppServiceNotification(Handler h)355 void unregisterForSuppServiceNotification(Handler h); 356 357 /** 358 * Answers a ringing or waiting call. Active calls, if any, go on hold. 359 * Answering occurs asynchronously, and final notification occurs via 360 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 361 * java.lang.Object) registerForPreciseCallStateChanged()}. 362 * 363 * @param videoState The video state in which to answer the call. 364 * @exception CallStateException when no call is ringing or waiting 365 */ acceptCall(int videoState)366 void acceptCall(int videoState) throws CallStateException; 367 368 /** 369 * Reject (ignore) a ringing call. In GSM, this means UDUB 370 * (User Determined User Busy). Reject occurs asynchronously, 371 * and final notification occurs via 372 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 373 * java.lang.Object) registerForPreciseCallStateChanged()}. 374 * 375 * @exception CallStateException when no call is ringing or waiting 376 */ rejectCall()377 void rejectCall() throws CallStateException; 378 379 /** 380 * Places any active calls on hold, and makes any held calls 381 * active. Switch occurs asynchronously and may fail. 382 * Final notification occurs via 383 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 384 * java.lang.Object) registerForPreciseCallStateChanged()}. 385 * 386 * @exception CallStateException if a call is ringing, waiting, or 387 * dialing/alerting. In these cases, this operation may not be performed. 388 */ switchHoldingAndActive()389 void switchHoldingAndActive() throws CallStateException; 390 391 /** 392 * Whether or not the phone can conference in the current phone 393 * state--that is, one call holding and one call active. 394 * @return true if the phone can conference; false otherwise. 395 */ canConference()396 boolean canConference(); 397 398 /** 399 * Conferences holding and active. Conference occurs asynchronously 400 * and may fail. Final notification occurs via 401 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 402 * java.lang.Object) registerForPreciseCallStateChanged()}. 403 * 404 * @exception CallStateException if canConference() would return false. 405 * In these cases, this operation may not be performed. 406 */ conference()407 void conference() throws CallStateException; 408 409 /** 410 * Whether or not the phone can do explicit call transfer in the current 411 * phone state--that is, one call holding and one call active. 412 * @return true if the phone can do explicit call transfer; false otherwise. 413 */ canTransfer()414 boolean canTransfer(); 415 416 /** 417 * Connects the two calls and disconnects the subscriber from both calls 418 * Explicit Call Transfer occurs asynchronously 419 * and may fail. Final notification occurs via 420 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 421 * java.lang.Object) registerForPreciseCallStateChanged()}. 422 * 423 * @exception CallStateException if canTransfer() would return false. 424 * In these cases, this operation may not be performed. 425 */ explicitCallTransfer()426 void explicitCallTransfer() throws CallStateException; 427 428 /** 429 * Clears all DISCONNECTED connections from Call connection lists. 430 * Calls that were in the DISCONNECTED state become idle. This occurs 431 * synchronously. 432 */ clearDisconnected()433 void clearDisconnected(); 434 435 /** 436 * Gets the foreground call object, which represents all connections that 437 * are dialing or active (all connections 438 * that have their audio path connected).<p> 439 * 440 * The foreground call is a singleton object. It is constant for the life 441 * of this phone. It is never null.<p> 442 * 443 * The foreground call will only ever be in one of these states: 444 * IDLE, ACTIVE, DIALING, ALERTING, or DISCONNECTED. 445 * 446 * State change notification is available via 447 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 448 * java.lang.Object) registerForPreciseCallStateChanged()}. 449 */ getForegroundCall()450 Call getForegroundCall(); 451 452 /** 453 * Gets the background call object, which represents all connections that 454 * are holding (all connections that have been accepted or connected, but 455 * do not have their audio path connected). <p> 456 * 457 * The background call is a singleton object. It is constant for the life 458 * of this phone object . It is never null.<p> 459 * 460 * The background call will only ever be in one of these states: 461 * IDLE, HOLDING or DISCONNECTED. 462 * 463 * State change notification is available via 464 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 465 * java.lang.Object) registerForPreciseCallStateChanged()}. 466 */ getBackgroundCall()467 Call getBackgroundCall(); 468 469 /** 470 * Gets the ringing call object, which represents an incoming 471 * connection (if present) that is pending answer/accept. (This connection 472 * may be RINGING or WAITING, and there may be only one.)<p> 473 474 * The ringing call is a singleton object. It is constant for the life 475 * of this phone. It is never null.<p> 476 * 477 * The ringing call will only ever be in one of these states: 478 * IDLE, INCOMING, WAITING or DISCONNECTED. 479 * 480 * State change notification is available via 481 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 482 * java.lang.Object) registerForPreciseCallStateChanged()}. 483 */ getRingingCall()484 Call getRingingCall(); 485 486 /** 487 * Initiate a new voice connection. This happens asynchronously, so you 488 * cannot assume the audio path is connected (or a call index has been 489 * assigned) until PhoneStateChanged notification has occurred. 490 * 491 * @param dialString The dial string. 492 * @param dialArgs Parameters to perform the dial with. 493 * @param chosenPhone The Phone (either GsmCdmaPhone or ImsPhone) that has been chosen to dial 494 * this number. This is used for any setup that should occur before dial 495 * actually occurs. 496 * @exception CallStateException if a new outgoing call is not currently 497 * possible because no more call slots exist or a call exists 498 * that is dialing, alerting, ringing, or waiting. Other 499 * errors are handled asynchronously. 500 */ dial(String dialString, @NonNull DialArgs dialArgs, Consumer<Phone> chosenPhone)501 Connection dial(String dialString, @NonNull DialArgs dialArgs, 502 Consumer<Phone> chosenPhone) throws CallStateException; 503 504 /** 505 * Initiate a new voice connection. This happens asynchronously, so you 506 * cannot assume the audio path is connected (or a call index has been 507 * assigned) until PhoneStateChanged notification has occurred. 508 * 509 * @param dialString The dial string. 510 * @param dialArgs Parameters to perform the dial with. 511 * @exception CallStateException if a new outgoing call is not currently 512 * possible because no more call slots exist or a call exists 513 * that is dialing, alerting, ringing, or waiting. Other 514 * errors are handled asynchronously. 515 */ dial(String dialString, @NonNull DialArgs dialArgs)516 default Connection dial(String dialString, @NonNull DialArgs dialArgs) 517 throws CallStateException { 518 return dial(dialString, dialArgs, (phone) -> {}); 519 } 520 521 /** 522 * Initiate a new conference connection. This happens asynchronously, so you 523 * cannot assume the audio path is connected (or a call index has been 524 * assigned) until PhoneStateChanged notification has occurred. 525 * 526 * @param participantsToDial The participants to dial. 527 * @param dialArgs Parameters to perform the start conference with. 528 * @exception CallStateException if a new outgoing call is not currently 529 * possible because no more call slots exist or a call exists 530 * that is dialing, alerting, ringing, or waiting. Other 531 * errors are handled asynchronously. 532 */ startConference(String[] participantsToDial, @NonNull DialArgs dialArgs)533 Connection startConference(String[] participantsToDial, @NonNull DialArgs dialArgs) 534 throws CallStateException; 535 536 /** 537 * Handles PIN MMI commands (PIN/PIN2/PUK/PUK2), which are initiated 538 * without SEND (so <code>dial</code> is not appropriate). 539 * 540 * @param dialString the MMI command to be executed. 541 * @return true if MMI command is executed. 542 */ handlePinMmi(String dialString)543 boolean handlePinMmi(String dialString); 544 545 /** 546 * Handles USSD commands 547 * 548 * @param ussdRequest the USSD command to be executed. 549 * @param wrappedCallback receives the callback result. 550 */ handleUssdRequest(String ussdRequest, ResultReceiver wrappedCallback)551 boolean handleUssdRequest(String ussdRequest, ResultReceiver wrappedCallback) 552 throws CallStateException; 553 554 /** 555 * Handles in-call MMI commands. While in a call, or while receiving a 556 * call, use this to execute MMI commands. 557 * see 3GPP 20.030, section 6.5.5.1 for specs on the allowed MMI commands. 558 * 559 * @param command the MMI command to be executed. 560 * @return true if the MMI command is executed. 561 * @throws CallStateException 562 */ handleInCallMmiCommands(String command)563 boolean handleInCallMmiCommands(String command) throws CallStateException; 564 565 /** 566 * Play a DTMF tone on the active call. Ignored if there is no active call. 567 * @param c should be one of 0-9, '*' or '#'. Other values will be 568 * silently ignored. 569 */ sendDtmf(char c)570 void sendDtmf(char c); 571 572 /** 573 * Start to paly a DTMF tone on the active call. Ignored if there is no active call 574 * or there is a playing DTMF tone. 575 * @param c should be one of 0-9, '*' or '#'. Other values will be 576 * silently ignored. 577 */ startDtmf(char c)578 void startDtmf(char c); 579 580 /** 581 * Stop the playing DTMF tone. Ignored if there is no playing DTMF 582 * tone or no active call. 583 */ stopDtmf()584 void stopDtmf(); 585 586 /** 587 * Sets the radio power on/off state (off is sometimes 588 * called "airplane mode"). Current state can be gotten via 589 * {@link #getServiceState()}.{@link 590 * android.telephony.ServiceState#getState() getState()}. 591 * <strong>Note: </strong>This request is asynchronous. 592 * getServiceState().getState() will not change immediately after this call. 593 * registerForServiceStateChanged() to find out when the 594 * request is complete. This will set the reason for radio power state as {@link 595 * #RADIO_POWER_REASON_USER}. This will not guarantee that the requested radio power state will 596 * actually be set. See {@link #setRadioPowerForReason(boolean, boolean, boolean, boolean, int)} 597 * for details. 598 * 599 * @param power true means "on", false means "off". 600 */ setRadioPower(boolean power)601 default void setRadioPower(boolean power) { 602 setRadioPower(power, false, false, false); 603 } 604 605 /** 606 * Sets the radio power on for a test emergency number. 607 * 608 * @param isSelectedPhoneForEmergencyCall true means this phone / modem is selected to place 609 * emergency call after turning power on. 610 */ setRadioPowerOnForTestEmergencyCall(boolean isSelectedPhoneForEmergencyCall)611 default void setRadioPowerOnForTestEmergencyCall(boolean isSelectedPhoneForEmergencyCall) {} 612 613 /** 614 * Sets the radio power on/off state with option to specify whether it's for emergency call 615 * (off is sometimes called "airplane mode"). Current state can be gotten via 616 * {@link #getServiceState()}.{@link 617 * android.telephony.ServiceState#getState() getState()}. 618 * <strong>Note: </strong>This request is asynchronous. 619 * getServiceState().getState() will not change immediately after this call. 620 * registerForServiceStateChanged() to find out when the 621 * request is complete. This will set the reason for radio power state as {@link 622 * #RADIO_POWER_REASON_USER}. This will not guarantee that the requested radio power state will 623 * actually be set. See {@link #setRadioPowerForReason(boolean, boolean, boolean, boolean, int)} 624 * for details. 625 * 626 * @param power true means "on", false means "off". 627 * @param forEmergencyCall true means the purpose of turning radio power on is for emergency 628 * call. No effect if power is set false. 629 * @param isSelectedPhoneForEmergencyCall true means this phone / modem is selected to place 630 * emergency call after turning power on. No effect if power 631 * or forEmergency is set false. 632 * @param forceApply true means always call setRadioPower HAL API without checking against 633 * current radio power state. It's needed when: radio was powered on into 634 * emergency call mode, to exit from that mode, we set radio 635 * power on again with forEmergencyCall being false. 636 */ setRadioPower(boolean power, boolean forEmergencyCall, boolean isSelectedPhoneForEmergencyCall, boolean forceApply)637 default void setRadioPower(boolean power, boolean forEmergencyCall, 638 boolean isSelectedPhoneForEmergencyCall, boolean forceApply) { 639 setRadioPowerForReason(power, forEmergencyCall, isSelectedPhoneForEmergencyCall, forceApply, 640 RADIO_POWER_REASON_USER); 641 } 642 643 /** 644 * Sets the radio power on/off state (off is sometimes 645 * called "airplane mode") for the specified reason, if possible. Current state can be gotten 646 * via {@link #getServiceState()}.{@link 647 * android.telephony.ServiceState#getState() getState()}. 648 * <strong>Note: </strong>This request is asynchronous. 649 * getServiceState().getState() will not change immediately after this call. 650 * registerForServiceStateChanged() to find out when the 651 * request is complete. Radio power will not be set if it is currently off for a reason other 652 * than the reason for which it is being turned on. However, if forEmergency call is {@code 653 * true}, it will forcefully turn radio power on. 654 * 655 * @param power true means "on", false means "off". 656 * @param reason RadioPowerReason constant defining the reason why the radio power was set. 657 */ setRadioPowerForReason(boolean power, @RadioPowerReason int reason)658 default void setRadioPowerForReason(boolean power, @RadioPowerReason int reason) { 659 setRadioPowerForReason(power, false, false, false, reason); 660 } 661 662 /** 663 * Sets the radio power on/off state with option to specify whether it's for emergency call 664 * (off is sometimes called "airplane mode") and option to set the reason for setting the power 665 * state. Current state can be gotten via {@link #getServiceState()}. 666 * {@link android.telephony.ServiceState#getState() getState()}. 667 * <strong>Note: </strong>This request is asynchronous. 668 * getServiceState().getState() will not change immediately after this call. 669 * registerForServiceStateChanged() to find out when the 670 * request is complete. Radio power will not be set if it is currently off for a reason other 671 * than the reason for which it is being turned on. However, if forEmergency call is {@code 672 * true}, it will forcefully turn radio power on. 673 * 674 * @param power true means "on", false means "off". 675 * @param forEmergencyCall true means the purpose of turning radio power on is for emergency 676 * call. No effect if power is set false. 677 * @param isSelectedPhoneForEmergencyCall true means this phone / modem is selected to place 678 * emergency call after turning power on. No effect if power 679 * or forEmergency is set false. 680 * @param forceApply true means always call setRadioPower HAL API without checking against 681 * current radio power state. It's needed when: radio was powered on into 682 * emergency call mode, to exit from that mode, we set radio 683 * power on again with forEmergencyCall being false. 684 * @param reason RadioPowerReason constant defining the reason why the radio power was set. 685 */ setRadioPowerForReason(boolean power, boolean forEmergencyCall, boolean isSelectedPhoneForEmergencyCall, boolean forceApply, @RadioPowerReason int reason)686 default void setRadioPowerForReason(boolean power, boolean forEmergencyCall, 687 boolean isSelectedPhoneForEmergencyCall, boolean forceApply, 688 @RadioPowerReason int reason) {} 689 690 /** 691 * Get the line 1 phone number (MSISDN). For CDMA phones, the MDN is returned 692 * and {@link #getMsisdn()} will return the MSISDN on CDMA/LTE phones.<p> 693 * 694 * @return phone number. May return null if not 695 * available or the SIM is not ready 696 */ getLine1Number()697 String getLine1Number(); 698 699 /** 700 * Returns the alpha tag associated with the msisdn number. 701 * If there is no alpha tag associated or the record is not yet available, 702 * returns a default localized string. <p> 703 */ getLine1AlphaTag()704 String getLine1AlphaTag(); 705 706 /** 707 * Sets the MSISDN phone number in the SIM card. 708 * 709 * @param alphaTag the alpha tag associated with the MSISDN phone number 710 * (see getMsisdnAlphaTag) 711 * @param number the new MSISDN phone number to be set on the SIM. 712 * @param onComplete a callback message when the action is completed. 713 * 714 * @return true if req is sent, false otherwise. If req is not sent there will be no response, 715 * that is, onComplete will never be sent. 716 */ setLine1Number(String alphaTag, String number, Message onComplete)717 boolean setLine1Number(String alphaTag, String number, Message onComplete); 718 719 /** 720 * Get the voice mail access phone number. Typically dialed when the 721 * user holds the "1" key in the phone app. May return null if not 722 * available or the SIM is not ready.<p> 723 */ getVoiceMailNumber()724 String getVoiceMailNumber(); 725 726 /** 727 * Returns the alpha tag associated with the voice mail number. 728 * If there is no alpha tag associated or the record is not yet available, 729 * returns a default localized string. <p> 730 * 731 * Please use this value instead of some other localized string when 732 * showing a name for this number in the UI. For example, call log 733 * entries should show this alpha tag. <p> 734 * 735 * Usage of this alpha tag in the UI is a common carrier requirement. 736 */ getVoiceMailAlphaTag()737 String getVoiceMailAlphaTag(); 738 739 /** 740 * setVoiceMailNumber 741 * sets the voicemail number in the SIM card. 742 * 743 * @param alphaTag the alpha tag associated with the voice mail number 744 * (see getVoiceMailAlphaTag) 745 * @param voiceMailNumber the new voicemail number to be set on the SIM. 746 * @param onComplete a callback message when the action is completed. 747 */ setVoiceMailNumber(String alphaTag, String voiceMailNumber, Message onComplete)748 void setVoiceMailNumber(String alphaTag, 749 String voiceMailNumber, 750 Message onComplete); 751 752 /** 753 * getCallForwardingOptions 754 * gets a call forwarding option for SERVICE_CLASS_VOICE. The return value of 755 * ((AsyncResult)onComplete.obj) is an array of CallForwardInfo. 756 * 757 * @param commandInterfaceCFReason is one of the valid call forwarding 758 * CF_REASONS, as defined in 759 * <code>com.android.internal.telephony.CommandsInterface.</code> 760 * @param onComplete a callback message when the action is completed. 761 * @see com.android.internal.telephony.CallForwardInfo for details. 762 */ getCallForwardingOption(int commandInterfaceCFReason, Message onComplete)763 void getCallForwardingOption(int commandInterfaceCFReason, 764 Message onComplete); 765 766 /** 767 * getCallForwardingOptions 768 * gets a call forwarding option. The return value of 769 * ((AsyncResult)onComplete.obj) is an array of CallForwardInfo. 770 * 771 * @param commandInterfaceCFReason is one of the valid call forwarding 772 * CF_REASONS, as defined in 773 * <code>com.android.internal.telephony.CommandsInterface.</code> 774 * @param serviceClass is a sum of SERVICE_CLASS_* as defined in 775 * <code>com.android.internal.telephony.CommandsInterface.</code> 776 * @param onComplete a callback message when the action is completed. 777 * @see com.android.internal.telephony.CallForwardInfo for details. 778 */ getCallForwardingOption(int commandInterfaceCFReason, int serviceClass, Message onComplete)779 void getCallForwardingOption(int commandInterfaceCFReason, int serviceClass, 780 Message onComplete); 781 782 /** 783 * setCallForwardingOptions 784 * sets a call forwarding option for SERVICE_CLASS_VOICE. 785 * 786 * @param commandInterfaceCFAction is one of the valid call forwarding 787 * CF_ACTIONS, as defined in 788 * <code>com.android.internal.telephony.CommandsInterface.</code> 789 * @param commandInterfaceCFReason is one of the valid call forwarding 790 * CF_REASONS, as defined in 791 * <code>com.android.internal.telephony.CommandsInterface.</code> 792 * @param dialingNumber is the target phone number to forward calls to 793 * @param timerSeconds is used by CFNRy to indicate the timeout before 794 * forwarding is attempted. 795 * @param onComplete a callback message when the action is completed. 796 */ setCallForwardingOption(int commandInterfaceCFAction, int commandInterfaceCFReason, String dialingNumber, int timerSeconds, Message onComplete)797 void setCallForwardingOption(int commandInterfaceCFAction, 798 int commandInterfaceCFReason, 799 String dialingNumber, 800 int timerSeconds, 801 Message onComplete); 802 803 /** 804 * setCallForwardingOptions 805 * sets a call forwarding option. 806 * 807 * @param commandInterfaceCFAction is one of the valid call forwarding 808 * CF_ACTIONS, as defined in 809 * <code>com.android.internal.telephony.CommandsInterface.</code> 810 * @param commandInterfaceCFReason is one of the valid call forwarding 811 * CF_REASONS, as defined in 812 * <code>com.android.internal.telephony.CommandsInterface.</code> 813 * @param dialingNumber is the target phone number to forward calls to 814 * @param serviceClass is a sum of SERVICE_CLASS_* as defined in 815 * <code>com.android.internal.telephony.CommandsInterface.</code> 816 * @param timerSeconds is used by CFNRy to indicate the timeout before 817 * forwarding is attempted. 818 * @param onComplete a callback message when the action is completed. 819 */ setCallForwardingOption(int commandInterfaceCFAction, int commandInterfaceCFReason, String dialingNumber, int serviceClass, int timerSeconds, Message onComplete)820 void setCallForwardingOption(int commandInterfaceCFAction, 821 int commandInterfaceCFReason, 822 String dialingNumber, 823 int serviceClass, 824 int timerSeconds, 825 Message onComplete); 826 827 /** 828 * Gets a call barring option. The return value of ((AsyncResult) onComplete.obj) will be an 829 * Integer representing the sum of enabled serivice classes (sum of SERVICE_CLASS_*) 830 * 831 * @param facility is one of CB_FACILTY_* 832 * @param password is password or "" if not required 833 * @param serviceClass is a sum of SERVICE_CLASS_* 834 * @param onComplete is callback message when the action is completed. 835 */ getCallBarring(String facility, String password, Message onComplete, int serviceClass)836 public void getCallBarring(String facility, 837 String password, 838 Message onComplete, 839 int serviceClass); 840 841 /** 842 * Sets a call barring option. 843 * 844 * @param facility is one of CB_FACILTY_* 845 * @param lockState is true means lock, false means unlock 846 * @param password is password or "" if not required 847 * @param serviceClass is a sum of SERVICE_CLASS_* 848 * @param onComplete is callback message when the action is completed. 849 */ setCallBarring(String facility, boolean lockState, String password, Message onComplete, int serviceClass)850 public void setCallBarring(String facility, 851 boolean lockState, 852 String password, 853 Message onComplete, 854 int serviceClass); 855 856 /** 857 * getOutgoingCallerIdDisplay 858 * gets outgoing caller id display. The return value of 859 * ((AsyncResult)onComplete.obj) is an array of int, with a length of 2. 860 * 861 * @param onComplete a callback message when the action is completed. 862 * @see com.android.internal.telephony.CommandsInterface#getCLIR for details. 863 */ getOutgoingCallerIdDisplay(Message onComplete)864 void getOutgoingCallerIdDisplay(Message onComplete); 865 866 /** 867 * setOutgoingCallerIdDisplay 868 * sets a call forwarding option. 869 * 870 * @param commandInterfaceCLIRMode is one of the valid call CLIR 871 * modes, as defined in 872 * <code>com.android.internal.telephony.CommandsInterface./code> 873 * @param onComplete a callback message when the action is completed. 874 */ setOutgoingCallerIdDisplay(int commandInterfaceCLIRMode, Message onComplete)875 void setOutgoingCallerIdDisplay(int commandInterfaceCLIRMode, 876 Message onComplete); 877 878 /** 879 * getCallWaiting 880 * gets call waiting activation state. The return value of 881 * ((AsyncResult)onComplete.obj) is an array of int, with a length of 1. 882 * 883 * @param onComplete a callback message when the action is completed. 884 * @see com.android.internal.telephony.CommandsInterface#queryCallWaiting for details. 885 */ getCallWaiting(Message onComplete)886 void getCallWaiting(Message onComplete); 887 888 /** 889 * setCallWaiting 890 * sets a call forwarding option. 891 * 892 * @param enable is a boolean representing the state that you are 893 * requesting, true for enabled, false for disabled. 894 * @param onComplete a callback message when the action is completed. 895 */ setCallWaiting(boolean enable, Message onComplete)896 void setCallWaiting(boolean enable, Message onComplete); 897 898 /** 899 * Scan available networks. This method is asynchronous; . 900 * On completion, <code>response.obj</code> is set to an AsyncResult with 901 * one of the following members:.<p> 902 *<ul> 903 * <li><code>response.obj.result</code> will be a <code>List</code> of 904 * <code>OperatorInfo</code> objects, or</li> 905 * <li><code>response.obj.exception</code> will be set with an exception 906 * on failure.</li> 907 * </ul> 908 */ getAvailableNetworks(Message response)909 void getAvailableNetworks(Message response); 910 911 /** 912 * Start a network scan. This method is asynchronous; . 913 * On completion, <code>response.obj</code> is set to an AsyncResult with 914 * one of the following members:.<p> 915 * <ul> 916 * <li><code>response.obj.result</code> will be a <code>NetworkScanResult</code> object, or</li> 917 * <li><code>response.obj.exception</code> will be set with an exception 918 * on failure.</li> 919 * </ul> 920 */ startNetworkScan(NetworkScanRequest nsr, Message response)921 void startNetworkScan(NetworkScanRequest nsr, Message response); 922 923 /** 924 * Stop ongoing network scan. This method is asynchronous; . 925 * On completion, <code>response.obj</code> is set to an AsyncResult with 926 * one of the following members:.<p> 927 * <ul> 928 * <li><code>response.obj.result</code> will be a <code>NetworkScanResult</code> object, or</li> 929 * <li><code>response.obj.exception</code> will be set with an exception 930 * on failure.</li> 931 * </ul> 932 */ stopNetworkScan(Message response)933 void stopNetworkScan(Message response); 934 935 /** 936 * Mutes or unmutes the microphone for the active call. The microphone 937 * is automatically unmuted if a call is answered, dialed, or resumed 938 * from a holding state. 939 * 940 * @param muted true to mute the microphone, 941 * false to activate the microphone. 942 */ 943 setMute(boolean muted)944 void setMute(boolean muted); 945 946 /** 947 * Gets current mute status. Use 948 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 949 * java.lang.Object) registerForPreciseCallStateChanged()} 950 * as a change notifcation, although presently phone state changed is not 951 * fired when setMute() is called. 952 * 953 * @return true is muting, false is unmuting 954 */ getMute()955 boolean getMute(); 956 957 /** 958 * Update the ServiceState CellLocation for current network registration. 959 * 960 * @param workSource the caller to be billed for work. 961 */ updateServiceLocation(WorkSource workSource)962 default void updateServiceLocation(WorkSource workSource) {} 963 964 /** 965 * To be deleted. 966 */ updateServiceLocation()967 default void updateServiceLocation() {} 968 969 /** 970 * Enable location update notifications. 971 */ enableLocationUpdates()972 void enableLocationUpdates(); 973 974 /** 975 * Disable location update notifications. 976 */ disableLocationUpdates()977 void disableLocationUpdates(); 978 979 /** 980 * @return true if enable data connection on roaming 981 */ getDataRoamingEnabled()982 boolean getDataRoamingEnabled(); 983 984 /** 985 * @param enable set true if enable data connection on roaming 986 */ setDataRoamingEnabled(boolean enable)987 void setDataRoamingEnabled(boolean enable); 988 989 /** 990 * @return true if user has enabled data 991 */ isUserDataEnabled()992 boolean isUserDataEnabled(); 993 994 /** 995 * Retrieves the unique device ID, e.g., IMEI for GSM phones and MEID for CDMA phones. 996 */ getDeviceId()997 String getDeviceId(); 998 999 /** 1000 * Retrieves the software version number for the device, e.g., IMEI/SV 1001 * for GSM phones. 1002 */ getDeviceSvn()1003 String getDeviceSvn(); 1004 1005 /** 1006 * Retrieves the unique subscriber ID, e.g., IMSI for GSM phones. 1007 */ getSubscriberId()1008 String getSubscriberId(); 1009 1010 /** 1011 * Retrieves the Group Identifier Level1 for GSM phones. 1012 */ getGroupIdLevel1()1013 String getGroupIdLevel1(); 1014 1015 /** 1016 * Retrieves the Group Identifier Level2 for phones. 1017 */ getGroupIdLevel2()1018 String getGroupIdLevel2(); 1019 1020 /* CDMA support methods */ 1021 1022 /** 1023 * Retrieves the ESN for CDMA phones. 1024 */ getEsn()1025 String getEsn(); 1026 1027 /** 1028 * Retrieves MEID for CDMA phones. 1029 */ getMeid()1030 String getMeid(); 1031 1032 /** 1033 * Retrieves IMEI for phones. Returns null if IMEI is not set. 1034 */ getImei()1035 String getImei(); 1036 1037 /** 1038 * Retrieves the IccPhoneBookInterfaceManager of the Phone 1039 */ getIccPhoneBookInterfaceManager()1040 public IccPhoneBookInterfaceManager getIccPhoneBookInterfaceManager(); 1041 1042 /** 1043 * Activate or deactivate cell broadcast SMS. 1044 * 1045 * @param activate 1046 * 0 = activate, 1 = deactivate 1047 * @param response 1048 * Callback message is empty on completion 1049 */ activateCellBroadcastSms(int activate, Message response)1050 void activateCellBroadcastSms(int activate, Message response); 1051 1052 /** 1053 * Query the current configuration of cdma cell broadcast SMS. 1054 * 1055 * @param response 1056 * Callback message is empty on completion 1057 */ getCellBroadcastSmsConfig(Message response)1058 void getCellBroadcastSmsConfig(Message response); 1059 1060 /** 1061 * Configure cell broadcast SMS. 1062 * 1063 * TODO: Change the configValuesArray to a RIL_BroadcastSMSConfig 1064 * 1065 * @param response 1066 * Callback message is empty on completion 1067 */ setCellBroadcastSmsConfig(int[] configValuesArray, Message response)1068 public void setCellBroadcastSmsConfig(int[] configValuesArray, Message response); 1069 1070 /* 1071 * Sets the carrier information needed to encrypt the IMSI and IMPI. 1072 * @param imsiEncryptionInfo Carrier specific information that will be used to encrypt the 1073 * IMSI and IMPI. This includes the Key type, the Public key 1074 * {@link java.security.PublicKey} and the Key identifier. 1075 */ setCarrierInfoForImsiEncryption(ImsiEncryptionInfo imsiEncryptionInfo)1076 public void setCarrierInfoForImsiEncryption(ImsiEncryptionInfo imsiEncryptionInfo); 1077 1078 /** 1079 * Returns Carrier specific information that will be used to encrypt the IMSI and IMPI. 1080 * @param keyType whether the key is being used for WLAN or ePDG. 1081 * @param fallback whether to fall back to the encryption key stored in carrier config 1082 * @return ImsiEncryptionInfo which includes the Key Type, the Public Key 1083 * {@link java.security.PublicKey} and the Key Identifier. 1084 * The keyIdentifier This is used by the server to help it locate the private key to 1085 * decrypt the permanent identity. 1086 */ getCarrierInfoForImsiEncryption(int keyType, boolean fallback)1087 ImsiEncryptionInfo getCarrierInfoForImsiEncryption(int keyType, boolean fallback); 1088 1089 /** 1090 * Resets the Carrier Keys, by deleting them from the database and sending a download intent. 1091 */ resetCarrierKeysForImsiEncryption()1092 public void resetCarrierKeysForImsiEncryption(); 1093 1094 /** 1095 * Return the mobile provisioning url that is used to launch a browser to allow users to manage 1096 * their mobile plan. 1097 */ getMobileProvisioningUrl()1098 String getMobileProvisioningUrl(); 1099 } 1100