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 | |
| 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. |
Chris Tate | a34df8a2 | 2009-04-02 23:15:58 -0700 | [diff] [blame] | 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. |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 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 | } |
Dan Egnor | 97e4494 | 2010-02-04 20:27:47 -0800 | [diff] [blame] | 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 | */ |
The Android Open Source Project | 9066cfe | 2009-03-03 19:31:44 -0800 | [diff] [blame] | 300 | public void setTimeZone(String timeZone) { |
| 301 | try { |
| 302 | mService.setTimeZone(timeZone); |
| 303 | } catch (RemoteException ex) { |
| 304 | } |
| 305 | } |
| 306 | } |