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 android.app;
18
19import android.content.Intent;
20import android.os.RemoteException;
21
22/**
23 * This class provides access to the system alarm services.  These allow you
24 * to schedule your application to be run at some point in the future.  When
25 * an alarm goes off, the {@link Intent} that had been registered for it
26 * is broadcast by the system, automatically starting the target application
27 * if it is not already running.  Registered alarms are retained while the
28 * device is asleep (and can optionally wake the device up if they go off
29 * during that time), but will be cleared if it is turned off and rebooted.
30 *
31 * <p>The Alarm Manager holds a CPU wake lock as long as the alarm receiver's
32 * onReceive() method is executing. This guarantees that the phone will not sleep
33 * until you have finished handling the broadcast. Once onReceive() returns, the
34 * Alarm Manager releases this wake lock. This means that the phone will in some
35 * cases sleep as soon as your onReceive() method completes.  If your alarm receiver
36 * called {@link android.content.Context#startService Context.startService()}, it
37 * is possible that the phone will sleep before the requested service is launched.
38 * To prevent this, your BroadcastReceiver and Service will need to implement a
39 * separate wake lock policy to ensure that the phone continues running until the
40 * service becomes available.
41 *
42 * <p><b>Note: The Alarm Manager is intended for cases where you want to have
43 * your application code run at a specific time, even if your application is
44 * not currently running.  For normal timing operations (ticks, timeouts,
45 * etc) it is easier and much more efficient to use
46 * {@link android.os.Handler}.</b>
47 *
48 * <p>You do not
49 * instantiate this class directly; instead, retrieve it through
50 * {@link android.content.Context#getSystemService
51 * Context.getSystemService(Context.ALARM_SERVICE)}.
52 */
53public class AlarmManager
54{
55    /**
56     * Alarm time in {@link System#currentTimeMillis System.currentTimeMillis()}
57     * (wall clock time in UTC), which will wake up the device when
58     * it goes off.
59     */
60    public static final int RTC_WAKEUP = 0;
61    /**
62     * Alarm time in {@link System#currentTimeMillis System.currentTimeMillis()}
63     * (wall clock time in UTC).  This alarm does not wake the
64     * device up; if it goes off while the device is asleep, it will not be
65     * delivered until the next time the device wakes up.
66     */
67    public static final int RTC = 1;
68    /**
69     * Alarm time in {@link android.os.SystemClock#elapsedRealtime
70     * SystemClock.elapsedRealtime()} (time since boot, including sleep),
71     * which will wake up the device when it goes off.
72     */
73    public static final int ELAPSED_REALTIME_WAKEUP = 2;
74    /**
75     * Alarm time in {@link android.os.SystemClock#elapsedRealtime
76     * SystemClock.elapsedRealtime()} (time since boot, including sleep).
77     * This alarm does not wake the device up; if it goes off while the device
78     * is asleep, it will not be delivered until the next time the device
79     * wakes up.
80     */
81    public static final int ELAPSED_REALTIME = 3;
82
83    private final IAlarmManager mService;
84
85    /**
86     * package private on purpose
87     */
88    AlarmManager(IAlarmManager service) {
89        mService = service;
90    }
91
92    /**
93     * Schedule an alarm.  <b>Note: for timing operations (ticks, timeouts,
94     * etc) it is easier and much more efficient to use
95     * {@link android.os.Handler}.</b>  If there is already an alarm scheduled
96     * for the same IntentSender, it will first be canceled.
97     *
98     * <p>If the time occurs in the past, the alarm will be triggered
99     * immediately.  If there is already an alarm for this Intent
100     * scheduled (with the equality of two intents being defined by
101     * {@link Intent#filterEquals}), then it will be removed and replaced by
102     * this one.
103     *
104     * <p>
105     * The alarm is an intent broadcast that goes to a broadcast receiver that
106     * you registered with {@link android.content.Context#registerReceiver}
107     * or through the &lt;receiver&gt; tag in an AndroidManifest.xml file.
108     *
109     * <p>
110     * Alarm intents are delivered with a data extra of type int called
111     * {@link Intent#EXTRA_ALARM_COUNT Intent.EXTRA_ALARM_COUNT} that indicates
112     * how many past alarm events have been accumulated into this intent
113     * broadcast.  Recurring alarms that have gone undelivered because the
114     * phone was asleep may have a count greater than one when delivered.
115     *
116     * @param type One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP, RTC or
117     *             RTC_WAKEUP.
118     * @param triggerAtMillis time in milliseconds that the alarm should go
119     * off, using the appropriate clock (depending on the alarm type).
120     * @param operation Action to perform when the alarm goes off;
121     * typically comes from {@link PendingIntent#getBroadcast
122     * IntentSender.getBroadcast()}.
123     *
124     * @see android.os.Handler
125     * @see #setRepeating
126     * @see #cancel
127     * @see android.content.Context#sendBroadcast
128     * @see android.content.Context#registerReceiver
129     * @see android.content.Intent#filterEquals
130     * @see #ELAPSED_REALTIME
131     * @see #ELAPSED_REALTIME_WAKEUP
132     * @see #RTC
133     * @see #RTC_WAKEUP
134     */
135    public void set(int type, long triggerAtMillis, PendingIntent operation) {
136        try {
137            mService.set(type, triggerAtMillis, operation);
138        } catch (RemoteException ex) {
139        }
140    }
141
142    /**
143     * Schedule a repeating alarm.  <b>Note: for timing operations (ticks,
144     * timeouts, etc) it is easier and much more efficient to use
145     * {@link android.os.Handler}.</b>  If there is already an alarm scheduled
146     * for the same IntentSender, it will first be canceled.
147     *
148     * <p>Like {@link #set}, except you can also
149     * supply a rate at which the alarm will repeat.  This alarm continues
150     * repeating until explicitly removed with {@link #cancel}.  If the time
151     * occurs in the past, the alarm will be triggered immediately, with an
152     * alarm count depending on how far in the past the trigger time is relative
153     * to the repeat interval.
154     *
155     * <p>If an alarm is delayed (by system sleep, for example, for non
156     * _WAKEUP alarm types), a skipped repeat will be delivered as soon as
157     * possible.  After that, future alarms will be delivered according to the
158     * original schedule; they do not drift over time.  For example, if you have
159     * set a recurring alarm for the top of every hour but the phone was asleep
160     * from 7:45 until 8:45, an alarm will be sent as soon as the phone awakens,
161     * then the next alarm will be sent at 9:00.
162     *
163     * <p>If your application wants to allow the delivery times to drift in
164     * order to guarantee that at least a certain time interval always elapses
165     * between alarms, then the approach to take is to use one-time alarms,
166     * scheduling the next one yourself when handling each alarm delivery.
167     *
168     * @param type One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP}, RTC or
169     *             RTC_WAKEUP.
170     * @param triggerAtMillis time in milliseconds that the alarm should first
171     * go off, using the appropriate clock (depending on the alarm type).
172     * @param intervalMillis interval in milliseconds between subsequent repeats
173     * of the alarm.
174     * @param operation Action to perform when the alarm goes off;
175     * typically comes from {@link PendingIntent#getBroadcast
176     * IntentSender.getBroadcast()}.
177     *
178     * @see android.os.Handler
179     * @see #set
180     * @see #cancel
181     * @see android.content.Context#sendBroadcast
182     * @see android.content.Context#registerReceiver
183     * @see android.content.Intent#filterEquals
184     * @see #ELAPSED_REALTIME
185     * @see #ELAPSED_REALTIME_WAKEUP
186     * @see #RTC
187     * @see #RTC_WAKEUP
188     */
189    public void setRepeating(int type, long triggerAtMillis,
190            long intervalMillis, PendingIntent operation) {
191        try {
192            mService.setRepeating(type, triggerAtMillis, intervalMillis, operation);
193        } catch (RemoteException ex) {
194        }
195    }
196
197    /**
198     * Available inexact recurrence intervals recognized by
199     * {@link #setInexactRepeating(int, long, long, PendingIntent)}
200     */
201    public static final long INTERVAL_FIFTEEN_MINUTES = 15 * 60 * 1000;
202    public static final long INTERVAL_HALF_HOUR = 2*INTERVAL_FIFTEEN_MINUTES;
203    public static final long INTERVAL_HOUR = 2*INTERVAL_HALF_HOUR;
204    public static final long INTERVAL_HALF_DAY = 12*INTERVAL_HOUR;
205    public static final long INTERVAL_DAY = 2*INTERVAL_HALF_DAY;
206
207    /**
208     * Schedule a repeating alarm that has inexact trigger time requirements;
209     * for example, an alarm that repeats every hour, but not necessarily at
210     * the top of every hour.  These alarms are more power-efficient than
211     * the strict recurrences supplied by {@link #setRepeating}, since the
212     * system can adjust alarms' phase to cause them to fire simultaneously,
213     * avoiding waking the device from sleep more than necessary.
214     *
215     * <p>Your alarm's first trigger will not be before the requested time,
216     * but it might not occur for almost a full interval after that time.  In
217     * addition, while the overall period of the repeating alarm will be as
218     * requested, the time between any two successive firings of the alarm
219     * may vary.  If your application demands very low jitter, use
220     * {@link #setRepeating} instead.
221     *
222     * @param type One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP}, RTC or
223     *             RTC_WAKEUP.
224     * @param triggerAtMillis time in milliseconds that the alarm should first
225     * go off, using the appropriate clock (depending on the alarm type).  This
226     * is inexact: the alarm will not fire before this time, but there may be a
227     * delay of almost an entire alarm interval before the first invocation of
228     * the alarm.
229     * @param intervalMillis interval in milliseconds between subsequent repeats
230     * of the alarm.  If this is one of INTERVAL_FIFTEEN_MINUTES,
231     * INTERVAL_HALF_HOUR, INTERVAL_HOUR, INTERVAL_HALF_DAY, or INTERVAL_DAY
232     * then the alarm will be phase-aligned with other alarms to reduce the
233     * number of wakeups.  Otherwise, the alarm will be set as though the
234     * application had called {@link #setRepeating}.
235     * @param operation Action to perform when the alarm goes off;
236     * typically comes from {@link PendingIntent#getBroadcast
237     * IntentSender.getBroadcast()}.
238     *
239     * @see android.os.Handler
240     * @see #set
241     * @see #cancel
242     * @see android.content.Context#sendBroadcast
243     * @see android.content.Context#registerReceiver
244     * @see android.content.Intent#filterEquals
245     * @see #ELAPSED_REALTIME
246     * @see #ELAPSED_REALTIME_WAKEUP
247     * @see #RTC
248     * @see #RTC_WAKEUP
249     * @see #INTERVAL_FIFTEEN_MINUTES
250     * @see #INTERVAL_HALF_HOUR
251     * @see #INTERVAL_HOUR
252     * @see #INTERVAL_HALF_DAY
253     * @see #INTERVAL_DAY
254     */
255    public void setInexactRepeating(int type, long triggerAtMillis,
256            long intervalMillis, PendingIntent operation) {
257        try {
258            mService.setInexactRepeating(type, triggerAtMillis, intervalMillis, operation);
259        } catch (RemoteException ex) {
260        }
261    }
262
263    /**
264     * Remove any alarms with a matching {@link Intent}.
265     * Any alarm, of any type, whose Intent matches this one (as defined by
266     * {@link Intent#filterEquals}), will be canceled.
267     *
268     * @param operation IntentSender which matches a previously added
269     * IntentSender.
270     *
271     * @see #set
272     */
273    public void cancel(PendingIntent operation) {
274        try {
275            mService.remove(operation);
276        } catch (RemoteException ex) {
277        }
278    }
279
280    /**
281     * Set the system wall clock time.
282     * Requires the permission android.permission.SET_TIME.
283     *
284     * @param millis time in milliseconds since the Epoch
285     */
286    public void setTime(long millis) {
287        try {
288            mService.setTime(millis);
289        } catch (RemoteException ex) {
290        }
291    }
292
293    /**
294     * Set the system default time zone.
295     * Requires the permission android.permission.SET_TIME_ZONE.
296     *
297     * @param timeZone in the format understood by {@link java.util.TimeZone}
298     */
299    public void setTimeZone(String timeZone) {
300        try {
301            mService.setTimeZone(timeZone);
302        } catch (RemoteException ex) {
303        }
304    }
305}
306