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