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