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