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.NonNull; 20 import android.compat.annotation.UnsupportedAppUsage; 21 import android.os.Build; 22 import android.os.Bundle; 23 import android.os.Handler; 24 import android.os.Message; 25 import android.os.ResultReceiver; 26 import android.os.WorkSource; 27 import android.telecom.VideoProfile; 28 import android.telephony.Annotation.DataActivityType; 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.util.HashSet; 39 import java.util.List; 40 import java.util.Set; 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 static final String REASON_TRAFFIC_DESCRIPTORS_UPDATED = "trafficDescriptorsUpdated"; 212 213 // Used for band mode selection methods 214 static final int BM_UNSPECIFIED = RILConstants.BAND_MODE_UNSPECIFIED; // automatic 215 static final int BM_EURO_BAND = RILConstants.BAND_MODE_EURO; 216 static final int BM_US_BAND = RILConstants.BAND_MODE_USA; 217 static final int BM_JPN_BAND = RILConstants.BAND_MODE_JPN; 218 static final int BM_AUS_BAND = RILConstants.BAND_MODE_AUS; 219 static final int BM_AUS2_BAND = RILConstants.BAND_MODE_AUS_2; 220 static final int BM_CELL_800 = RILConstants.BAND_MODE_CELL_800; 221 static final int BM_PCS = RILConstants.BAND_MODE_PCS; 222 static final int BM_JTACS = RILConstants.BAND_MODE_JTACS; 223 static final int BM_KOREA_PCS = RILConstants.BAND_MODE_KOREA_PCS; 224 static final int BM_4_450M = RILConstants.BAND_MODE_5_450M; 225 static final int BM_IMT2000 = RILConstants.BAND_MODE_IMT2000; 226 static final int BM_7_700M2 = RILConstants.BAND_MODE_7_700M_2; 227 static final int BM_8_1800M = RILConstants.BAND_MODE_8_1800M; 228 static final int BM_9_900M = RILConstants.BAND_MODE_9_900M; 229 static final int BM_10_800M_2 = RILConstants.BAND_MODE_10_800M_2; 230 static final int BM_EURO_PAMR = RILConstants.BAND_MODE_EURO_PAMR_400M; 231 static final int BM_AWS = RILConstants.BAND_MODE_AWS; 232 static final int BM_US_2500M = RILConstants.BAND_MODE_USA_2500M; 233 static final int BM_NUM_BAND_MODES = 19; //Total number of band modes 234 235 @UnsupportedAppUsage(maxTargetSdk = Build.VERSION_CODES.R, trackingBug = 170729553) 236 int PREFERRED_NT_MODE = RILConstants.PREFERRED_NETWORK_MODE; 237 238 // Used for CDMA roaming mode 239 // Home Networks only, as defined in PRL 240 int CDMA_RM_HOME = TelephonyManager.CDMA_ROAMING_MODE_HOME; 241 // Roaming an Affiliated networks, as defined in PRL 242 int CDMA_RM_AFFILIATED = TelephonyManager.CDMA_ROAMING_MODE_AFFILIATED; 243 // Roaming on Any Network, as defined in PRL 244 int CDMA_RM_ANY = TelephonyManager.CDMA_ROAMING_MODE_ANY; 245 246 // Used for CDMA subscription mode 247 // Unknown 248 static final int CDMA_SUBSCRIPTION_UNKNOWN = TelephonyManager.CDMA_SUBSCRIPTION_UNKNOWN; 249 // RUIM/SIM (default) 250 static final int CDMA_SUBSCRIPTION_RUIM_SIM = TelephonyManager.CDMA_SUBSCRIPTION_RUIM_SIM; 251 // NV -> non-volatile memory 252 static final int CDMA_SUBSCRIPTION_NV = TelephonyManager.CDMA_SUBSCRIPTION_NV; 253 254 static final int PREFERRED_CDMA_SUBSCRIPTION = CDMA_SUBSCRIPTION_RUIM_SIM; 255 256 static final int TTY_MODE_OFF = 0; 257 static final int TTY_MODE_FULL = 1; 258 static final int TTY_MODE_HCO = 2; 259 static final int TTY_MODE_VCO = 3; 260 261 /** 262 * CDMA OTA PROVISION STATUS, the same as RIL_CDMA_OTA_Status in ril.h 263 */ 264 265 public static final int CDMA_OTA_PROVISION_STATUS_SPL_UNLOCKED = 0; 266 public static final int CDMA_OTA_PROVISION_STATUS_SPC_RETRIES_EXCEEDED = 1; 267 public static final int CDMA_OTA_PROVISION_STATUS_A_KEY_EXCHANGED = 2; 268 public static final int CDMA_OTA_PROVISION_STATUS_SSD_UPDATED = 3; 269 public static final int CDMA_OTA_PROVISION_STATUS_NAM_DOWNLOADED = 4; 270 public static final int CDMA_OTA_PROVISION_STATUS_MDN_DOWNLOADED = 5; 271 public static final int CDMA_OTA_PROVISION_STATUS_IMSI_DOWNLOADED = 6; 272 public static final int CDMA_OTA_PROVISION_STATUS_PRL_DOWNLOADED = 7; 273 public static final int CDMA_OTA_PROVISION_STATUS_COMMITTED = 8; 274 public static final int CDMA_OTA_PROVISION_STATUS_OTAPA_STARTED = 9; 275 public static final int CDMA_OTA_PROVISION_STATUS_OTAPA_STOPPED = 10; 276 public static final int CDMA_OTA_PROVISION_STATUS_OTAPA_ABORTED = 11; 277 278 279 /** 280 * Get the current ServiceState. Use 281 * <code>registerForServiceStateChanged</code> to be informed of 282 * updates. 283 */ getServiceState()284 ServiceState getServiceState(); 285 286 /** 287 * Get the current DataState. No change notification exists at this 288 * interface -- use 289 * {@link android.telephony.PhoneStateListener} instead. 290 * @param apnType specify for which apn to get connection state info. 291 */ getDataConnectionState(String apnType)292 DataState getDataConnectionState(String apnType); 293 294 /** 295 * Get the current Precise DataState. No change notification exists at this 296 * interface -- use 297 * {@link android.telephony.PhoneStateListener} instead. 298 * 299 * @param apnType specify for which apn to get connection state info. 300 * @return the PreciseDataConnectionState for the data connection supporting apnType 301 */ getPreciseDataConnectionState(String apnType)302 PreciseDataConnectionState getPreciseDataConnectionState(String apnType); 303 304 /** 305 * Get the current data activity. No change notification exists at this 306 * interface. 307 */ getDataActivityState()308 @DataActivityType int getDataActivityState(); 309 310 /** 311 * Returns a list of MMI codes that are pending. (They have initiated 312 * but have not yet completed). 313 * Presently there is only ever one. 314 * Use <code>registerForMmiInitiate</code> 315 * and <code>registerForMmiComplete</code> for change notification. 316 */ getPendingMmiCodes()317 public List<? extends MmiCode> getPendingMmiCodes(); 318 319 /** 320 * Sends user response to a USSD REQUEST message. An MmiCode instance 321 * representing this response is sent to handlers registered with 322 * registerForMmiInitiate. 323 * 324 * @param ussdMessge Message to send in the response. 325 */ sendUssdResponse(String ussdMessge)326 public void sendUssdResponse(String ussdMessge); 327 328 /** 329 * Register for Supplementary Service notifications from the network. 330 * Message.obj will contain an AsyncResult. 331 * AsyncResult.result will be a SuppServiceNotification instance. 332 * 333 * @param h Handler that receives the notification message. 334 * @param what User-defined message code. 335 * @param obj User object. 336 */ registerForSuppServiceNotification(Handler h, int what, Object obj)337 void registerForSuppServiceNotification(Handler h, int what, Object obj); 338 339 /** 340 * Unregisters for Supplementary Service notifications. 341 * Extraneous calls are tolerated silently 342 * 343 * @param h Handler to be removed from the registrant list. 344 */ unregisterForSuppServiceNotification(Handler h)345 void unregisterForSuppServiceNotification(Handler h); 346 347 /** 348 * Answers a ringing or waiting call. Active calls, if any, go on hold. 349 * Answering occurs asynchronously, and final notification occurs via 350 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 351 * java.lang.Object) registerForPreciseCallStateChanged()}. 352 * 353 * @param videoState The video state in which to answer the call. 354 * @exception CallStateException when no call is ringing or waiting 355 */ acceptCall(int videoState)356 void acceptCall(int videoState) throws CallStateException; 357 358 /** 359 * Reject (ignore) a ringing call. In GSM, this means UDUB 360 * (User Determined User Busy). Reject occurs asynchronously, 361 * and final notification occurs via 362 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 363 * java.lang.Object) registerForPreciseCallStateChanged()}. 364 * 365 * @exception CallStateException when no call is ringing or waiting 366 */ rejectCall()367 void rejectCall() throws CallStateException; 368 369 /** 370 * Places any active calls on hold, and makes any held calls 371 * active. Switch occurs asynchronously and may fail. 372 * Final notification occurs via 373 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 374 * java.lang.Object) registerForPreciseCallStateChanged()}. 375 * 376 * @exception CallStateException if a call is ringing, waiting, or 377 * dialing/alerting. In these cases, this operation may not be performed. 378 */ switchHoldingAndActive()379 void switchHoldingAndActive() throws CallStateException; 380 381 /** 382 * Whether or not the phone can conference in the current phone 383 * state--that is, one call holding and one call active. 384 * @return true if the phone can conference; false otherwise. 385 */ canConference()386 boolean canConference(); 387 388 /** 389 * Conferences holding and active. Conference occurs asynchronously 390 * and may fail. Final notification occurs via 391 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 392 * java.lang.Object) registerForPreciseCallStateChanged()}. 393 * 394 * @exception CallStateException if canConference() would return false. 395 * In these cases, this operation may not be performed. 396 */ conference()397 void conference() throws CallStateException; 398 399 /** 400 * Whether or not the phone can do explicit call transfer in the current 401 * phone state--that is, one call holding and one call active. 402 * @return true if the phone can do explicit call transfer; false otherwise. 403 */ canTransfer()404 boolean canTransfer(); 405 406 /** 407 * Connects the two calls and disconnects the subscriber from both calls 408 * Explicit Call Transfer occurs asynchronously 409 * and may fail. Final notification occurs via 410 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 411 * java.lang.Object) registerForPreciseCallStateChanged()}. 412 * 413 * @exception CallStateException if canTransfer() would return false. 414 * In these cases, this operation may not be performed. 415 */ explicitCallTransfer()416 void explicitCallTransfer() throws CallStateException; 417 418 /** 419 * Clears all DISCONNECTED connections from Call connection lists. 420 * Calls that were in the DISCONNECTED state become idle. This occurs 421 * synchronously. 422 */ clearDisconnected()423 void clearDisconnected(); 424 425 /** 426 * Gets the foreground call object, which represents all connections that 427 * are dialing or active (all connections 428 * that have their audio path connected).<p> 429 * 430 * The foreground call is a singleton object. It is constant for the life 431 * of this phone. It is never null.<p> 432 * 433 * The foreground call will only ever be in one of these states: 434 * IDLE, ACTIVE, DIALING, ALERTING, or DISCONNECTED. 435 * 436 * State change notification is available via 437 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 438 * java.lang.Object) registerForPreciseCallStateChanged()}. 439 */ getForegroundCall()440 Call getForegroundCall(); 441 442 /** 443 * Gets the background call object, which represents all connections that 444 * are holding (all connections that have been accepted or connected, but 445 * do not have their audio path connected). <p> 446 * 447 * The background call is a singleton object. It is constant for the life 448 * of this phone object . It is never null.<p> 449 * 450 * The background call will only ever be in one of these states: 451 * IDLE, HOLDING or DISCONNECTED. 452 * 453 * State change notification is available via 454 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 455 * java.lang.Object) registerForPreciseCallStateChanged()}. 456 */ getBackgroundCall()457 Call getBackgroundCall(); 458 459 /** 460 * Gets the ringing call object, which represents an incoming 461 * connection (if present) that is pending answer/accept. (This connection 462 * may be RINGING or WAITING, and there may be only one.)<p> 463 464 * The ringing call is a singleton object. It is constant for the life 465 * of this phone. It is never null.<p> 466 * 467 * The ringing call will only ever be in one of these states: 468 * IDLE, INCOMING, WAITING or DISCONNECTED. 469 * 470 * State change notification is available via 471 * {@link #registerForPreciseCallStateChanged(android.os.Handler, int, 472 * java.lang.Object) registerForPreciseCallStateChanged()}. 473 */ getRingingCall()474 Call getRingingCall(); 475 476 /** 477 * Initiate a new voice connection. This happens asynchronously, so you 478 * cannot assume the audio path is connected (or a call index has been 479 * assigned) until PhoneStateChanged notification has occurred. 480 * 481 * @param dialString The dial string. 482 * @param dialArgs Parameters to perform the dial with. 483 * @param chosenPhone The Phone (either GsmCdmaPhone or ImsPhone) that has been chosen to dial 484 * this number. This is used for any setup that should occur before dial 485 * actually occurs. 486 * @exception CallStateException if a new outgoing call is not currently 487 * possible because no more call slots exist or a call exists 488 * that is dialing, alerting, ringing, or waiting. Other 489 * errors are handled asynchronously. 490 */ dial(String dialString, @NonNull DialArgs dialArgs, Consumer<Phone> chosenPhone)491 Connection dial(String dialString, @NonNull DialArgs dialArgs, 492 Consumer<Phone> chosenPhone) throws CallStateException; 493 494 /** 495 * Initiate a new voice connection. This happens asynchronously, so you 496 * cannot assume the audio path is connected (or a call index has been 497 * assigned) until PhoneStateChanged notification has occurred. 498 * 499 * @param dialString The dial string. 500 * @param dialArgs Parameters to perform the dial with. 501 * @exception CallStateException if a new outgoing call is not currently 502 * possible because no more call slots exist or a call exists 503 * that is dialing, alerting, ringing, or waiting. Other 504 * errors are handled asynchronously. 505 */ dial(String dialString, @NonNull DialArgs dialArgs)506 default Connection dial(String dialString, @NonNull DialArgs dialArgs) 507 throws CallStateException { 508 return dial(dialString, dialArgs, (phone) -> {}); 509 } 510 511 /** 512 * Initiate a new conference connection. This happens asynchronously, so you 513 * cannot assume the audio path is connected (or a call index has been 514 * assigned) until PhoneStateChanged notification has occurred. 515 * 516 * @param participantsToDial The participants to dial. 517 * @param dialArgs Parameters to perform the start conference with. 518 * @exception CallStateException if a new outgoing call is not currently 519 * possible because no more call slots exist or a call exists 520 * that is dialing, alerting, ringing, or waiting. Other 521 * errors are handled asynchronously. 522 */ startConference(String[] participantsToDial, @NonNull DialArgs dialArgs)523 Connection startConference(String[] participantsToDial, @NonNull DialArgs dialArgs) 524 throws CallStateException; 525 526 /** 527 * Handles PIN MMI commands (PIN/PIN2/PUK/PUK2), which are initiated 528 * without SEND (so <code>dial</code> is not appropriate). 529 * 530 * @param dialString the MMI command to be executed. 531 * @return true if MMI command is executed. 532 */ handlePinMmi(String dialString)533 boolean handlePinMmi(String dialString); 534 535 /** 536 * Handles USSD commands 537 * 538 * @param ussdRequest the USSD command to be executed. 539 * @param wrappedCallback receives the callback result. 540 */ handleUssdRequest(String ussdRequest, ResultReceiver wrappedCallback)541 boolean handleUssdRequest(String ussdRequest, ResultReceiver wrappedCallback) 542 throws CallStateException; 543 544 /** 545 * Handles in-call MMI commands. While in a call, or while receiving a 546 * call, use this to execute MMI commands. 547 * see 3GPP 20.030, section 6.5.5.1 for specs on the allowed MMI commands. 548 * 549 * @param command the MMI command to be executed. 550 * @return true if the MMI command is executed. 551 * @throws CallStateException 552 */ handleInCallMmiCommands(String command)553 boolean handleInCallMmiCommands(String command) throws CallStateException; 554 555 /** 556 * Play a DTMF tone on the active call. Ignored if there is no active call. 557 * @param c should be one of 0-9, '*' or '#'. Other values will be 558 * silently ignored. 559 */ sendDtmf(char c)560 void sendDtmf(char c); 561 562 /** 563 * Start to paly a DTMF tone on the active call. Ignored if there is no active call 564 * or there is a playing DTMF tone. 565 * @param c should be one of 0-9, '*' or '#'. Other values will be 566 * silently ignored. 567 */ startDtmf(char c)568 void startDtmf(char c); 569 570 /** 571 * Stop the playing DTMF tone. Ignored if there is no playing DTMF 572 * tone or no active call. 573 */ stopDtmf()574 void stopDtmf(); 575 576 /** 577 * Sets the radio power on/off state (off is sometimes 578 * called "airplane mode"). Current state can be gotten via 579 * {@link #getServiceState()}.{@link 580 * android.telephony.ServiceState#getState() getState()}. 581 * <strong>Note: </strong>This request is asynchronous. 582 * getServiceState().getState() will not change immediately after this call. 583 * registerForServiceStateChanged() to find out when the 584 * request is complete. This will set the reason for radio power state as {@link 585 * android.telephony.TelephonyManager#RADIO_POWER_REASON_USER}. This will not guarantee that the 586 * requested radio power state will actually be set. 587 * See {@link #setRadioPowerForReason(boolean, boolean, boolean, boolean, int)} 588 * for details. 589 * 590 * @param power true means "on", false means "off". 591 */ setRadioPower(boolean power)592 default void setRadioPower(boolean power) { 593 setRadioPower(power, false, false, false); 594 } 595 596 /** 597 * Sets the radio power on for a test emergency number. 598 * 599 * @param isSelectedPhoneForEmergencyCall true means this phone / modem is selected to place 600 * emergency call after turning power on. 601 */ setRadioPowerOnForTestEmergencyCall(boolean isSelectedPhoneForEmergencyCall)602 default void setRadioPowerOnForTestEmergencyCall(boolean isSelectedPhoneForEmergencyCall) {} 603 604 /** 605 * Sets the radio power on/off state with option to specify whether it's for emergency call 606 * (off is sometimes called "airplane mode"). Current state can be gotten via 607 * {@link #getServiceState()}.{@link 608 * android.telephony.ServiceState#getState() getState()}. 609 * <strong>Note: </strong>This request is asynchronous. 610 * getServiceState().getState() will not change immediately after this call. 611 * registerForServiceStateChanged() to find out when the 612 * request is complete. This will set the reason for radio power state as {@link 613 * android.telephony.TelephonyManager#RADIO_POWER_REASON_USER}. This will not guarantee that the 614 * requested radio power state will actually be set. 615 * See {@link #setRadioPowerForReason(boolean, boolean, boolean, boolean, int)} 616 * for details. 617 * 618 * @param power true means "on", false means "off". 619 * @param forEmergencyCall true means the purpose of turning radio power on is for emergency 620 * call. No effect if power is set false. 621 * @param isSelectedPhoneForEmergencyCall true means this phone / modem is selected to place 622 * emergency call after turning power on. No effect if power 623 * or forEmergency is set false. 624 * @param forceApply true means always call setRadioPower HAL API without checking against 625 * current radio power state. It's needed when: radio was powered on into 626 * emergency call mode, to exit from that mode, we set radio 627 * power on again with forEmergencyCall being false. 628 */ setRadioPower(boolean power, boolean forEmergencyCall, boolean isSelectedPhoneForEmergencyCall, boolean forceApply)629 default void setRadioPower(boolean power, boolean forEmergencyCall, 630 boolean isSelectedPhoneForEmergencyCall, boolean forceApply) { 631 setRadioPowerForReason(power, forEmergencyCall, isSelectedPhoneForEmergencyCall, forceApply, 632 TelephonyManager.RADIO_POWER_REASON_USER); 633 } 634 635 /** 636 * Sets the radio power on/off state (off is sometimes 637 * called "airplane mode") for the specified reason, if possible. Current state can be gotten 638 * via {@link #getServiceState()}.{@link 639 * android.telephony.ServiceState#getState() getState()}. 640 * <strong>Note: </strong>This request is asynchronous. 641 * getServiceState().getState() will not change immediately after this call. 642 * registerForServiceStateChanged() to find out when the 643 * request is complete. Radio power will not be set if it is currently off for a reason other 644 * than the reason for which it is being turned on. However, if forEmergency call is {@code 645 * true}, it will forcefully turn radio power on. 646 * 647 * @param power true means "on", false means "off". 648 * @param reason RadioPowerReason constant defining the reason why the radio power was set. 649 */ setRadioPowerForReason(boolean power, @TelephonyManager.RadioPowerReason int reason)650 default void setRadioPowerForReason(boolean power, 651 @TelephonyManager.RadioPowerReason int reason) { 652 setRadioPowerForReason(power, false, false, false, reason); 653 } 654 655 /** 656 * @return reasons for powering off radio. 657 */ getRadioPowerOffReasons()658 default Set<Integer> getRadioPowerOffReasons() { 659 return new HashSet<>(); 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, @TelephonyManager.RadioPowerReason int reason)686 default void setRadioPowerForReason(boolean power, boolean forEmergencyCall, 687 boolean isSelectedPhoneForEmergencyCall, boolean forceApply, 688 @TelephonyManager.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 IMEI type for phones. 1039 */ getImeiType()1040 int getImeiType(); 1041 /** 1042 * Retrieves the IccPhoneBookInterfaceManager of the Phone 1043 */ getIccPhoneBookInterfaceManager()1044 public IccPhoneBookInterfaceManager getIccPhoneBookInterfaceManager(); 1045 1046 /** 1047 * Activate or deactivate cell broadcast SMS. 1048 * 1049 * @param activate 1050 * 0 = activate, 1 = deactivate 1051 * @param response 1052 * Callback message is empty on completion 1053 */ activateCellBroadcastSms(int activate, Message response)1054 void activateCellBroadcastSms(int activate, Message response); 1055 1056 /** 1057 * Query the current configuration of cdma cell broadcast SMS. 1058 * 1059 * @param response 1060 * Callback message is empty on completion 1061 */ getCellBroadcastSmsConfig(Message response)1062 void getCellBroadcastSmsConfig(Message response); 1063 1064 /** 1065 * Configure cell broadcast SMS. 1066 * 1067 * TODO: Change the configValuesArray to a RIL_BroadcastSMSConfig 1068 * 1069 * @param response 1070 * Callback message is empty on completion 1071 */ setCellBroadcastSmsConfig(int[] configValuesArray, Message response)1072 public void setCellBroadcastSmsConfig(int[] configValuesArray, Message response); 1073 1074 /* 1075 * Sets the carrier information needed to encrypt the IMSI and IMPI. 1076 * @param imsiEncryptionInfo Carrier specific information that will be used to encrypt the 1077 * IMSI and IMPI. This includes the Key type, the Public key 1078 * {@link java.security.PublicKey} and the Key identifier. 1079 */ setCarrierInfoForImsiEncryption(ImsiEncryptionInfo imsiEncryptionInfo)1080 public void setCarrierInfoForImsiEncryption(ImsiEncryptionInfo imsiEncryptionInfo); 1081 1082 /** 1083 * Returns Carrier specific information that will be used to encrypt the IMSI and IMPI. 1084 * @param keyType whether the key is being used for WLAN or ePDG. 1085 * @param fallback whether to fall back to the encryption key stored in carrier config 1086 * @return ImsiEncryptionInfo which includes the Key Type, the Public Key 1087 * {@link java.security.PublicKey} and the Key Identifier. 1088 * The keyIdentifier This is used by the server to help it locate the private key to 1089 * decrypt the permanent identity. 1090 */ getCarrierInfoForImsiEncryption(int keyType, boolean fallback)1091 ImsiEncryptionInfo getCarrierInfoForImsiEncryption(int keyType, boolean fallback); 1092 1093 /** 1094 * Resets the Carrier Keys, by deleting them from the database and sending a download intent. 1095 */ resetCarrierKeysForImsiEncryption()1096 public void resetCarrierKeysForImsiEncryption(); 1097 1098 /** 1099 * Return the mobile provisioning url that is used to launch a browser to allow users to manage 1100 * their mobile plan. 1101 */ getMobileProvisioningUrl()1102 String getMobileProvisioningUrl(); 1103 1104 /** 1105 * Update the cellular usage setting if applicable. 1106 */ updateUsageSetting()1107 boolean updateUsageSetting(); 1108 1109 } 1110