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 19 import android.content.Intent; 20 import 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 */ 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. 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
