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