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