PhoneStateListener.java revision 54b6cfa9a9e5b861a9930af873580d6dc20f773c 
1package android.telephony;
2
3import android.os.Bundle;
4import android.os.Handler;
5import android.os.Message;
6import android.telephony.ServiceState;
7import android.telephony.CellLocation;
8import android.util.Log;
9
10import com.android.internal.telephony.IPhoneStateListener;
11
12/**
13 * A listener class for monitoring changes in specific telephony states
14 * on the device, including service state, signal strength, message
15 * waiting indicator (voicemail), and others.
16 * <p>
17 * Override the methods for the state that you wish to receive updates for, and
18 * pass your PhoneStateListener object, along with bitwise-or of the LISTEN_
19 * flags to {@link TelephonyManager#listen TelephonyManager.listen()}.
20 * <p>
21 * Note that access to some telephony information is
22 * permission-protected. Your application won't receive updates for protected
23 * information unless it has the appropriate permissions declared in
24 * its manifest file. Where permissions apply, they are noted in the
25 * appropriate LISTEN_ flags.
26 */
27public class PhoneStateListener {
28
29    /**
30     * Stop listening for updates.
31     */
32    public static final int LISTEN_NONE = 0;
33
34    /**
35     *  Listen for changes to the network service state (cellular).
36     *
37     *  @see #onServiceStateChanged
38     *  @see ServiceState
39     */
40    public static final int LISTEN_SERVICE_STATE                            = 0x00000001;
41
42    /**
43     * Listen for changes to the network signal strength (cellular).
44     * <p>
45     * Example: The status bar uses this to control the signal-strength
46     * icon.
47     *
48     * @see #onSignalStrengthChanged
49     */
50    public static final int LISTEN_SIGNAL_STRENGTH                          = 0x00000002;
51
52    /**
53     * Listen for changes to the message-waiting indicator.
54     * <p>
55     * Example: The status bar uses this to determine when to display the
56     * voicemail icon.
57     *
58     * @see #onMessageWaitingIndicatorChanged
59     */
60    public static final int LISTEN_MESSAGE_WAITING_INDICATOR                = 0x00000004;
61
62    /**
63     * Listen for changes to the call-forwarding indicator.
64     *
65     * @see #onCallForwardingIndicatorChanged
66     */
67    public static final int LISTEN_CALL_FORWARDING_INDICATOR                = 0x00000008;
68
69    /**
70     * Listen for changes to the device's cell location. Note that
71     * this will result in frequent callbacks to the listener.
72     * {@more}
73     * Requires Permission: {@link android.Manifest.permission#ACCESS_COARSE_LOCATION
74     * ACCESS_COARSE_LOCATION}
75     * <p>
76     * If you need regular location updates but want more control over
77     * the update interval or location precision, you can set up a listener
78     * through the {@link android.location.LocationManager location manager}
79     * instead.
80     *
81     * @see #onCellLocationChanged
82     */
83    public static final int LISTEN_CELL_LOCATION                            = 0x00000010;
84
85    /**
86     * Listen for changes to the device call state.
87     *
88     * @see #onCallStateChanged
89     */
90    public static final int LISTEN_CALL_STATE                               = 0x00000020;
91
92    /**
93     * Listen for changes to the data connection state (cellular).
94     *
95     * @see #onDataConnectionStateChanged
96     */
97    public static final int LISTEN_DATA_CONNECTION_STATE                    = 0x00000040;
98
99    /**
100     * Listen for changes to the direction of data traffic on the data
101     * connection (cellular).
102     *
103     * Example: The status bar uses this to display the appropriate
104     * data-traffic icon.
105     *
106     * @see #onDataActivity
107     */
108    public static final int LISTEN_DATA_ACTIVITY                            = 0x00000080;
109
110    public PhoneStateListener() {
111    }
112
113    /**
114     * Callback invoked when device service state changes.
115     *
116     * @see ServiceState#STATE_EMERGENCY_ONLY
117     * @see ServiceState#STATE_IN_SERVICE
118     * @see ServiceState#STATE_OUT_OF_SERVICE
119     * @see ServiceState#STATE_POWER_OFF
120     */
121    public void onServiceStateChanged(ServiceState serviceState) {
122        // default implementation empty
123    }
124
125    /**
126     * Callback invoked when network signal strength changes.
127     *
128     * @see ServiceState#STATE_EMERGENCY_ONLY
129     * @see ServiceState#STATE_IN_SERVICE
130     * @see ServiceState#STATE_OUT_OF_SERVICE
131     * @see ServiceState#STATE_POWER_OFF
132     */
133    public void onSignalStrengthChanged(int asu) {
134        // default implementation empty
135    }
136
137    /**
138     * Callback invoked when the message-waiting indicator changes.
139     */
140    public void onMessageWaitingIndicatorChanged(boolean mwi) {
141        // default implementation empty
142    }
143
144    /**
145     * Callback invoked when the call-forwarding indicator changes.
146     */
147    public void onCallForwardingIndicatorChanged(boolean cfi) {
148        // default implementation empty
149    }
150
151    /**
152     * Callback invoked when device cell location changes.
153     */
154    public void onCellLocationChanged(CellLocation location) {
155        // default implementation empty
156    }
157
158    /**
159     * Callback invoked when device call state changes.
160     *
161     * @see TelephonyManager#CALL_STATE_IDLE
162     * @see TelephonyManager#CALL_STATE_RINGING
163     * @see TelephonyManager#CALL_STATE_OFFHOOK
164     */
165    public void onCallStateChanged(int state, String incomingNumber) {
166        // default implementation empty
167    }
168
169    /**
170     * Callback invoked when connection state changes.
171     *
172     * @see TelephonyManager#DATA_DISCONNECTED
173     * @see TelephonyManager#DATA_CONNECTING
174     * @see TelephonyManager#DATA_CONNECTED
175     * @see TelephonyManager#DATA_SUSPENDED
176     */
177    public void onDataConnectionStateChanged(int state) {
178        // default implementation empty
179    }
180
181    /**
182     * Callback invoked when data activity state changes.
183     *
184     * @see TelephonyManager#DATA_ACTIVITY_NONE
185     * @see TelephonyManager#DATA_ACTIVITY_IN
186     * @see TelephonyManager#DATA_ACTIVITY_OUT
187     * @see TelephonyManager#DATA_ACTIVITY_INOUT
188     */
189    public void onDataActivity(int direction) {
190        // default implementation empty
191    }
192
193    /**
194     * The callback methods need to be called on the handler thread where
195     * this object was created.  If the binder did that for us it'd be nice.
196     */
197    IPhoneStateListener callback = new IPhoneStateListener.Stub() {
198        public void onServiceStateChanged(ServiceState serviceState) {
199            Message.obtain(mHandler, LISTEN_SERVICE_STATE, 0, 0, serviceState).sendToTarget();
200        }
201
202        public void onSignalStrengthChanged(int asu) {
203            Message.obtain(mHandler, LISTEN_SIGNAL_STRENGTH, asu, 0, null).sendToTarget();
204        }
205
206        public void onMessageWaitingIndicatorChanged(boolean mwi) {
207            Message.obtain(mHandler, LISTEN_MESSAGE_WAITING_INDICATOR, mwi ? 1 : 0, 0, null)
208                    .sendToTarget();
209        }
210
211        public void onCallForwardingIndicatorChanged(boolean cfi) {
212            Message.obtain(mHandler, LISTEN_CALL_FORWARDING_INDICATOR, cfi ? 1 : 0, 0, null)
213                    .sendToTarget();
214        }
215
216        public void onCellLocationChanged(Bundle bundle) {
217            CellLocation location = CellLocation.newFromBundle(bundle);
218            Message.obtain(mHandler, LISTEN_CELL_LOCATION, 0, 0, location).sendToTarget();
219        }
220
221        public void onCallStateChanged(int state, String incomingNumber) {
222            Message.obtain(mHandler, LISTEN_CALL_STATE, state, 0, incomingNumber).sendToTarget();
223        }
224
225        public void onDataConnectionStateChanged(int state) {
226            Message.obtain(mHandler, LISTEN_DATA_CONNECTION_STATE, state, 0, null).sendToTarget();
227        }
228
229        public void onDataActivity(int direction) {
230            Message.obtain(mHandler, LISTEN_DATA_ACTIVITY, direction, 0, null).sendToTarget();
231        }
232    };
233
234    Handler mHandler = new Handler() {
235        public void handleMessage(Message msg) {
236            //Log.d("TelephonyRegistry", "what=0x" + Integer.toHexString(msg.what) + " msg=" + msg);
237            switch (msg.what) {
238                case LISTEN_SERVICE_STATE:
239                    PhoneStateListener.this.onServiceStateChanged((ServiceState)msg.obj);
240                    break;
241                case LISTEN_SIGNAL_STRENGTH:
242                    PhoneStateListener.this.onSignalStrengthChanged(msg.arg1);
243                    break;
244                case LISTEN_MESSAGE_WAITING_INDICATOR:
245                    PhoneStateListener.this.onMessageWaitingIndicatorChanged(msg.arg1 != 0);
246                    break;
247                case LISTEN_CALL_FORWARDING_INDICATOR:
248                    PhoneStateListener.this.onCallForwardingIndicatorChanged(msg.arg1 != 0);
249                    break;
250                case LISTEN_CELL_LOCATION:
251                    PhoneStateListener.this.onCellLocationChanged((CellLocation)msg.obj);
252                    break;
253                case LISTEN_CALL_STATE:
254                    PhoneStateListener.this.onCallStateChanged(msg.arg1, (String)msg.obj);
255                    break;
256                case LISTEN_DATA_CONNECTION_STATE:
257                    PhoneStateListener.this.onDataConnectionStateChanged(msg.arg1);
258                    break;
259                case LISTEN_DATA_ACTIVITY:
260                    PhoneStateListener.this.onDataActivity(msg.arg1);
261                    break;
262            }
263        }
264    };
265}
266