The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | |
| 17 | package android.app; |
| 18 | |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 19 | import android.content.Intent; |
| 20 | import android.os.RemoteException; |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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. |
Chris Tate | a34df8a2 | 2009-04-02 23:15:58 -0700 | [diff] [blame] | 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. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | */ |
| 53 | public 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 <receiver> 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. |
Jesse Wilson | 79074cd | 2011-12-22 22:51:37 -0500 | [diff] [blame] | 118 | * @param triggerAtMillis time in milliseconds that the alarm should go |
| 119 | * off, using the appropriate clock (depending on the alarm type). |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | */ |
Jesse Wilson | 79074cd | 2011-12-22 22:51:37 -0500 | [diff] [blame] | 135 | public void set(int type, long triggerAtMillis, PendingIntent operation) { |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 136 | try { |
Jesse Wilson | 79074cd | 2011-12-22 22:51:37 -0500 | [diff] [blame] | 137 | mService.set(type, triggerAtMillis, operation); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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. |
Jesse Wilson | 79074cd | 2011-12-22 22:51:37 -0500 | [diff] [blame] | 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. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | */ |
Jesse Wilson | 79074cd | 2011-12-22 22:51:37 -0500 | [diff] [blame] | 189 | public void setRepeating(int type, long triggerAtMillis, |
| 190 | long intervalMillis, PendingIntent operation) { |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 191 | try { |
Jesse Wilson | 79074cd | 2011-12-22 22:51:37 -0500 | [diff] [blame] | 192 | mService.setRepeating(type, triggerAtMillis, intervalMillis, operation); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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. |
Jesse Wilson | 79074cd | 2011-12-22 22:51:37 -0500 | [diff] [blame] | 221 | * |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 222 | * @param type One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP}, RTC or |
| 223 | * RTC_WAKEUP. |
Jesse Wilson | 79074cd | 2011-12-22 22:51:37 -0500 | [diff] [blame] | 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}. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | */ |
Jesse Wilson | 79074cd | 2011-12-22 22:51:37 -0500 | [diff] [blame] | 255 | public void setInexactRepeating(int type, long triggerAtMillis, |
| 256 | long intervalMillis, PendingIntent operation) { |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 257 | try { |
Jesse Wilson | 79074cd | 2011-12-22 22:51:37 -0500 | [diff] [blame] | 258 | mService.setInexactRepeating(type, triggerAtMillis, intervalMillis, operation); |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | } |
Dan Egnor | 97e4494 | 2010-02-04 20:27:47 -0800 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 299 | public void setTimeZone(String timeZone) { |
| 300 | try { |
| 301 | mService.setTimeZone(timeZone); |
| 302 | } catch (RemoteException ex) { |
| 303 | } |
| 304 | } |
| 305 | } |