PhoneStateListener.java revision c5ac15a3e11c03951e269b243674858411204b67 
1/*
2 * Copyright (C) 2008 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.telephony;
18
19import android.os.Bundle;
20import android.os.Handler;
21import android.os.Message;
22import android.telephony.ServiceState;
23import android.telephony.SignalStrength;
24import android.telephony.CellLocation;
25import android.telephony.CellInfo;
26import android.telephony.Rlog;
27import android.telephony.PreciseCallState;
28import android.telephony.PreciseDataConnectionState;
29
30import com.android.internal.telephony.IPhoneStateListener;
31
32import java.util.List;
33
34/**
35 * A listener class for monitoring changes in specific telephony states
36 * on the device, including service state, signal strength, message
37 * waiting indicator (voicemail), and others.
38 * <p>
39 * Override the methods for the state that you wish to receive updates for, and
40 * pass your PhoneStateListener object, along with bitwise-or of the LISTEN_
41 * flags to {@link TelephonyManager#listen TelephonyManager.listen()}.
42 * <p>
43 * Note that access to some telephony information is
44 * permission-protected. Your application won't receive updates for protected
45 * information unless it has the appropriate permissions declared in
46 * its manifest file. Where permissions apply, they are noted in the
47 * appropriate LISTEN_ flags.
48 */
49public class PhoneStateListener {
50
51    /**
52     * Stop listening for updates.
53     */
54    public static final int LISTEN_NONE = 0;
55
56    /**
57     *  Listen for changes to the network service state (cellular).
58     *
59     *  @see #onServiceStateChanged
60     *  @see ServiceState
61     */
62    public static final int LISTEN_SERVICE_STATE                            = 0x00000001;
63
64    /**
65     * Listen for changes to the network signal strength (cellular).
66     * {@more}
67     * Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE
68     * READ_PHONE_STATE}
69     * <p>
70     *
71     * @see #onSignalStrengthChanged
72     *
73     * @deprecated by {@link #LISTEN_SIGNAL_STRENGTHS}
74     */
75    @Deprecated
76    public static final int LISTEN_SIGNAL_STRENGTH                          = 0x00000002;
77
78    /**
79     * Listen for changes to the message-waiting indicator.
80     * {@more}
81     * Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE
82     * READ_PHONE_STATE}
83     * <p>
84     * Example: The status bar uses this to determine when to display the
85     * voicemail icon.
86     *
87     * @see #onMessageWaitingIndicatorChanged
88     */
89    public static final int LISTEN_MESSAGE_WAITING_INDICATOR                = 0x00000004;
90
91    /**
92     * Listen for changes to the call-forwarding indicator.
93     * {@more}
94     * Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE
95     * READ_PHONE_STATE}
96     * @see #onCallForwardingIndicatorChanged
97     */
98    public static final int LISTEN_CALL_FORWARDING_INDICATOR                = 0x00000008;
99
100    /**
101     * Listen for changes to the device's cell location. Note that
102     * this will result in frequent callbacks to the listener.
103     * {@more}
104     * Requires Permission: {@link android.Manifest.permission#ACCESS_COARSE_LOCATION
105     * ACCESS_COARSE_LOCATION}
106     * <p>
107     * If you need regular location updates but want more control over
108     * the update interval or location precision, you can set up a listener
109     * through the {@link android.location.LocationManager location manager}
110     * instead.
111     *
112     * @see #onCellLocationChanged
113     */
114    public static final int LISTEN_CELL_LOCATION                            = 0x00000010;
115
116    /**
117     * Listen for changes to the device call state.
118     * {@more}
119     * Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE
120     * READ_PHONE_STATE}
121     * @see #onCallStateChanged
122     */
123    public static final int LISTEN_CALL_STATE                               = 0x00000020;
124
125    /**
126     * Listen for changes to the data connection state (cellular).
127     *
128     * @see #onDataConnectionStateChanged
129     */
130    public static final int LISTEN_DATA_CONNECTION_STATE                    = 0x00000040;
131
132    /**
133     * Listen for changes to the direction of data traffic on the data
134     * connection (cellular).
135     * {@more}
136     * Requires Permission: {@link android.Manifest.permission#READ_PHONE_STATE
137     * READ_PHONE_STATE}
138     * Example: The status bar uses this to display the appropriate
139     * data-traffic icon.
140     *
141     * @see #onDataActivity
142     */
143    public static final int LISTEN_DATA_ACTIVITY                            = 0x00000080;
144
145    /**
146     * Listen for changes to the network signal strengths (cellular).
147     * <p>
148     * Example: The status bar uses this to control the signal-strength
149     * icon.
150     *
151     * @see #onSignalStrengthsChanged
152     */
153    public static final int LISTEN_SIGNAL_STRENGTHS                         = 0x00000100;
154
155    /**
156     * Listen for changes to OTASP mode.
157     *
158     * @see #onOtaspChanged
159     * @hide
160     */
161    public static final int LISTEN_OTASP_CHANGED                            = 0x00000200;
162
163    /**
164     * Listen for changes to observed cell info.
165     *
166     * @see #onCellInfoChanged
167     */
168    public static final int LISTEN_CELL_INFO = 0x00000400;
169
170    /**
171     * Listen for precise changes and fails to the device calls (cellular).
172     * {@more}
173     * Requires Permission: {@link android.Manifest.permission#READ_PRECISE_PHONE_STATE
174     * READ_PRECISE_PHONE_STATE}
175     *
176     * @hide
177     */
178    public static final int LISTEN_PRECISE_CALL_STATE                       = 0x00000800;
179
180    /**
181     * Listen for precise changes and fails on the data connection (cellular).
182     * {@more}
183     * Requires Permission: {@link android.Manifest.permission#READ_PRECISE_PHONE_STATE
184     * READ_PRECISE_PHONE_STATE}
185     *
186     * @see #onPreciseDataConnectionStateChanged
187     * @hide
188     */
189    public static final int LISTEN_PRECISE_DATA_CONNECTION_STATE            = 0x00001000;
190
191    public PhoneStateListener() {
192    }
193
194    /**
195     * Callback invoked when device service state changes.
196     *
197     * @see ServiceState#STATE_EMERGENCY_ONLY
198     * @see ServiceState#STATE_IN_SERVICE
199     * @see ServiceState#STATE_OUT_OF_SERVICE
200     * @see ServiceState#STATE_POWER_OFF
201     */
202    public void onServiceStateChanged(ServiceState serviceState) {
203        // default implementation empty
204    }
205
206    /**
207     * Callback invoked when network signal strength changes.
208     *
209     * @see ServiceState#STATE_EMERGENCY_ONLY
210     * @see ServiceState#STATE_IN_SERVICE
211     * @see ServiceState#STATE_OUT_OF_SERVICE
212     * @see ServiceState#STATE_POWER_OFF
213     * @deprecated Use {@link #onSignalStrengthsChanged(SignalStrength)}
214     */
215    @Deprecated
216    public void onSignalStrengthChanged(int asu) {
217        // default implementation empty
218    }
219
220    /**
221     * Callback invoked when the message-waiting indicator changes.
222     */
223    public void onMessageWaitingIndicatorChanged(boolean mwi) {
224        // default implementation empty
225    }
226
227    /**
228     * Callback invoked when the call-forwarding indicator changes.
229     */
230    public void onCallForwardingIndicatorChanged(boolean cfi) {
231        // default implementation empty
232    }
233
234    /**
235     * Callback invoked when device cell location changes.
236     */
237    public void onCellLocationChanged(CellLocation location) {
238        // default implementation empty
239    }
240
241    /**
242     * Callback invoked when device call state changes.
243     *
244     * @see TelephonyManager#CALL_STATE_IDLE
245     * @see TelephonyManager#CALL_STATE_RINGING
246     * @see TelephonyManager#CALL_STATE_OFFHOOK
247     */
248    public void onCallStateChanged(int state, String incomingNumber) {
249        // default implementation empty
250    }
251
252    /**
253     * Callback invoked when connection state changes.
254     *
255     * @see TelephonyManager#DATA_DISCONNECTED
256     * @see TelephonyManager#DATA_CONNECTING
257     * @see TelephonyManager#DATA_CONNECTED
258     * @see TelephonyManager#DATA_SUSPENDED
259     */
260    public void onDataConnectionStateChanged(int state) {
261        // default implementation empty
262    }
263
264    /**
265     * same as above, but with the network type.  Both called.
266     */
267    public void onDataConnectionStateChanged(int state, int networkType) {
268    }
269
270    /**
271     * Callback invoked when data activity state changes.
272     *
273     * @see TelephonyManager#DATA_ACTIVITY_NONE
274     * @see TelephonyManager#DATA_ACTIVITY_IN
275     * @see TelephonyManager#DATA_ACTIVITY_OUT
276     * @see TelephonyManager#DATA_ACTIVITY_INOUT
277     * @see TelephonyManager#DATA_ACTIVITY_DORMANT
278     */
279    public void onDataActivity(int direction) {
280        // default implementation empty
281    }
282
283    /**
284     * Callback invoked when network signal strengths changes.
285     *
286     * @see ServiceState#STATE_EMERGENCY_ONLY
287     * @see ServiceState#STATE_IN_SERVICE
288     * @see ServiceState#STATE_OUT_OF_SERVICE
289     * @see ServiceState#STATE_POWER_OFF
290     */
291    public void onSignalStrengthsChanged(SignalStrength signalStrength) {
292        // default implementation empty
293    }
294
295
296    /**
297     * The Over The Air Service Provisioning (OTASP) has changed. Requires
298     * the READ_PHONE_STATE permission.
299     * @param otaspMode is integer <code>OTASP_UNKNOWN=1<code>
300     *   means the value is currently unknown and the system should wait until
301     *   <code>OTASP_NEEDED=2<code> or <code>OTASP_NOT_NEEDED=3<code> is received before
302     *   making the decisision to perform OTASP or not.
303     *
304     * @hide
305     */
306    public void onOtaspChanged(int otaspMode) {
307        // default implementation empty
308    }
309
310    /**
311     * Callback invoked when a observed cell info has changed,
312     * or new cells have been added or removed.
313     * @param cellInfo is the list of currently visible cells.
314     */
315    public void onCellInfoChanged(List<CellInfo> cellInfo) {
316    }
317
318    /**
319     * Callback invoked when precise device call state changes.
320     *
321     * @hide
322     */
323    public void onPreciseCallStateChanged(PreciseCallState callState) {
324        // default implementation empty
325    }
326
327    /**
328     * Callback invoked when data connection state changes with precise information.
329     *
330     * @hide
331     */
332    public void onPreciseDataConnectionStateChanged(
333            PreciseDataConnectionState dataConnectionState) {
334        // default implementation empty
335    }
336
337    /**
338     * The callback methods need to be called on the handler thread where
339     * this object was created.  If the binder did that for us it'd be nice.
340     */
341    IPhoneStateListener callback = new IPhoneStateListener.Stub() {
342        public void onServiceStateChanged(ServiceState serviceState) {
343            Message.obtain(mHandler, LISTEN_SERVICE_STATE, 0, 0, serviceState).sendToTarget();
344        }
345
346        public void onSignalStrengthChanged(int asu) {
347            Message.obtain(mHandler, LISTEN_SIGNAL_STRENGTH, asu, 0, null).sendToTarget();
348        }
349
350        public void onMessageWaitingIndicatorChanged(boolean mwi) {
351            Message.obtain(mHandler, LISTEN_MESSAGE_WAITING_INDICATOR, mwi ? 1 : 0, 0, null)
352                    .sendToTarget();
353        }
354
355        public void onCallForwardingIndicatorChanged(boolean cfi) {
356            Message.obtain(mHandler, LISTEN_CALL_FORWARDING_INDICATOR, cfi ? 1 : 0, 0, null)
357                    .sendToTarget();
358        }
359
360        public void onCellLocationChanged(Bundle bundle) {
361            CellLocation location = CellLocation.newFromBundle(bundle);
362            Message.obtain(mHandler, LISTEN_CELL_LOCATION, 0, 0, location).sendToTarget();
363        }
364
365        public void onCallStateChanged(int state, String incomingNumber) {
366            Message.obtain(mHandler, LISTEN_CALL_STATE, state, 0, incomingNumber).sendToTarget();
367        }
368
369        public void onDataConnectionStateChanged(int state, int networkType) {
370            Message.obtain(mHandler, LISTEN_DATA_CONNECTION_STATE, state, networkType).
371                    sendToTarget();
372        }
373
374        public void onDataActivity(int direction) {
375            Message.obtain(mHandler, LISTEN_DATA_ACTIVITY, direction, 0, null).sendToTarget();
376        }
377
378        public void onSignalStrengthsChanged(SignalStrength signalStrength) {
379            Message.obtain(mHandler, LISTEN_SIGNAL_STRENGTHS, 0, 0, signalStrength).sendToTarget();
380        }
381
382        public void onOtaspChanged(int otaspMode) {
383            Message.obtain(mHandler, LISTEN_OTASP_CHANGED, otaspMode, 0).sendToTarget();
384        }
385
386        public void onCellInfoChanged(List<CellInfo> cellInfo) {
387            Message.obtain(mHandler, LISTEN_CELL_INFO, 0, 0, cellInfo).sendToTarget();
388        }
389
390        public void onPreciseCallStateChanged(PreciseCallState callState) {
391            Message.obtain(mHandler, LISTEN_PRECISE_CALL_STATE, 0, 0, callState).sendToTarget();
392        }
393
394        public void onPreciseDataConnectionStateChanged(
395                PreciseDataConnectionState dataConnectionState) {
396            Message.obtain(mHandler, LISTEN_PRECISE_DATA_CONNECTION_STATE, 0, 0,
397                    dataConnectionState).sendToTarget();
398        }
399    };
400
401    Handler mHandler = new Handler() {
402        public void handleMessage(Message msg) {
403            //Rlog.d("TelephonyRegistry", "what=0x" + Integer.toHexString(msg.what) + " msg=" + msg);
404            switch (msg.what) {
405                case LISTEN_SERVICE_STATE:
406                    PhoneStateListener.this.onServiceStateChanged((ServiceState)msg.obj);
407                    break;
408                case LISTEN_SIGNAL_STRENGTH:
409                    PhoneStateListener.this.onSignalStrengthChanged(msg.arg1);
410                    break;
411                case LISTEN_MESSAGE_WAITING_INDICATOR:
412                    PhoneStateListener.this.onMessageWaitingIndicatorChanged(msg.arg1 != 0);
413                    break;
414                case LISTEN_CALL_FORWARDING_INDICATOR:
415                    PhoneStateListener.this.onCallForwardingIndicatorChanged(msg.arg1 != 0);
416                    break;
417                case LISTEN_CELL_LOCATION:
418                    PhoneStateListener.this.onCellLocationChanged((CellLocation)msg.obj);
419                    break;
420                case LISTEN_CALL_STATE:
421                    PhoneStateListener.this.onCallStateChanged(msg.arg1, (String)msg.obj);
422                    break;
423                case LISTEN_DATA_CONNECTION_STATE:
424                    PhoneStateListener.this.onDataConnectionStateChanged(msg.arg1, msg.arg2);
425                    PhoneStateListener.this.onDataConnectionStateChanged(msg.arg1);
426                    break;
427                case LISTEN_DATA_ACTIVITY:
428                    PhoneStateListener.this.onDataActivity(msg.arg1);
429                    break;
430                case LISTEN_SIGNAL_STRENGTHS:
431                    PhoneStateListener.this.onSignalStrengthsChanged((SignalStrength)msg.obj);
432                    break;
433                case LISTEN_OTASP_CHANGED:
434                    PhoneStateListener.this.onOtaspChanged(msg.arg1);
435                    break;
436                case LISTEN_CELL_INFO:
437                    PhoneStateListener.this.onCellInfoChanged((List<CellInfo>)msg.obj);
438                    break;
439                case LISTEN_PRECISE_CALL_STATE:
440                    PhoneStateListener.this.onPreciseCallStateChanged((PreciseCallState)msg.obj);
441                    break;
442                case LISTEN_PRECISE_DATA_CONNECTION_STATE:
443                    PhoneStateListener.this.onPreciseDataConnectionStateChanged((PreciseDataConnectionState)msg.obj);
444            }
445        }
446    };
447}
448