PhoneStateListener.java revision 309b2f63f3265c341f6a43cbca2fb25f9c38109a
1/* 2 * Copyright (C) 2008 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17package android.telephony; 18 19import android.os.Bundle; 20import android.os.Handler; 21import android.os.Looper; 22import android.os.Message; 23import android.telephony.SubscriptionManager; 24import android.telephony.CellLocation; 25import android.telephony.CellInfo; 26import android.telephony.VoLteServiceState; 27import android.telephony.Rlog; 28import android.telephony.ServiceState; 29import android.telephony.SignalStrength; 30import android.telephony.PreciseCallState; 31import android.telephony.PreciseDataConnectionState; 32 33import com.android.internal.telephony.IPhoneStateListener; 34import java.util.List; 35 36/** 37 * A listener class for monitoring changes in specific telephony states 38 * on the device, including service state, signal strength, message 39 * waiting indicator (voicemail), and others. 40 * <p> 41 * Override the methods for the state that you wish to receive updates for, and 42 * pass your PhoneStateListener object, along with bitwise-or of the LISTEN_ 43 * flags to {@link TelephonyManager#listen TelephonyManager.listen()}. 44 * <p> 45 * Note that access to some telephony information is 46 * permission-protected. Your application won't receive updates for protected 47 * information unless it has the appropriate permissions declared in 48 * its manifest file. Where permissions apply, they are noted in the 49 * appropriate LISTEN_ flags. 50 */ 51public class PhoneStateListener { 52 private static final String LOG_TAG = "PhoneStateListener"; 53 private static final boolean DBG = false; // STOPSHIP if true 54 55 /** 56 * Stop listening for updates. 57 */ 58 public static final int LISTEN_NONE = 0; 59 60 /** 61 * Listen for changes to the network service state (cellular). 62 * 63 * @see #onServiceStateChanged 64 * @see ServiceState 65 */ 66 public static final int LISTEN_SERVICE_STATE = 0x00000001; 67 68 /** 69 * Listen for changes to the network signal strength (cellular). 70 * {@more} 71 * Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE 72 * READ_PHONE_STATE} 73 * <p> 74 * 75 * @see #onSignalStrengthChanged 76 * 77 * @deprecated by {@link #LISTEN_SIGNAL_STRENGTHS} 78 */ 79 @Deprecated 80 public static final int LISTEN_SIGNAL_STRENGTH = 0x00000002; 81 82 /** 83 * Listen for changes to the message-waiting indicator. 84 * {@more} 85 * Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE 86 * READ_PHONE_STATE} 87 * <p> 88 * Example: The status bar uses this to determine when to display the 89 * voicemail icon. 90 * 91 * @see #onMessageWaitingIndicatorChanged 92 */ 93 public static final int LISTEN_MESSAGE_WAITING_INDICATOR = 0x00000004; 94 95 /** 96 * Listen for changes to the call-forwarding indicator. 97 * {@more} 98 * Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE 99 * READ_PHONE_STATE} 100 * @see #onCallForwardingIndicatorChanged 101 */ 102 public static final int LISTEN_CALL_FORWARDING_INDICATOR = 0x00000008; 103 104 /** 105 * Listen for changes to the device's cell location. Note that 106 * this will result in frequent callbacks to the listener. 107 * {@more} 108 * Requires Permission: {@link android.Manifest.permission#ACCESS_COARSE_LOCATION 109 * ACCESS_COARSE_LOCATION} 110 * <p> 111 * If you need regular location updates but want more control over 112 * the update interval or location precision, you can set up a listener 113 * through the {@link android.location.LocationManager location manager} 114 * instead. 115 * 116 * @see #onCellLocationChanged 117 */ 118 public static final int LISTEN_CELL_LOCATION = 0x00000010; 119 120 /** 121 * Listen for changes to the device call state. 122 * {@more} 123 * 124 * @see #onCallStateChanged 125 */ 126 public static final int LISTEN_CALL_STATE = 0x00000020; 127 128 /** 129 * Listen for changes to the data connection state (cellular). 130 * 131 * @see #onDataConnectionStateChanged 132 */ 133 public static final int LISTEN_DATA_CONNECTION_STATE = 0x00000040; 134 135 /** 136 * Listen for changes to the direction of data traffic on the data 137 * connection (cellular). 138 * {@more} 139 * Example: The status bar uses this to display the appropriate 140 * data-traffic icon. 141 * 142 * @see #onDataActivity 143 */ 144 public static final int LISTEN_DATA_ACTIVITY = 0x00000080; 145 146 /** 147 * Listen for changes to the network signal strengths (cellular). 148 * <p> 149 * Example: The status bar uses this to control the signal-strength 150 * icon. 151 * 152 * @see #onSignalStrengthsChanged 153 */ 154 public static final int LISTEN_SIGNAL_STRENGTHS = 0x00000100; 155 156 /** 157 * Listen for changes to OTASP mode. 158 * 159 * @see #onOtaspChanged 160 * @hide 161 */ 162 public static final int LISTEN_OTASP_CHANGED = 0x00000200; 163 164 /** 165 * Listen for changes to observed cell info. 166 * 167 * @see #onCellInfoChanged 168 */ 169 public static final int LISTEN_CELL_INFO = 0x00000400; 170 171 /** 172 * Listen for precise changes and fails to the device calls (cellular). 173 * {@more} 174 * Requires Permission: {@link android.Manifest.permission#READ_PRECISE_PHONE_STATE 175 * READ_PRECISE_PHONE_STATE} 176 * 177 * @hide 178 */ 179 public static final int LISTEN_PRECISE_CALL_STATE = 0x00000800; 180 181 /** 182 * Listen for precise changes and fails on the data connection (cellular). 183 * {@more} 184 * Requires Permission: {@link android.Manifest.permission#READ_PRECISE_PHONE_STATE 185 * READ_PRECISE_PHONE_STATE} 186 * 187 * @see #onPreciseDataConnectionStateChanged 188 * @hide 189 */ 190 public static final int LISTEN_PRECISE_DATA_CONNECTION_STATE = 0x00001000; 191 192 /** 193 * Listen for real time info for all data connections (cellular)). 194 * {@more} 195 * Requires Permission: {@link android.Manifest.permission#READ_PRECISE_PHONE_STATE 196 * READ_PRECISE_PHONE_STATE} 197 * 198 * @see #onDataConnectionRealTimeInfoChanged(DataConnectionRealTimeInfo) 199 * @hide 200 */ 201 public static final int LISTEN_DATA_CONNECTION_REAL_TIME_INFO = 0x00002000; 202 203 /** 204 * Listen for changes to LTE network state 205 * 206 * @see #onLteNetworkStateChanged 207 * @hide 208 */ 209 public static final int LISTEN_VOLTE_STATE = 0x00004000; 210 211 /** 212 * Listen for OEM hook raw event 213 * 214 * @see #onOemHookRawEvent 215 * @hide 216 */ 217 public static final int LISTEN_OEM_HOOK_RAW_EVENT = 0x00008000; 218 219 /** 220 * Listen for carrier network changes indicated by a carrier app. 221 * 222 * @see #onCarrierNetworkRequest 223 * @see TelephonyManager#notifyCarrierNetworkChange(boolean) 224 * @hide 225 */ 226 public static final int LISTEN_CARRIER_NETWORK_CHANGE = 0x00010000; 227 228 /* 229 * Subscription used to listen to the phone state changes 230 * @hide 231 */ 232 /** @hide */ 233 protected int mSubId = SubscriptionManager.INVALID_SUBSCRIPTION_ID; 234 235 private final Handler mHandler; 236 237 /** 238 * Create a PhoneStateListener for the Phone with the default subscription. 239 * This class requires Looper.myLooper() not return null. 240 */ 241 public PhoneStateListener() { 242 this(SubscriptionManager.DEFAULT_SUBSCRIPTION_ID, Looper.myLooper()); 243 } 244 245 /** 246 * Create a PhoneStateListener for the Phone with the default subscription 247 * using a particular non-null Looper. 248 * @hide 249 */ 250 public PhoneStateListener(Looper looper) { 251 this(SubscriptionManager.DEFAULT_SUBSCRIPTION_ID, looper); 252 } 253 254 /** 255 * Create a PhoneStateListener for the Phone using the specified subscription. 256 * This class requires Looper.myLooper() not return null. To supply your 257 * own non-null Looper use PhoneStateListener(int subId, Looper looper) below. 258 * @hide 259 */ 260 public PhoneStateListener(int subId) { 261 this(subId, Looper.myLooper()); 262 } 263 264 /** 265 * Create a PhoneStateListener for the Phone using the specified subscription 266 * and non-null Looper. 267 * @hide 268 */ 269 public PhoneStateListener(int subId, Looper looper) { 270 if (DBG) log("ctor: subId=" + subId + " looper=" + looper); 271 mSubId = subId; 272 mHandler = new Handler(looper) { 273 public void handleMessage(Message msg) { 274 if (DBG) { 275 log("mSubId=" + mSubId + " what=0x" + Integer.toHexString(msg.what) 276 + " msg=" + msg); 277 } 278 switch (msg.what) { 279 case LISTEN_SERVICE_STATE: 280 PhoneStateListener.this.onServiceStateChanged((ServiceState)msg.obj); 281 break; 282 case LISTEN_SIGNAL_STRENGTH: 283 PhoneStateListener.this.onSignalStrengthChanged(msg.arg1); 284 break; 285 case LISTEN_MESSAGE_WAITING_INDICATOR: 286 PhoneStateListener.this.onMessageWaitingIndicatorChanged(msg.arg1 != 0); 287 break; 288 case LISTEN_CALL_FORWARDING_INDICATOR: 289 PhoneStateListener.this.onCallForwardingIndicatorChanged(msg.arg1 != 0); 290 break; 291 case LISTEN_CELL_LOCATION: 292 PhoneStateListener.this.onCellLocationChanged((CellLocation)msg.obj); 293 break; 294 case LISTEN_CALL_STATE: 295 PhoneStateListener.this.onCallStateChanged(msg.arg1, (String)msg.obj); 296 break; 297 case LISTEN_DATA_CONNECTION_STATE: 298 PhoneStateListener.this.onDataConnectionStateChanged(msg.arg1, msg.arg2); 299 PhoneStateListener.this.onDataConnectionStateChanged(msg.arg1); 300 break; 301 case LISTEN_DATA_ACTIVITY: 302 PhoneStateListener.this.onDataActivity(msg.arg1); 303 break; 304 case LISTEN_SIGNAL_STRENGTHS: 305 PhoneStateListener.this.onSignalStrengthsChanged((SignalStrength)msg.obj); 306 break; 307 case LISTEN_OTASP_CHANGED: 308 PhoneStateListener.this.onOtaspChanged(msg.arg1); 309 break; 310 case LISTEN_CELL_INFO: 311 PhoneStateListener.this.onCellInfoChanged((List<CellInfo>)msg.obj); 312 break; 313 case LISTEN_PRECISE_CALL_STATE: 314 PhoneStateListener.this.onPreciseCallStateChanged((PreciseCallState)msg.obj); 315 break; 316 case LISTEN_PRECISE_DATA_CONNECTION_STATE: 317 PhoneStateListener.this.onPreciseDataConnectionStateChanged( 318 (PreciseDataConnectionState)msg.obj); 319 break; 320 case LISTEN_DATA_CONNECTION_REAL_TIME_INFO: 321 PhoneStateListener.this.onDataConnectionRealTimeInfoChanged( 322 (DataConnectionRealTimeInfo)msg.obj); 323 break; 324 case LISTEN_VOLTE_STATE: 325 PhoneStateListener.this.onVoLteServiceStateChanged((VoLteServiceState)msg.obj); 326 break; 327 case LISTEN_OEM_HOOK_RAW_EVENT: 328 PhoneStateListener.this.onOemHookRawEvent((byte[])msg.obj); 329 break; 330 case LISTEN_CARRIER_NETWORK_CHANGE: 331 PhoneStateListener.this.onCarrierNetworkChange((boolean)msg.obj); 332 break; 333 334 } 335 } 336 }; 337 } 338 339 /** 340 * Callback invoked when device service state changes. 341 * 342 * @see ServiceState#STATE_EMERGENCY_ONLY 343 * @see ServiceState#STATE_IN_SERVICE 344 * @see ServiceState#STATE_OUT_OF_SERVICE 345 * @see ServiceState#STATE_POWER_OFF 346 */ 347 public void onServiceStateChanged(ServiceState serviceState) { 348 // default implementation empty 349 } 350 351 /** 352 * Callback invoked when network signal strength changes. 353 * 354 * @see ServiceState#STATE_EMERGENCY_ONLY 355 * @see ServiceState#STATE_IN_SERVICE 356 * @see ServiceState#STATE_OUT_OF_SERVICE 357 * @see ServiceState#STATE_POWER_OFF 358 * @deprecated Use {@link #onSignalStrengthsChanged(SignalStrength)} 359 */ 360 @Deprecated 361 public void onSignalStrengthChanged(int asu) { 362 // default implementation empty 363 } 364 365 /** 366 * Callback invoked when the message-waiting indicator changes. 367 */ 368 public void onMessageWaitingIndicatorChanged(boolean mwi) { 369 // default implementation empty 370 } 371 372 /** 373 * Callback invoked when the call-forwarding indicator changes. 374 */ 375 public void onCallForwardingIndicatorChanged(boolean cfi) { 376 // default implementation empty 377 } 378 379 /** 380 * Callback invoked when device cell location changes. 381 */ 382 public void onCellLocationChanged(CellLocation location) { 383 // default implementation empty 384 } 385 386 /** 387 * Callback invoked when device call state changes. 388 * @param state call state 389 * @param incomingNumber incoming call phone number. If application does not have 390 * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE} permission, an empty 391 * string will be passed as an argument. 392 * 393 * @see TelephonyManager#CALL_STATE_IDLE 394 * @see TelephonyManager#CALL_STATE_RINGING 395 * @see TelephonyManager#CALL_STATE_OFFHOOK 396 */ 397 public void onCallStateChanged(int state, String incomingNumber) { 398 // default implementation empty 399 } 400 401 /** 402 * Callback invoked when connection state changes. 403 * 404 * @see TelephonyManager#DATA_DISCONNECTED 405 * @see TelephonyManager#DATA_CONNECTING 406 * @see TelephonyManager#DATA_CONNECTED 407 * @see TelephonyManager#DATA_SUSPENDED 408 */ 409 public void onDataConnectionStateChanged(int state) { 410 // default implementation empty 411 } 412 413 /** 414 * same as above, but with the network type. Both called. 415 */ 416 public void onDataConnectionStateChanged(int state, int networkType) { 417 } 418 419 /** 420 * Callback invoked when data activity state changes. 421 * 422 * @see TelephonyManager#DATA_ACTIVITY_NONE 423 * @see TelephonyManager#DATA_ACTIVITY_IN 424 * @see TelephonyManager#DATA_ACTIVITY_OUT 425 * @see TelephonyManager#DATA_ACTIVITY_INOUT 426 * @see TelephonyManager#DATA_ACTIVITY_DORMANT 427 */ 428 public void onDataActivity(int direction) { 429 // default implementation empty 430 } 431 432 /** 433 * Callback invoked when network signal strengths changes. 434 * 435 * @see ServiceState#STATE_EMERGENCY_ONLY 436 * @see ServiceState#STATE_IN_SERVICE 437 * @see ServiceState#STATE_OUT_OF_SERVICE 438 * @see ServiceState#STATE_POWER_OFF 439 */ 440 public void onSignalStrengthsChanged(SignalStrength signalStrength) { 441 // default implementation empty 442 } 443 444 445 /** 446 * The Over The Air Service Provisioning (OTASP) has changed. Requires 447 * the READ_PHONE_STATE permission. 448 * @param otaspMode is integer <code>OTASP_UNKNOWN=1<code> 449 * means the value is currently unknown and the system should wait until 450 * <code>OTASP_NEEDED=2<code> or <code>OTASP_NOT_NEEDED=3<code> is received before 451 * making the decision to perform OTASP or not. 452 * 453 * @hide 454 */ 455 public void onOtaspChanged(int otaspMode) { 456 // default implementation empty 457 } 458 459 /** 460 * Callback invoked when a observed cell info has changed, 461 * or new cells have been added or removed. 462 * @param cellInfo is the list of currently visible cells. 463 */ 464 public void onCellInfoChanged(List<CellInfo> cellInfo) { 465 } 466 467 /** 468 * Callback invoked when precise device call state changes. 469 * 470 * @hide 471 */ 472 public void onPreciseCallStateChanged(PreciseCallState callState) { 473 // default implementation empty 474 } 475 476 /** 477 * Callback invoked when data connection state changes with precise information. 478 * 479 * @hide 480 */ 481 public void onPreciseDataConnectionStateChanged( 482 PreciseDataConnectionState dataConnectionState) { 483 // default implementation empty 484 } 485 486 /** 487 * Callback invoked when data connection state changes with precise information. 488 * 489 * @hide 490 */ 491 public void onDataConnectionRealTimeInfoChanged( 492 DataConnectionRealTimeInfo dcRtInfo) { 493 // default implementation empty 494 } 495 496 /** 497 * Callback invoked when the service state of LTE network 498 * related to the VoLTE service has changed. 499 * @param stateInfo is the current LTE network information 500 * @hide 501 */ 502 public void onVoLteServiceStateChanged(VoLteServiceState stateInfo) { 503 } 504 505 /** 506 * Callback invoked when OEM hook raw event is received. Requires 507 * the READ_PRIVILEGED_PHONE_STATE permission. 508 * @param rawData is the byte array of the OEM hook raw data. 509 * @hide 510 */ 511 public void onOemHookRawEvent(byte[] rawData) { 512 // default implementation empty 513 } 514 515 /** 516 * Callback invoked when telephony has received notice from a carrier 517 * app that a network action that could result in connectivity loss 518 * has been requested by an app using 519 * {@link android.telephony.TelephonyManager#notifyCarrierNetworkChange(boolean)} 520 * 521 * @param active Whether the carrier network change is or shortly 522 * will be active. This value is true to indicate 523 * showing alternative UI and false to stop. 524 * 525 * @hide 526 */ 527 public void onCarrierNetworkChange(boolean active) { 528 // default implementation empty 529 } 530 531 /** 532 * The callback methods need to be called on the handler thread where 533 * this object was created. If the binder did that for us it'd be nice. 534 */ 535 IPhoneStateListener callback = new IPhoneStateListener.Stub() { 536 public void onServiceStateChanged(ServiceState serviceState) { 537 Message.obtain(mHandler, LISTEN_SERVICE_STATE, 0, 0, serviceState).sendToTarget(); 538 } 539 540 public void onSignalStrengthChanged(int asu) { 541 Message.obtain(mHandler, LISTEN_SIGNAL_STRENGTH, asu, 0, null).sendToTarget(); 542 } 543 544 public void onMessageWaitingIndicatorChanged(boolean mwi) { 545 Message.obtain(mHandler, LISTEN_MESSAGE_WAITING_INDICATOR, mwi ? 1 : 0, 0, null) 546 .sendToTarget(); 547 } 548 549 public void onCallForwardingIndicatorChanged(boolean cfi) { 550 Message.obtain(mHandler, LISTEN_CALL_FORWARDING_INDICATOR, cfi ? 1 : 0, 0, null) 551 .sendToTarget(); 552 } 553 554 public void onCellLocationChanged(Bundle bundle) { 555 CellLocation location = CellLocation.newFromBundle(bundle); 556 Message.obtain(mHandler, LISTEN_CELL_LOCATION, 0, 0, location).sendToTarget(); 557 } 558 559 public void onCallStateChanged(int state, String incomingNumber) { 560 Message.obtain(mHandler, LISTEN_CALL_STATE, state, 0, incomingNumber).sendToTarget(); 561 } 562 563 public void onDataConnectionStateChanged(int state, int networkType) { 564 Message.obtain(mHandler, LISTEN_DATA_CONNECTION_STATE, state, networkType). 565 sendToTarget(); 566 } 567 568 public void onDataActivity(int direction) { 569 Message.obtain(mHandler, LISTEN_DATA_ACTIVITY, direction, 0, null).sendToTarget(); 570 } 571 572 public void onSignalStrengthsChanged(SignalStrength signalStrength) { 573 Message.obtain(mHandler, LISTEN_SIGNAL_STRENGTHS, 0, 0, signalStrength).sendToTarget(); 574 } 575 576 public void onOtaspChanged(int otaspMode) { 577 Message.obtain(mHandler, LISTEN_OTASP_CHANGED, otaspMode, 0).sendToTarget(); 578 } 579 580 public void onCellInfoChanged(List<CellInfo> cellInfo) { 581 Message.obtain(mHandler, LISTEN_CELL_INFO, 0, 0, cellInfo).sendToTarget(); 582 } 583 584 public void onPreciseCallStateChanged(PreciseCallState callState) { 585 Message.obtain(mHandler, LISTEN_PRECISE_CALL_STATE, 0, 0, callState).sendToTarget(); 586 } 587 588 public void onPreciseDataConnectionStateChanged( 589 PreciseDataConnectionState dataConnectionState) { 590 Message.obtain(mHandler, LISTEN_PRECISE_DATA_CONNECTION_STATE, 0, 0, 591 dataConnectionState).sendToTarget(); 592 } 593 594 public void onDataConnectionRealTimeInfoChanged( 595 DataConnectionRealTimeInfo dcRtInfo) { 596 Message.obtain(mHandler, LISTEN_DATA_CONNECTION_REAL_TIME_INFO, 0, 0, 597 dcRtInfo).sendToTarget(); 598 } 599 600 public void onVoLteServiceStateChanged(VoLteServiceState lteState) { 601 Message.obtain(mHandler, LISTEN_VOLTE_STATE, 0, 0, lteState).sendToTarget(); 602 } 603 604 public void onOemHookRawEvent(byte[] rawData) { 605 Message.obtain(mHandler, LISTEN_OEM_HOOK_RAW_EVENT, 0, 0, rawData).sendToTarget(); 606 } 607 608 public void onCarrierNetworkChange(boolean active) { 609 Message.obtain(mHandler, LISTEN_CARRIER_NETWORK_CHANGE, 0, 0, active).sendToTarget(); 610 } 611 }; 612 613 private void log(String s) { 614 Rlog.d(LOG_TAG, s); 615 } 616} 617