TelephonyManager.java revision f013e1afd1e68af5e3b868c26a653bbfb39538f8
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 com.android.internal.telephony.*; 20 21import java.util.ArrayList; 22import java.util.List; 23 24import android.annotation.SdkConstant.SdkConstantType; 25import android.annotation.SdkConstant; 26import android.content.Context; 27import android.os.Bundle; 28import android.os.RemoteException; 29import android.os.ServiceManager; 30import android.os.SystemProperties; 31 32 33/** 34 * Provides access to information about the telephony services on 35 * the device. Applications can use the methods in this class to 36 * determine telephony services and states, as well as to access some 37 * types of subscriber information. Applications can also register 38 * a listener to receive notification of telephony state changes. 39 * <p> 40 * You do not instantiate this class directly; instead, you retrieve 41 * a reference to an instance through 42 * {@link android.content.Context#getSystemService 43 * Context.getSystemService(Context.TELEPHONY_SERVICE)}. 44 * <p> 45 * Note that acess to some telephony information is 46 * permission-protected. Your application cannot access the protected 47 * information unless it has the appropriate permissions declared in 48 * its manifest file. Where permissions apply, they are noted in the 49 * the methods through which you access the protected information. 50 */ 51public class TelephonyManager { 52 private static final String TAG = "TelephonyManager"; 53 54 private Context mContext; 55 private ITelephonyRegistry mRegistry; 56 57 /** @hide */ 58 public TelephonyManager(Context context) { 59 mContext = context; 60 mRegistry = ITelephonyRegistry.Stub.asInterface(ServiceManager.getService( 61 "telephony.registry")); 62 } 63 64 /** @hide */ 65 private TelephonyManager() { 66 } 67 68 private static TelephonyManager sInstance = new TelephonyManager(); 69 70 /** @hide */ 71 public static TelephonyManager getDefault() { 72 return sInstance; 73 } 74 75 76 // 77 // Broadcast Intent actions 78 // 79 80 /** 81 * Broadcast intent action indicating that the call state (cellular) 82 * on the device has changed. 83 * 84 * <p> 85 * The {@link #EXTRA_STATE} extra indicates the new call state. 86 * If the new state is RINGING, a second extra 87 * {@link #EXTRA_INCOMING_NUMBER} provides the incoming phone number as 88 * a String. 89 * 90 * <p class="note"> 91 * Requires the READ_PHONE_STATE permission. 92 * 93 * <p class="note"> 94 * This was a {@link android.content.Context#sendStickyBroadcast sticky} 95 * broadcast in version 1.0, but it is no longer sticky. 96 * Instead, use {@link #getCallState} to synchronously query the current call state. 97 * 98 * @see #EXTRA_STATE 99 * @see #EXTRA_INCOMING_NUMBER 100 * @see #getCallState 101 * 102 * @hide pending API Council approval 103 */ 104 @SdkConstant(SdkConstantType.BROADCAST_INTENT_ACTION) 105 public static final String ACTION_PHONE_STATE_CHANGED = 106 "android.intent.action.PHONE_STATE"; 107 108 /** 109 * The lookup key used with the {@link #ACTION_PHONE_STATE_CHANGED} broadcast 110 * for a String containing the new call state. 111 * 112 * @see #EXTRA_STATE_IDLE 113 * @see #EXTRA_STATE_RINGING 114 * @see #EXTRA_STATE_OFFHOOK 115 * 116 * <p class="note"> 117 * Retrieve with 118 * {@link android.content.Intent#getStringExtra(String)}. 119 * 120 * @hide pending API Council approval 121 */ 122 public static final String EXTRA_STATE = Phone.STATE_KEY; 123 124 /** 125 * Value used with {@link #EXTRA_STATE} corresponding to 126 * {@link #CALL_STATE_IDLE}. 127 * 128 * @hide pending API Council approval 129 */ 130 public static final String EXTRA_STATE_IDLE = Phone.State.IDLE.toString(); 131 132 /** 133 * Value used with {@link #EXTRA_STATE} corresponding to 134 * {@link #CALL_STATE_RINGING}. 135 * 136 * @hide pending API Council approval 137 */ 138 public static final String EXTRA_STATE_RINGING = Phone.State.RINGING.toString(); 139 140 /** 141 * Value used with {@link #EXTRA_STATE} corresponding to 142 * {@link #CALL_STATE_OFFHOOK}. 143 * 144 * @hide pending API Council approval 145 */ 146 public static final String EXTRA_STATE_OFFHOOK = Phone.State.OFFHOOK.toString(); 147 148 /** 149 * The lookup key used with the {@link #ACTION_PHONE_STATE_CHANGED} broadcast 150 * for a String containing the incoming phone number. 151 * Only valid when the new call state is RINGING. 152 * 153 * <p class="note"> 154 * Retrieve with 155 * {@link android.content.Intent#getStringExtra(String)}. 156 * 157 * @hide pending API Council approval 158 */ 159 public static final String EXTRA_INCOMING_NUMBER = "incoming_number"; 160 161 162 // 163 // 164 // Device Info 165 // 166 // 167 168 /** 169 * Returns the software version number for the device, for example, 170 * the IMEI/SV for GSM phones. 171 * 172 * <p>Requires Permission: 173 * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE} 174 */ 175 public String getDeviceSoftwareVersion() { 176 try { 177 return getSubscriberInfo().getDeviceSvn(); 178 } catch (RemoteException ex) { 179 } 180 return null; 181 } 182 183 /** 184 * Returns the unique device ID, for example,the IMEI for GSM 185 * phones. 186 * 187 * <p>Requires Permission: 188 * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE} 189 */ 190 public String getDeviceId() { 191 try { 192 return getSubscriberInfo().getDeviceId(); 193 } catch (RemoteException ex) { 194 } 195 return null; 196 } 197 198 /** 199 * Returns the current location of the device. 200 * 201 * <p>Requires Permission: {@link android.Manifest.permission#ACCESS_COARSE_LOCATION 202 * ACCESS_COARSE_LOCATION}. 203 */ 204 public CellLocation getCellLocation() { 205 try { 206 Bundle bundle = getITelephony().getCellLocation(); 207 return CellLocation.newFromBundle(bundle); 208 } catch (RemoteException ex) { 209 } 210 return null; 211 } 212 213 /** 214 * Enables location update notifications. {@link PhoneStateListener#onCellLocationChanged 215 * PhoneStateListener.onCellLocationChanged} will be called on location updates. 216 * 217 * <p>Requires Permission: {@link android.Manifest.permission#CONTROL_LOCATION_UPDATES 218 * CONTROL_LOCATION_UPDATES} 219 * 220 * @hide 221 */ 222 public void enableLocationUpdates() { 223 try { 224 getITelephony().enableLocationUpdates(); 225 } catch (RemoteException ex) { 226 } 227 } 228 229 /** 230 * Disables location update notifications. {@link PhoneStateListener#onCellLocationChanged 231 * PhoneStateListener.onCellLocationChanged} will be called on location updates. 232 * 233 * <p>Requires Permission: {@link android.Manifest.permission#CONTROL_LOCATION_UPDATES 234 * CONTROL_LOCATION_UPDATES} 235 * 236 * @hide 237 */ 238 public void disableLocationUpdates() { 239 try { 240 getITelephony().disableLocationUpdates(); 241 } catch (RemoteException ex) { 242 } 243 } 244 245 /** 246 * Returns the neighboring cell information of the device. 247 * 248 * @return List of NeighboringCellInfo or null if info unavailable. 249 * 250 * <p>Requires Permission: 251 * (@link android.Manifest.permission#ACCESS_COARSE_UPDATES} 252 */ 253 public List<NeighboringCellInfo> getNeighboringCellInfo() { 254 try { 255 ITelephony tel = getITelephony(); 256 if (tel != null) { 257 return tel.getNeighboringCellInfo(); 258 } 259 } catch (RemoteException ex) { 260 } 261 return null; 262 263 } 264 265 /** 266 * No phone module 267 */ 268 public static final int PHONE_TYPE_NONE = 0; 269 270 /** 271 * GSM phone 272 */ 273 public static final int PHONE_TYPE_GSM = 1; 274 275 /** 276 * Returns a constant indicating the device phone type. 277 * 278 * @see #PHONE_TYPE_NONE 279 * @see #PHONE_TYPE_GSM 280 */ 281 public int getPhoneType() { 282 // in the future, we should really check this 283 return PHONE_TYPE_GSM; 284 } 285 286 // 287 // 288 // Current Network 289 // 290 // 291 292 /** 293 * Returns the alphabetic name of current registered operator. 294 * <p> 295 * Availability: Only when user is registered to a network 296 */ 297 public String getNetworkOperatorName() { 298 return SystemProperties.get(TelephonyProperties.PROPERTY_OPERATOR_ALPHA); 299 } 300 301 /** 302 * Returns the numeric name (MCC+MNC) of current registered operator. 303 * <p> 304 * Availability: Only when user is registered to a network 305 */ 306 public String getNetworkOperator() { 307 return SystemProperties.get(TelephonyProperties.PROPERTY_OPERATOR_NUMERIC); 308 } 309 310 /** 311 * Returns true if the device is considered roaming on the current 312 * network, for GSM purposes. 313 * <p> 314 * Availability: Only when user registered to a network 315 */ 316 public boolean isNetworkRoaming() { 317 return "true".equals(SystemProperties.get(TelephonyProperties.PROPERTY_OPERATOR_ISROAMING)); 318 } 319 320 /** 321 * Returns the ISO country code equivilent of the current registered 322 * operator's MCC (Mobile Country Code). 323 * <p> 324 * Availability: Only when user is registered to a network 325 */ 326 public String getNetworkCountryIso() { 327 return SystemProperties.get(TelephonyProperties.PROPERTY_OPERATOR_ISO_COUNTRY); 328 } 329 330 /** Network type is unknown */ 331 public static final int NETWORK_TYPE_UNKNOWN = 0; 332 /** Current network is GPRS */ 333 public static final int NETWORK_TYPE_GPRS = 1; 334 /** Current network is EDGE */ 335 public static final int NETWORK_TYPE_EDGE = 2; 336 /** Current network is UMTS */ 337 public static final int NETWORK_TYPE_UMTS = 3; 338 339 /** 340 * Returns a constant indicating the radio technology (network type) 341 * currently in use on the device. 342 * @return the network type 343 * 344 * @see #NETWORK_TYPE_UNKNOWN 345 * @see #NETWORK_TYPE_GPRS 346 * @see #NETWORK_TYPE_EDGE 347 * @see #NETWORK_TYPE_UMTS 348 */ 349 public int getNetworkType() { 350 String prop = SystemProperties.get(TelephonyProperties.PROPERTY_DATA_NETWORK_TYPE); 351 if ("GPRS".equals(prop)) { 352 return NETWORK_TYPE_GPRS; 353 } 354 else if ("EDGE".equals(prop)) { 355 return NETWORK_TYPE_EDGE; 356 } 357 else if ("UMTS".equals(prop)) { 358 return NETWORK_TYPE_UMTS; 359 } 360 else { 361 return NETWORK_TYPE_UNKNOWN; 362 } 363 } 364 365 /** 366 * Returns a string representation of the radio technology (network type) 367 * currently in use on the device. 368 * @return the name of the radio technology 369 * 370 * @hide pending API council review 371 */ 372 public String getNetworkTypeName() { 373 switch (getNetworkType()) { 374 case NETWORK_TYPE_GPRS: 375 return "GPRS"; 376 case NETWORK_TYPE_EDGE: 377 return "EDGE"; 378 case NETWORK_TYPE_UMTS: 379 return "UMTS"; 380 default: 381 return "UNKNOWN"; 382 } 383 } 384 385 // 386 // 387 // SIM Card 388 // 389 // 390 391 /** SIM card state: Unknown. Signifies that the SIM is in transition 392 * between states. For example, when the user inputs the SIM pin 393 * under PIN_REQUIRED state, a query for sim status returns 394 * this state before turning to SIM_STATE_READY. */ 395 public static final int SIM_STATE_UNKNOWN = 0; 396 /** SIM card state: no SIM card is available in the device */ 397 public static final int SIM_STATE_ABSENT = 1; 398 /** SIM card state: Locked: requires the user's SIM PIN to unlock */ 399 public static final int SIM_STATE_PIN_REQUIRED = 2; 400 /** SIM card state: Locked: requires the user's SIM PUK to unlock */ 401 public static final int SIM_STATE_PUK_REQUIRED = 3; 402 /** SIM card state: Locked: requries a network PIN to unlock */ 403 public static final int SIM_STATE_NETWORK_LOCKED = 4; 404 /** SIM card state: Ready */ 405 public static final int SIM_STATE_READY = 5; 406 407 /** 408 * Returns a constant indicating the state of the 409 * device SIM card. 410 * 411 * @see #SIM_STATE_UNKNOWN 412 * @see #SIM_STATE_ABSENT 413 * @see #SIM_STATE_PIN_REQUIRED 414 * @see #SIM_STATE_PUK_REQUIRED 415 * @see #SIM_STATE_NETWORK_LOCKED 416 * @see #SIM_STATE_READY 417 */ 418 public int getSimState() { 419 String prop = SystemProperties.get(TelephonyProperties.PROPERTY_SIM_STATE); 420 if ("ABSENT".equals(prop)) { 421 return SIM_STATE_ABSENT; 422 } 423 else if ("PIN_REQUIRED".equals(prop)) { 424 return SIM_STATE_PIN_REQUIRED; 425 } 426 else if ("PUK_REQUIRED".equals(prop)) { 427 return SIM_STATE_PUK_REQUIRED; 428 } 429 else if ("NETWORK_LOCKED".equals(prop)) { 430 return SIM_STATE_NETWORK_LOCKED; 431 } 432 else if ("READY".equals(prop)) { 433 return SIM_STATE_READY; 434 } 435 else { 436 return SIM_STATE_UNKNOWN; 437 } 438 } 439 440 /** 441 * Returns the MCC+MNC (mobile country code + mobile network code) of the 442 * provider of the SIM. 5 or 6 decimal digits. 443 * <p> 444 * Availability: SIM state must be {@link #SIM_STATE_READY} 445 * 446 * @see #getSimState 447 */ 448 public String getSimOperator() { 449 return SystemProperties.get(TelephonyProperties.PROPERTY_SIM_OPERATOR_NUMERIC); 450 } 451 452 /** 453 * Returns the Service Provider Name (SPN). 454 * <p> 455 * Availability: SIM state must be {@link #SIM_STATE_READY} 456 * 457 * @see #getSimState 458 */ 459 public String getSimOperatorName() { 460 return SystemProperties.get(TelephonyProperties.PROPERTY_SIM_OPERATOR_ALPHA); 461 } 462 463 /** 464 * Returns the ISO country code equivalent for the SIM provider's country code. 465 */ 466 public String getSimCountryIso() { 467 return SystemProperties.get(TelephonyProperties.PROPERTY_SIM_OPERATOR_ISO_COUNTRY); 468 } 469 470 /** 471 * Returns the serial number of the SIM, if applicable. 472 * <p> 473 * Requires Permission: 474 * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE} 475 */ 476 public String getSimSerialNumber() { 477 try { 478 return getSubscriberInfo().getSimSerialNumber(); 479 } catch (RemoteException ex) { 480 } 481 return null; 482 } 483 484 // 485 // 486 // Subscriber Info 487 // 488 // 489 490 /** 491 * Returns the unique subscriber ID, for example, the IMSI for a GSM phone. 492 * <p> 493 * Requires Permission: 494 * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE} 495 */ 496 public String getSubscriberId() { 497 try { 498 return getSubscriberInfo().getSubscriberId(); 499 } catch (RemoteException ex) { 500 } 501 return null; 502 } 503 504 /** 505 * Returns the phone number string for line 1, for example, the MSISDN 506 * for a GSM phone. 507 * <p> 508 * Requires Permission: 509 * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE} 510 */ 511 public String getLine1Number() { 512 try { 513 return getSubscriberInfo().getLine1Number(); 514 } catch (RemoteException ex) { 515 } 516 return null; 517 } 518 519 /** 520 * Returns the alphabetic identifier associated with the line 1 number. 521 * <p> 522 * Requires Permission: 523 * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE} 524 * @hide 525 * nobody seems to call this. 526 */ 527 public String getLine1AlphaTag() { 528 try { 529 return getSubscriberInfo().getLine1AlphaTag(); 530 } catch (RemoteException ex) { 531 } 532 return null; 533 } 534 535 /** 536 * Returns the voice mail number. 537 * <p> 538 * Requires Permission: 539 * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE} 540 */ 541 public String getVoiceMailNumber() { 542 try { 543 return getSubscriberInfo().getVoiceMailNumber(); 544 } catch (RemoteException ex) { 545 } 546 return null; 547 } 548 549 /** 550 * Retrieves the alphabetic identifier associated with the voice 551 * mail number. 552 * <p> 553 * Requires Permission: 554 * {@link android.Manifest.permission#READ_PHONE_STATE READ_PHONE_STATE} 555 */ 556 public String getVoiceMailAlphaTag() { 557 try { 558 return getSubscriberInfo().getVoiceMailAlphaTag(); 559 } catch (RemoteException ex) { 560 } 561 return null; 562 } 563 564 private IPhoneSubInfo getSubscriberInfo() { 565 // get it each time because that process crashes a lot 566 return IPhoneSubInfo.Stub.asInterface(ServiceManager.getService("iphonesubinfo")); 567 } 568 569 570 /** Device call state: No activity. */ 571 public static final int CALL_STATE_IDLE = 0; 572 /** Device call state: Ringing. A new call arrived and is 573 * ringing or waiting. In the latter case, another call is 574 * already active. */ 575 public static final int CALL_STATE_RINGING = 1; 576 /** Device call state: Off-hook. At least one call exists 577 * that is dialing, active, or on hold, and no calls are ringing 578 * or waiting. */ 579 public static final int CALL_STATE_OFFHOOK = 2; 580 581 /** 582 * Returns a constant indicating the call state (cellular) on the device. 583 */ 584 public int getCallState() { 585 try { 586 return getITelephony().getCallState(); 587 } catch (RemoteException ex) { 588 // the phone process is restarting. 589 return CALL_STATE_IDLE; 590 } 591 } 592 593 /** Data connection activity: No traffic. */ 594 public static final int DATA_ACTIVITY_NONE = 0x00000000; 595 /** Data connection activity: Currently receiving IP PPP traffic. */ 596 public static final int DATA_ACTIVITY_IN = 0x00000001; 597 /** Data connection activity: Currently sending IP PPP traffic. */ 598 public static final int DATA_ACTIVITY_OUT = 0x00000002; 599 /** Data connection activity: Currently both sending and receiving 600 * IP PPP traffic. */ 601 public static final int DATA_ACTIVITY_INOUT = DATA_ACTIVITY_IN | DATA_ACTIVITY_OUT; 602 603 /** 604 * Returns a constant indicating the type of activity on a data connection 605 * (cellular). 606 * 607 * @see #DATA_ACTIVITY_NONE 608 * @see #DATA_ACTIVITY_IN 609 * @see #DATA_ACTIVITY_OUT 610 * @see #DATA_ACTIVITY_INOUT 611 */ 612 public int getDataActivity() { 613 try { 614 return getITelephony().getDataActivity(); 615 } catch (RemoteException ex) { 616 // the phone process is restarting. 617 return DATA_ACTIVITY_NONE; 618 } 619 } 620 621 /** Data connection state: Disconnected. IP traffic not available. */ 622 public static final int DATA_DISCONNECTED = 0; 623 /** Data connection state: Currently setting up a data connection. */ 624 public static final int DATA_CONNECTING = 1; 625 /** Data connection state: Connected. IP traffic should be available. */ 626 public static final int DATA_CONNECTED = 2; 627 /** Data connection state: Suspended. The connection is up, but IP 628 * traffic is temporarily unavailable. For example, in a 2G network, 629 * data activity may be suspended when a voice call arrives. */ 630 public static final int DATA_SUSPENDED = 3; 631 632 /** 633 * Returns a constant indicating the current data connection state 634 * (cellular). 635 * 636 * @see #DATA_DISCONNECTED 637 * @see #DATA_CONNECTING 638 * @see #DATA_CONNECTED 639 * @see #DATA_SUSPENDED 640 */ 641 public int getDataState() { 642 try { 643 return getITelephony().getDataState(); 644 } catch (RemoteException ex) { 645 // the phone process is restarting. 646 return DATA_DISCONNECTED; 647 } 648 } 649 650 private ITelephony getITelephony() { 651 return ITelephony.Stub.asInterface(ServiceManager.getService(Context.TELEPHONY_SERVICE)); 652 } 653 654 // 655 // 656 // PhoneStateListener 657 // 658 // 659 660 /** 661 * Registers a listener object to receive notification of changes 662 * in specified telephony states. 663 * <p> 664 * To register a listener, pass a {@link PhoneStateListener} 665 * and specify at least one telephony state of interest in 666 * the events argument. 667 * 668 * At registration, and when a specified telephony state 669 * changes, the telephony manager invokes the appropriate 670 * callback method on the listener object and passes the 671 * current (udpated) values. 672 * <p> 673 * To unregister a listener, pass the listener object and set the 674 * events argument to 675 * {@link PhoneStateListener#LISTEN_NONE LISTEN_NONE} (0). 676 * 677 * @param listener The {@link PhoneStateListener} object to register 678 * (or unregister) 679 * @param events The telephony state(s) of interest to the listener, 680 * as a bitwise-OR combination of {@link PhoneStateListener} 681 * LISTEN_ flags. 682 */ 683 public void listen(PhoneStateListener listener, int events) { 684 String pkgForDebug = mContext != null ? mContext.getPackageName() : "<unknown>"; 685 try { 686 mRegistry.listen(pkgForDebug, listener.callback, events, true); 687 } catch (RemoteException ex) { 688 // system process dead 689 } 690 } 691} 692