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