Phone.java revision 9066cfe9886ac131c34d59ed0e2d287b0e3c0087
1/* 2 * Copyright (C) 2007 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 com.android.internal.telephony; 18 19import android.content.Context; 20import android.os.Handler; 21import android.os.Message; 22import android.telephony.CellLocation; 23import android.telephony.ServiceState; 24import com.android.internal.telephony.gsm.NetworkInfo; 25import com.android.internal.telephony.gsm.PdpConnection; 26import com.android.internal.telephony.test.SimulatedRadioControl; 27 28import java.util.List; 29 30/** 31 * Internal interface used to control the phone; SDK developers cannot 32 * obtain this interface. 33 * 34 * {@hide} 35 * 36 */ 37public interface Phone { 38 39 /** used to enable additional debug messages */ 40 static final boolean DEBUG_PHONE = true; 41 42 43 /** 44 * The phone state. One of the following:<p> 45 * <ul> 46 * <li>IDLE = no phone activity</li> 47 * <li>RINGING = a phone call is ringing or call waiting. 48 * In the latter case, another call is active as well</li> 49 * <li>OFFHOOK = The phone is off hook. At least one call 50 * exists that is dialing, active or holding and no calls are 51 * ringing or waiting.</li> 52 * </ul> 53 */ 54 enum State { 55 IDLE, RINGING, OFFHOOK; 56 }; 57 58 /** 59 * The state of a data connection. 60 * <ul> 61 * <li>CONNECTED = IP traffic should be available</li> 62 * <li>CONNECTING = Currently setting up data connection</li> 63 * <li>DISCONNECTED = IP not available</li> 64 * <li>SUSPENDED = connection is created but IP traffic is 65 * temperately not available. i.e. voice call is in place 66 * in 2G network</li> 67 * </ul> 68 */ 69 enum DataState { 70 CONNECTED, CONNECTING, DISCONNECTED, SUSPENDED; 71 }; 72 73 enum DataActivityState { 74 /** 75 * The state of a data activity. 76 * <ul> 77 * <li>NONE = No traffic</li> 78 * <li>DATAIN = Receiving IP ppp traffic</li> 79 * <li>DATAOUT = Sending IP ppp traffic</li> 80 * <li>DATAINANDOUT = Both receiving and sending IP ppp traffic</li> 81 * </ul> 82 */ 83 NONE, DATAIN, DATAOUT, DATAINANDOUT; 84 }; 85 86 enum SuppService { 87 UNKNOWN, SWITCH, SEPARATE, TRANSFER, CONFERENCE, REJECT, HANGUP; 88 }; 89 90 static final String STATE_KEY = "state"; 91 static final String PHONE_NAME_KEY = "phoneName"; 92 static final String FAILURE_REASON_KEY = "reason"; 93 static final String STATE_CHANGE_REASON_KEY = "reason"; 94 static final String DATA_APN_TYPE_KEY = "apnType"; 95 static final String DATA_APN_KEY = "apn"; 96 static final String DATA_IFACE_NAME_KEY = "iface"; 97 static final String NETWORK_UNAVAILABLE_KEY = "networkUnvailable"; 98 99 /** 100 * APN types for data connections. These are usage categories for an APN 101 * entry. One APN entry may support multiple APN types, eg, a single APN 102 * may service regular internet traffic ("default") as well as MMS-specific 103 * connections.<br/> 104 * APN_TYPE_ALL is a special type to indicate that this APN entry can 105 * service all data connections. 106 */ 107 static final String APN_TYPE_ALL = "*"; 108 /** APN type for default data traffic */ 109 static final String APN_TYPE_DEFAULT = "default"; 110 /** APN type for MMS traffic */ 111 static final String APN_TYPE_MMS = "mms"; 112 113 // "Features" accessible through the connectivity manager 114 static final String FEATURE_ENABLE_MMS = "enableMMS"; 115 116 /** 117 * Return codes for <code>enableApnType()</code> 118 */ 119 static final int APN_ALREADY_ACTIVE = 0; 120 static final int APN_REQUEST_STARTED = 1; 121 static final int APN_TYPE_NOT_AVAILABLE = 2; 122 static final int APN_REQUEST_FAILED = 3; 123 124 125 /** 126 * Optional reasons for disconnect and connect 127 */ 128 static final String REASON_ROAMING_ON = "roamingOn"; 129 static final String REASON_ROAMING_OFF = "roamingOff"; 130 static final String REASON_DATA_DISABLED = "dataDisabled"; 131 static final String REASON_DATA_ENABLED = "dataEnabled"; 132 static final String REASON_GPRS_ATTACHED = "gprsAttached"; 133 static final String REASON_GPRS_DETACHED = "gprsDetached"; 134 static final String REASON_APN_CHANGED = "apnChanged"; 135 static final String REASON_APN_SWITCHED = "apnSwitched"; 136 static final String REASON_RESTORE_DEFAULT_APN = "restoreDefaultApn"; 137 static final String REASON_RADIO_TURNED_OFF = "radioTurnedOff"; 138 static final String REASON_PDP_RESET = "pdpReset"; 139 static final String REASON_VOICE_CALL_ENDED = "2GVoiceCallEnded"; 140 static final String REASON_VOICE_CALL_STARTED = "2GVoiceCallStarted"; 141 142 // Used for band mode selction methods 143 static final int BM_UNSPECIFIED = 0; // selected by baseband automatically 144 static final int BM_EURO_BAND = 1; // GSM-900 / DCS-1800 / WCDMA-IMT-2000 145 static final int BM_US_BAND = 2; // GSM-850 / PCS-1900 / WCDMA-850 / WCDMA-PCS-1900 146 static final int BM_JPN_BAND = 3; // WCDMA-800 / WCDMA-IMT-2000 147 static final int BM_AUS_BAND = 4; // GSM-900 / DCS-1800 / WCDMA-850 / WCDMA-IMT-2000 148 static final int BM_AUS2_BAND = 5; // GSM-900 / DCS-1800 / WCDMA-850 149 static final int BM_BOUNDARY = 6; // upper band boundary 150 151 // Used for preferred network type 152 static final int NT_AUTO_TYPE = 0; // WCDMA preferred (auto mode) 153 static final int NT_GSM_TYPE = 1; // GSM only 154 static final int NT_WCDMA_TYPE = 2; // WCDMA only 155 156 /** 157 * Get the current ServiceState. Use 158 * <code>registerForServiceStateChanged</code> to be informed of 159 * updates. 160 */ 161 ServiceState getServiceState(); 162 163 /** 164 * Get the current CellLocation. 165 */ 166 CellLocation getCellLocation(); 167 168 /** 169 * Get the current DataState. No change notification exists at this 170 * interface -- use 171 * {@link com.android.internal.telephony.PhoneStateIntentReceiver PhoneStateIntentReceiver} instead. 172 */ 173 DataState getDataConnectionState(); 174 175 /** 176 * Get the current DataActivityState. No change notification exists at this 177 * interface -- use 178 * {@link TelephonyManager} instead. 179 */ 180 DataActivityState getDataActivityState(); 181 182 /** 183 * Gets the context for the phone, as set at initialization time. 184 */ 185 Context getContext(); 186 187 /** 188 * Get current coarse-grained voice call state. 189 * Use {@link #registerForPhoneStateChanged(Handler, int, Object) 190 * registerForPhoneStateChanged()} for change notification. <p> 191 * If the phone has an active call and call waiting occurs, 192 * then the phone state is RINGING not OFFHOOK 193 * <strong>Note:</strong> 194 * This registration point provides notification of finer-grained 195 * changes.<p> 196 * 197 */ 198 State getState(); 199 200 /** 201 * Returns a string identifier for this phone interface for parties 202 * outside the phone app process. 203 * @return The string name. 204 */ 205 String getPhoneName(); 206 207 /** 208 * Returns an array of string identifiers for the APN types serviced by the 209 * currently active or last connected APN. 210 * @return The string array. 211 */ 212 String[] getActiveApnTypes(); 213 214 /** 215 * Returns a string identifier for currently active or last connected APN. 216 * @return The string name. 217 */ 218 String getActiveApn(); 219 220 /** 221 * Get current signal strength. No change notification available on this 222 * interface. Use <code>PhoneStateNotifier</code> or an equivalent. 223 * An ASU is 0-31 or -1 if unknown (for GSM, dBm = -113 - 2 * asu). 224 * The following special values are defined:</p> 225 * <ul><li>0 means "-113 dBm or less".</li> 226 * <li>31 means "-51 dBm or greater".</li></ul> 227 * 228 * @return Current signal strength in ASU's. 229 */ 230 int getSignalStrengthASU(); 231 232 /** 233 * Notifies when a previously untracked non-ringing/waiting connection has appeared. 234 * This is likely due to some other entity (eg, SIM card application) initiating a call. 235 */ 236 void registerForUnknownConnection(Handler h, int what, Object obj); 237 238 /** 239 * Unregisters for unknown connection notifications. 240 */ 241 void unregisterForUnknownConnection(Handler h); 242 243 /** 244 * Notifies when any aspect of the voice call state changes. 245 * Resulting events will have an AsyncResult in <code>Message.obj</code>. 246 * AsyncResult.userData will be set to the obj argument here. 247 * The <em>h</em> parameter is held only by a weak reference. 248 */ 249 void registerForPhoneStateChanged(Handler h, int what, Object obj); 250 251 /** 252 * Unregisters for voice call state change notifications. 253 * Extraneous calls are tolerated silently. 254 */ 255 void unregisterForPhoneStateChanged(Handler h); 256 257 258 /** 259 * Notifies when a new ringing or waiting connection has appeared.<p> 260 * 261 * Messages received from this: 262 * Message.obj will be an AsyncResult 263 * AsyncResult.userObj = obj 264 * AsyncResult.result = a Connection. <p> 265 * Please check Connection.isRinging() to make sure the Connection 266 * has not dropped since this message was posted. 267 * If Connection.isRinging() is true, then 268 * Connection.getCall() == Phone.getRingingCall() 269 */ 270 void registerForNewRingingConnection(Handler h, int what, Object obj); 271 272 /** 273 * Unregisters for new ringing connection notification. 274 * Extraneous calls are tolerated silently 275 */ 276 277 void unregisterForNewRingingConnection(Handler h); 278 279 /** 280 * Notifies when an incoming call rings.<p> 281 * 282 * Messages received from this: 283 * Message.obj will be an AsyncResult 284 * AsyncResult.userObj = obj 285 * AsyncResult.result = a Connection. <p> 286 */ 287 void registerForIncomingRing(Handler h, int what, Object obj); 288 289 /** 290 * Unregisters for ring notification. 291 * Extraneous calls are tolerated silently 292 */ 293 294 void unregisterForIncomingRing(Handler h); 295 296 297 /** 298 * Notifies when a voice connection has disconnected, either due to local 299 * or remote hangup or error. 300 * 301 * Messages received from this will have the following members:<p> 302 * <ul><li>Message.obj will be an AsyncResult</li> 303 * <li>AsyncResult.userObj = obj</li> 304 * <li>AsyncResult.result = a Connection object that is 305 * no longer connected.</li></ul> 306 */ 307 void registerForDisconnect(Handler h, int what, Object obj); 308 309 /** 310 * Unregisters for voice disconnection notification. 311 * Extraneous calls are tolerated silently 312 */ 313 void unregisterForDisconnect(Handler h); 314 315 316 /** 317 * Register for notifications of initiation of a new MMI code request. 318 * MMI codes for GSM are discussed in 3GPP TS 22.030.<p> 319 * 320 * Example: If Phone.dial is called with "*#31#", then the app will 321 * be notified here.<p> 322 * 323 * The returned <code>Message.obj</code> will contain an AsyncResult. 324 * 325 * <code>obj.result</code> will be an "MmiCode" object. 326 */ 327 void registerForMmiInitiate(Handler h, int what, Object obj); 328 329 /** 330 * Unregisters for new MMI initiate notification. 331 * Extraneous calls are tolerated silently 332 */ 333 void unregisterForMmiInitiate(Handler h); 334 335 /** 336 * Register for notifications that an MMI request has completed 337 * its network activity and is in its final state. This may mean a state 338 * of COMPLETE, FAILED, or CANCELLED. 339 * 340 * <code>Message.obj</code> will contain an AsyncResult. 341 * <code>obj.result</code> will be an "MmiCode" object 342 */ 343 void registerForMmiComplete(Handler h, int what, Object obj); 344 345 /** 346 * Unregisters for MMI complete notification. 347 * Extraneous calls are tolerated silently 348 */ 349 void unregisterForMmiComplete(Handler h); 350 351 /** 352 * Returns a list of MMI codes that are pending. (They have initiated 353 * but have not yet completed). 354 * Presently there is only ever one. 355 * Use <code>registerForMmiInitiate</code> 356 * and <code>registerForMmiComplete</code> for change notification. 357 */ 358 public List<? extends MmiCode> getPendingMmiCodes(); 359 360 /** 361 * Sends user response to a USSD REQUEST message. An MmiCode instance 362 * representing this response is sent to handlers registered with 363 * registerForMmiInitiate. 364 * 365 * @param ussdMessge Message to send in the response. 366 */ 367 public void sendUssdResponse(String ussdMessge); 368 369 /** 370 * Register for ServiceState changed. 371 * Message.obj will contain an AsyncResult. 372 * AsyncResult.result will be a ServiceState instance 373 */ 374 void registerForServiceStateChanged(Handler h, int what, Object obj); 375 376 /** 377 * Unregisters for ServiceStateChange notification. 378 * Extraneous calls are tolerated silently 379 */ 380 void unregisterForServiceStateChanged(Handler h); 381 382 /** 383 * Register for Supplementary Service notifications from the network. 384 * Message.obj will contain an AsyncResult. 385 * AsyncResult.result will be a SuppServiceNotification instance. 386 * 387 * @param h Handler that receives the notification message. 388 * @param what User-defined message code. 389 * @param obj User object. 390 */ 391 void registerForSuppServiceNotification(Handler h, int what, Object obj); 392 393 /** 394 * Unregisters for Supplementary Service notifications. 395 * Extraneous calls are tolerated silently 396 * 397 * @param h Handler to be removed from the registrant list. 398 */ 399 void unregisterForSuppServiceNotification(Handler h); 400 401 /** 402 * Register for notifications when a supplementary service attempt fails. 403 * Message.obj will contain an AsyncResult. 404 * 405 * @param h Handler that receives the notification message. 406 * @param what User-defined message code. 407 * @param obj User object. 408 */ 409 void registerForSuppServiceFailed(Handler h, int what, Object obj); 410 411 /** 412 * Unregister for notifications when a supplementary service attempt fails. 413 * Extraneous calls are tolerated silently 414 * 415 * @param h Handler to be removed from the registrant list. 416 */ 417 void unregisterForSuppServiceFailed(Handler h); 418 419 /** 420 * Returns SIM record load state. Use 421 * <code>getSimCard().registerForReady()</code> for change notification. 422 * 423 * @return true if records from the SIM have been loaded and are 424 * available (if applicable). If not applicable to the underlying 425 * technology, returns true as well. 426 */ 427 boolean getSimRecordsLoaded(); 428 429 /** 430 * Returns the SIM card interface for this phone, or null 431 * if not applicable to underlying technology. 432 */ 433 SimCard getSimCard(); 434 435 /** 436 * Answers a ringing or waiting call. Active calls, if any, go on hold. 437 * Answering occurs asynchronously, and final notification occurs via 438 * {@link #registerForPhoneStateChanged(android.os.Handler, int, 439 * java.lang.Object) registerForPhoneStateChanged()}. 440 * 441 * @exception CallStateException when no call is ringing or waiting 442 */ 443 void acceptCall() throws CallStateException; 444 445 /** 446 * Reject (ignore) a ringing call. In GSM, this means UDUB 447 * (User Determined User Busy). Reject occurs asynchronously, 448 * and final notification occurs via 449 * {@link #registerForPhoneStateChanged(android.os.Handler, int, 450 * java.lang.Object) registerForPhoneStateChanged()}. 451 * 452 * @exception CallStateException when no call is ringing or waiting 453 */ 454 void rejectCall() throws CallStateException; 455 456 /** 457 * Places any active calls on hold, and makes any held calls 458 * active. Switch occurs asynchronously and may fail. 459 * Final notification occurs via 460 * {@link #registerForPhoneStateChanged(android.os.Handler, int, 461 * java.lang.Object) registerForPhoneStateChanged()}. 462 * 463 * @exception CallStateException if a call is ringing, waiting, or 464 * dialing/alerting. In these cases, this operation may not be performed. 465 */ 466 void switchHoldingAndActive() throws CallStateException; 467 468 /** 469 * Whether or not the phone can conference in the current phone 470 * state--that is, one call holding and one call active. 471 * @return true if the phone can conference; false otherwise. 472 */ 473 boolean canConference(); 474 475 /** 476 * Conferences holding and active. Conference occurs asynchronously 477 * and may fail. Final notification occurs via 478 * {@link #registerForPhoneStateChanged(android.os.Handler, int, 479 * java.lang.Object) registerForPhoneStateChanged()}. 480 * 481 * @exception CallStateException if canConference() would return false. 482 * In these cases, this operation may not be performed. 483 */ 484 void conference() throws CallStateException; 485 486 /** 487 * Whether or not the phone can do explicit call transfer in the current 488 * phone state--that is, one call holding and one call active. 489 * @return true if the phone can do explicit call transfer; false otherwise. 490 */ 491 boolean canTransfer(); 492 493 /** 494 * Connects the two calls and disconnects the subscriber from both calls 495 * Explicit Call Transfer occurs asynchronously 496 * and may fail. Final notification occurs via 497 * {@link #registerForPhoneStateChanged(android.os.Handler, int, 498 * java.lang.Object) registerForPhoneStateChanged()}. 499 * 500 * @exception CallStateException if canTransfer() would return false. 501 * In these cases, this operation may not be performed. 502 */ 503 void explicitCallTransfer() throws CallStateException; 504 505 /** 506 * Clears all DISCONNECTED connections from Call connection lists. 507 * Calls that were in the DISCONNECTED state become idle. This occurs 508 * synchronously. 509 */ 510 void clearDisconnected(); 511 512 513 /** 514 * Gets the foreground call object, which represents all connections that 515 * are dialing or active (all connections 516 * that have their audio path connected).<p> 517 * 518 * The foreground call is a singleton object. It is constant for the life 519 * of this phone. It is never null.<p> 520 * 521 * The foreground call will only ever be in one of these states: 522 * IDLE, ACTIVE, DIALING, ALERTING, or DISCONNECTED. 523 * 524 * State change notification is available via 525 * {@link #registerForPhoneStateChanged(android.os.Handler, int, 526 * java.lang.Object) registerForPhoneStateChanged()}. 527 */ 528 Call getForegroundCall(); 529 530 /** 531 * Gets the background call object, which represents all connections that 532 * are holding (all connections that have been accepted or connected, but 533 * do not have their audio path connected). <p> 534 * 535 * The background call is a singleton object. It is constant for the life 536 * of this phone object . It is never null.<p> 537 * 538 * The background call will only ever be in one of these states: 539 * IDLE, HOLDING or DISCONNECTED. 540 * 541 * State change notification is available via 542 * {@link #registerForPhoneStateChanged(android.os.Handler, int, 543 * java.lang.Object) registerForPhoneStateChanged()}. 544 */ 545 Call getBackgroundCall(); 546 547 /** 548 * Gets the ringing call object, which represents an incoming 549 * connection (if present) that is pending answer/accept. (This connection 550 * may be RINGING or WAITING, and there may be only one.)<p> 551 552 * The ringing call is a singleton object. It is constant for the life 553 * of this phone. It is never null.<p> 554 * 555 * The ringing call will only ever be in one of these states: 556 * IDLE, INCOMING, WAITING or DISCONNECTED. 557 * 558 * State change notification is available via 559 * {@link #registerForPhoneStateChanged(android.os.Handler, int, 560 * java.lang.Object) registerForPhoneStateChanged()}. 561 */ 562 Call getRingingCall(); 563 564 /** 565 * Initiate a new voice connection. This happens asynchronously, so you 566 * cannot assume the audio path is connected (or a call index has been 567 * assigned) until PhoneStateChanged notification has occurred. 568 * 569 * @exception CallStateException if a new outgoing call is not currently 570 * possible because no more call slots exist or a call exists that is 571 * dialing, alerting, ringing, or waiting. Other errors are 572 * handled asynchronously. 573 */ 574 Connection dial(String dialString) throws CallStateException; 575 576 /** 577 * Handles PIN MMI commands (PIN/PIN2/PUK/PUK2), which are initiated 578 * without SEND (so <code>dial</code> is not appropriate). 579 * 580 * @param dialString the MMI command to be executed. 581 * @return true if MMI command is executed. 582 */ 583 boolean handlePinMmi(String dialString); 584 585 /** 586 * Handles in-call MMI commands. While in a call, or while receiving a 587 * call, use this to execute MMI commands. 588 * see 3GPP 20.030, section 6.5.5.1 for specs on the allowed MMI commands. 589 * 590 * @param command the MMI command to be executed. 591 * @return true if the MMI command is executed. 592 * @throws CallStateException 593 */ 594 boolean handleInCallMmiCommands(String command) throws CallStateException; 595 596 /** 597 * Play a DTMF tone on the active call. Ignored if there is no active call. 598 * @param c should be one of 0-9, '*' or '#'. Other values will be 599 * silently ignored. 600 */ 601 void sendDtmf(char c); 602 603 /** 604 * Start to paly a DTMF tone on the active call. Ignored if there is no active call 605 * or there is a playing DTMF tone. 606 * @param c should be one of 0-9, '*' or '#'. Other values will be 607 * silently ignored. 608 */ 609 void startDtmf(char c); 610 611 /** 612 * Stop the playing DTMF tone. Ignored if there is no playing DTMF 613 * tone or no active call. 614 */ 615 void stopDtmf(); 616 617 618 /** 619 * Sets the radio power on/off state (off is sometimes 620 * called "airplane mode"). Current state can be gotten via 621 * {@link #getServiceState()}.{@link 622 * android.telephony.ServiceState#getState() getState()}. 623 * <strong>Note: </strong>This request is asynchronous. 624 * getServiceState().getState() will not change immediately after this call. 625 * registerForServiceStateChanged() to find out when the 626 * request is complete. 627 * 628 * @param power true means "on", false means "off". 629 */ 630 void setRadioPower(boolean power); 631 632 /** 633 * Get voice message waiting indicator status. No change notification 634 * available on this interface. Use PhoneStateNotifier or similar instead. 635 * 636 * @return true if there is a voice message waiting 637 */ 638 boolean getMessageWaitingIndicator(); 639 640 /** 641 * Get voice call forwarding indicator status. No change notification 642 * available on this interface. Use PhoneStateNotifier or similar instead. 643 * 644 * @return true if there is a voice call forwarding 645 */ 646 boolean getCallForwardingIndicator(); 647 648 /** 649 * Get the line 1 phone number (MSISDN).<p> 650 * 651 * @return phone number. May return null if not 652 * available or the SIM is not ready 653 */ 654 String getLine1Number(); 655 656 /** 657 * Returns the alpha tag associated with the msisdn number. 658 * If there is no alpha tag associated or the record is not yet available, 659 * returns a default localized string. <p> 660 */ 661 String getLine1AlphaTag(); 662 663 /** 664 * Sets the MSISDN phone number in the SIM card. 665 * 666 * @param alphaTag the alpha tag associated with the MSISDN phone number 667 * (see getMsisdnAlphaTag) 668 * @param number the new MSISDN phone number to be set on the SIM. 669 * @param onComplete a callback message when the action is completed. 670 */ 671 void setLine1Number(String alphaTag, String number, Message onComplete); 672 673 /** 674 * Get the voice mail access phone number. Typically dialed when the 675 * user holds the "1" key in the phone app. May return null if not 676 * available or the SIM is not ready.<p> 677 */ 678 String getVoiceMailNumber(); 679 680 /** 681 * Returns the alpha tag associated with the voice mail number. 682 * If there is no alpha tag associated or the record is not yet available, 683 * returns a default localized string. <p> 684 * 685 * Please use this value instead of some other localized string when 686 * showing a name for this number in the UI. For example, call log 687 * entries should show this alpha tag. <p> 688 * 689 * Usage of this alpha tag in the UI is a common carrier requirement. 690 */ 691 String getVoiceMailAlphaTag(); 692 693 /** 694 * setVoiceMailNumber 695 * sets the voicemail number in the SIM card. 696 * 697 * @param alphaTag the alpha tag associated with the voice mail number 698 * (see getVoiceMailAlphaTag) 699 * @param voiceMailNumber the new voicemail number to be set on the SIM. 700 * @param onComplete a callback message when the action is completed. 701 */ 702 void setVoiceMailNumber(String alphaTag, 703 String voiceMailNumber, 704 Message onComplete); 705 706 /** 707 * getCallForwardingOptions 708 * gets a call forwarding option. The return value of 709 * ((AsyncResult)onComplete.obj) is an array of CallForwardInfo. 710 * 711 * @param commandInterfaceCFReason is one of the valid call forwarding 712 * CF_REASONS, as defined in 713 * <code>com.android.internal.telephony.gsm.CommandsInterface</code> 714 * @param onComplete a callback message when the action is completed. 715 * @see com.android.internal.telephony.gsm.CallForwardInfo for details. 716 */ 717 void getCallForwardingOption(int commandInterfaceCFReason, 718 Message onComplete); 719 720 /** 721 * setCallForwardingOptions 722 * sets a call forwarding option. 723 * 724 * @param commandInterfaceCFReason is one of the valid call forwarding 725 * CF_REASONS, as defined in 726 * <code>com.android.internal.telephony.gsm.CommandsInterface</code> 727 * @param commandInterfaceCFAction is one of the valid call forwarding 728 * CF_ACTIONS, as defined in 729 * <code>com.android.internal.telephony.gsm.CommandsInterface</code> 730 * @param dialingNumber is the target phone number to forward calls to 731 * @param timerSeconds is used by CFNRy to indicate the timeout before 732 * forwarding is attempted. 733 * @param onComplete a callback message when the action is completed. 734 */ 735 void setCallForwardingOption(int commandInterfaceCFReason, 736 int commandInterfaceCFAction, 737 String dialingNumber, 738 int timerSeconds, 739 Message onComplete); 740 741 /** 742 * getOutgoingCallerIdDisplay 743 * gets outgoing caller id display. The return value of 744 * ((AsyncResult)onComplete.obj) is an array of int, with a length of 2. 745 * 746 * @param onComplete a callback message when the action is completed. 747 * @see com.android.internal.telephony.gsm.CommandsInterface.getCLIR for details. 748 */ 749 void getOutgoingCallerIdDisplay(Message onComplete); 750 751 /** 752 * setOutgoingCallerIdDisplay 753 * sets a call forwarding option. 754 * 755 * @param commandInterfaceCLIRMode is one of the valid call CLIR 756 * modes, as defined in 757 * <code>com.android.internal.telephony.gsm.CommandsInterface</code> 758 * @param onComplete a callback message when the action is completed. 759 */ 760 void setOutgoingCallerIdDisplay(int commandInterfaceCLIRMode, 761 Message onComplete); 762 763 /** 764 * getCallWaiting 765 * gets call waiting activation state. The return value of 766 * ((AsyncResult)onComplete.obj) is an array of int, with a length of 1. 767 * 768 * @param onComplete a callback message when the action is completed. 769 * @see com.android.internal.telephony.gsm.CommandsInterface.queryCallWaiting for details. 770 */ 771 void getCallWaiting(Message onComplete); 772 773 /** 774 * setCallWaiting 775 * sets a call forwarding option. 776 * 777 * @param enable is a boolean representing the state that you are 778 * requesting, true for enabled, false for disabled. 779 * @param onComplete a callback message when the action is completed. 780 */ 781 void setCallWaiting(boolean enable, Message onComplete); 782 783 /** 784 * Scan available networks. This method is asynchronous; . 785 * On completion, <code>response.obj</code> is set to an AsyncResult with 786 * one of the following members:.<p> 787 *<ul> 788 * <li><code>response.obj.result</code> will be a <code>List</code> of 789 * <code>com.android.internal.telephony.gsm.NetworkInfo</code> objects, or</li> 790 * <li><code>response.obj.exception</code> will be set with an exception 791 * on failure.</li> 792 * </ul> 793 */ 794 void getAvailableNetworks(Message response); 795 796 /** 797 * Switches network selection mode to "automatic", re-scanning and 798 * re-selecting a network if appropriate. 799 * 800 * @param response The message to dispatch when the network selection 801 * is complete. 802 * 803 * @see #selectNetworkManually(com.android.internal.telephony.gsm.NetworkInfo, 804 * android.os.Message ) 805 */ 806 void setNetworkSelectionModeAutomatic(Message response); 807 808 /** 809 * Manually selects a network. <code>response</code> is 810 * dispatched when this is complete. <code>response.obj</code> will be 811 * an AsyncResult, and <code>response.obj.exception</code> will be non-null 812 * on failure. 813 * 814 * @see #setNetworkSelectionModeAutomatic(Message) 815 */ 816 void selectNetworkManually(NetworkInfo network, 817 Message response); 818 819 /** 820 * Requests to set the preferred network type for searching and registering 821 * (CS/PS domain, RAT, and operation mode) 822 * @param networkType one of NT_*_TYPE 823 * @param response is callback message 824 */ 825 void setPreferredNetworkType(int networkType, Message response); 826 827 /** 828 * Query the preferred network type setting 829 * 830 * @param response is callback message to report one of NT_*_TYPE 831 */ 832 void getPreferredNetworkType(Message response); 833 834 /** 835 * Query neighboring cell IDs. <code>response</code> is dispatched when 836 * this is complete. <code>response.obj</code> will be an AsyncResult, 837 * and <code>response.obj.exception</code> will be non-null on failure. 838 * On success, <code>AsyncResult.result</code> will be a <code>String[]</code> 839 * containing the neighboring cell IDs. Index 0 will contain the count 840 * of available cell IDs. Cell IDs are in hexadecimal format. 841 * 842 * @param response callback message that is dispatched when the query 843 * completes. 844 */ 845 void getNeighboringCids(Message response); 846 847 /** 848 * Sets an event to be fired when the telephony system processes 849 * a post-dial character on an outgoing call.<p> 850 * 851 * Messages of type <code>what</code> will be sent to <code>h</code>. 852 * The <code>obj</code> field of these Message's will be instances of 853 * <code>AsyncResult</code>. <code>Message.obj.result</code> will be 854 * a Connection object.<p> 855 * 856 * Message.arg1 will be the post dial character being processed, 857 * or 0 ('\0') if end of string.<p> 858 * 859 * If Connection.getPostDialState() == WAIT, 860 * the application must call 861 * {@link com.android.internal.telephony.Connection#proceedAfterWaitChar() 862 * Connection.proceedAfterWaitChar()} or 863 * {@link com.android.internal.telephony.Connection#cancelPostDial() 864 * Connection.cancelPostDial()} 865 * for the telephony system to continue playing the post-dial 866 * DTMF sequence.<p> 867 * 868 * If Connection.getPostDialState() == WILD, 869 * the application must call 870 * {@link com.android.internal.telephony.Connection#proceedAfterWildChar 871 * Connection.proceedAfterWildChar()} 872 * or 873 * {@link com.android.internal.telephony.Connection#cancelPostDial() 874 * Connection.cancelPostDial()} 875 * for the telephony system to continue playing the 876 * post-dial DTMF sequence.<p> 877 * 878 * Only one post dial character handler may be set. <p> 879 * Calling this method with "h" equal to null unsets this handler.<p> 880 */ 881 void setOnPostDialCharacter(Handler h, int what, Object obj); 882 883 884 /** 885 * Mutes or unmutes the microphone for the active call. The microphone 886 * is automatically unmuted if a call is answered, dialed, or resumed 887 * from a holding state. 888 * 889 * @param muted true to mute the microphone, 890 * false to activate the microphone. 891 */ 892 893 void setMute(boolean muted); 894 895 /** 896 * Gets current mute status. Use 897 * {@link #registerForPhoneStateChanged(android.os.Handler, int, 898 * java.lang.Object) registerForPhoneStateChanged()} 899 * as a change notifcation, although presently phone state changed is not 900 * fired when setMute() is called. 901 * 902 * @return true is muting, false is unmuting 903 */ 904 boolean getMute(); 905 906 /** 907 * Invokes RIL_REQUEST_OEM_HOOK_RAW on RIL implementation. 908 * 909 * @param data The data for the request. 910 * @param response <strong>On success</strong>, 911 * (byte[])(((AsyncResult)response.obj).result) 912 * <strong>On failure</strong>, 913 * (((AsyncResult)response.obj).result) == null and 914 * (((AsyncResult)response.obj).exception) being an instance of 915 * com.android.internal.telephony.gsm.CommandException 916 * 917 * @see #invokeOemRilRequestRaw(byte[], android.os.Message) 918 */ 919 void invokeOemRilRequestRaw(byte[] data, Message response); 920 921 /** 922 * Invokes RIL_REQUEST_OEM_HOOK_Strings on RIL implementation. 923 * 924 * @param strings The strings to make available as the request data. 925 * @param response <strong>On success</strong>, "response" bytes is 926 * made available as: 927 * (String[])(((AsyncResult)response.obj).result). 928 * <strong>On failure</strong>, 929 * (((AsyncResult)response.obj).result) == null and 930 * (((AsyncResult)response.obj).exception) being an instance of 931 * com.android.internal.telephony.gsm.CommandException 932 * 933 * @see #invokeOemRilRequestStrings(java.lang.String[], android.os.Message) 934 */ 935 void invokeOemRilRequestStrings(String[] strings, Message response); 936 937 /** 938 * Get the current active PDP context list 939 * 940 * @param response <strong>On success</strong>, "response" bytes is 941 * made available as: 942 * (String[])(((AsyncResult)response.obj).result). 943 * <strong>On failure</strong>, 944 * (((AsyncResult)response.obj).result) == null and 945 * (((AsyncResult)response.obj).exception) being an instance of 946 * com.android.internal.telephony.gsm.CommandException 947 */ 948 void getPdpContextList(Message response); 949 950 /** 951 * Get current mutiple PDP link status 952 * 953 * @return list of pdp link connections 954 */ 955 List<PdpConnection> getCurrentPdpList (); 956 957 /** 958 * Udpate LAC and CID in service state for currnet GSM netowrk registration 959 * 960 * If get different LAC and/or CID, notifyServiceState will be sent 961 * 962 * @param 963 * <strong>On failure</strong>, 964 * (((AsyncResult)response.obj).result) == null and 965 * (((AsyncResult)response.obj).exception) being an instance of 966 * com.android.internal.telephony.gsm.CommandException 967 */ 968 void updateServiceLocation(Message response); 969 970 /** 971 * Enable location update notifications. 972 */ 973 void enableLocationUpdates(); 974 975 /** 976 * Disable location update notifications. 977 */ 978 void disableLocationUpdates(); 979 980 /** 981 * For unit tests; don't send notifications to "Phone" 982 * mailbox registrants if true. 983 */ 984 void setUnitTestMode(boolean f); 985 986 /** 987 * @return true If unit test mode is enabled 988 */ 989 boolean getUnitTestMode(); 990 991 /** 992 * Assign a specified band for RF configuration. 993 * 994 * @param bandMode one of BM_*_BAND 995 * @param response is callback message 996 */ 997 void setBandMode(int bandMode, Message response); 998 999 /** 1000 * Query the list of band mode supported by RF. 1001 * 1002 * @param response is callback message 1003 * ((AsyncResult)response.obj).result is an int[] with every 1004 * element representing one avialable BM_*_BAND 1005 */ 1006 void queryAvailableBandMode(Message response); 1007 1008 /** 1009 * @return true if enable data connection on roaming 1010 */ 1011 boolean getDataRoamingEnabled(); 1012 1013 /** 1014 * @param enable set true if enable data connection on roaming 1015 */ 1016 void setDataRoamingEnabled(boolean enable); 1017 1018 /** 1019 * If this is a simulated phone interface, returns a SimulatedRadioControl. 1020 * @ return A SimulatedRadioControl if this is a simulated interface; 1021 * otherwise, null. 1022 */ 1023 SimulatedRadioControl getSimulatedRadioControl(); 1024 1025 /** 1026 * Allow mobile data connections. 1027 * @return {@code true} if the operation started successfully 1028 * <br/>{@code false} if it 1029 * failed immediately.<br/> 1030 * Even in the {@code true} case, it may still fail later 1031 * during setup, in which case an asynchronous indication will 1032 * be supplied. 1033 */ 1034 boolean enableDataConnectivity(); 1035 1036 /** 1037 * Disallow mobile data connections, and terminate any that 1038 * are in progress. 1039 * @return {@code true} if the operation started successfully 1040 * <br/>{@code false} if it 1041 * failed immediately.<br/> 1042 * Even in the {@code true} case, it may still fail later 1043 * during setup, in which case an asynchronous indication will 1044 * be supplied. 1045 */ 1046 boolean disableDataConnectivity(); 1047 1048 /** 1049 * Enables the specified APN type. Only works for "special" APN types, 1050 * i.e., not the default APN. 1051 * @param type The desired APN type. Cannot be {@link #APN_TYPE_DEFAULT}. 1052 * @return <code>APN_ALREADY_ACTIVE</code> if the current APN 1053 * services the requested type.<br/> 1054 * <code>APN_TYPE_NOT_AVAILABLE</code> if the carrier does not 1055 * support the requested APN.<br/> 1056 * <code>APN_REQUEST_STARTED</code> if the request has been initiated.<br/> 1057 * <code>APN_REQUEST_FAILED</code> if the request was invalid.<br/> 1058 * A <code>ACTION_ANY_DATA_CONNECTION_STATE_CHANGED</code> broadcast will 1059 * indicate connection state progress. 1060 */ 1061 int enableApnType(String type); 1062 1063 /** 1064 * Disables the specified APN type, and switches back to the default APN, 1065 * if necessary. Switching to the default APN will not happen if default 1066 * data traffic has been explicitly disabled via a call to {@link #disableDataConnectivity}. 1067 * <p/>Only works for "special" APN types, 1068 * i.e., not the default APN. 1069 * @param type The desired APN type. Cannot be {@link #APN_TYPE_DEFAULT}. 1070 * @return <code>APN_ALREADY_ACTIVE</code> if the default APN 1071 * is already active.<br/> 1072 * <code>APN_REQUEST_STARTED</code> if the request to switch to the default 1073 * APN has been initiated.<br/> 1074 * <code>APN_REQUEST_FAILED</code> if the request was invalid.<br/> 1075 * A <code>ACTION_ANY_DATA_CONNECTION_STATE_CHANGED</code> broadcast will 1076 * indicate connection state progress. 1077 */ 1078 int disableApnType(String type); 1079 1080 /** 1081 * Report on whether data connectivity is allowed. 1082 */ 1083 boolean isDataConnectivityPossible(); 1084 1085 /** 1086 * Returns the name of the network interface used by the specified APN type. 1087 */ 1088 String getInterfaceName(String apnType); 1089 1090 /** 1091 * Returns the IP address of the network interface used by the specified 1092 * APN type. 1093 */ 1094 String getIpAddress(String apnType); 1095 1096 /** 1097 * Returns the gateway for the network interface used by the specified APN 1098 * type. 1099 */ 1100 String getGateway(String apnType); 1101 1102 /** 1103 * Returns the DNS servers for the network interface used by the specified 1104 * APN type. 1105 */ 1106 public String[] getDnsServers(String apnType); 1107 1108 /** 1109 * Retrieves the unique device ID, e.g., IMEI for GSM phones. 1110 */ 1111 String getDeviceId(); 1112 1113 /** 1114 * Retrieves the software version number for the device, e.g., IMEI/SV 1115 * for GSM phones. 1116 */ 1117 String getDeviceSvn(); 1118 1119 /** 1120 * Retrieves the unique sbuscriber ID, e.g., IMSI for GSM phones. 1121 */ 1122 String getSubscriberId(); 1123 1124 /** 1125 * Retrieves the serial number of the SIM, if applicable. 1126 */ 1127 String getSimSerialNumber(); 1128} 1129