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