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