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