AlarmManager.java revision 08c7116ab9cd04ad6dd3c04aa1017237e7f409ac
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.annotation.SdkConstant; 20import android.annotation.SystemApi; 21import android.content.Context; 22import android.content.Intent; 23import android.os.Build; 24import android.os.Parcel; 25import android.os.Parcelable; 26import android.os.RemoteException; 27import android.os.UserHandle; 28import android.os.WorkSource; 29 30/** 31 * This class provides access to the system alarm services. These allow you 32 * to schedule your application to be run at some point in the future. When 33 * an alarm goes off, the {@link Intent} that had been registered for it 34 * is broadcast by the system, automatically starting the target application 35 * if it is not already running. Registered alarms are retained while the 36 * device is asleep (and can optionally wake the device up if they go off 37 * during that time), but will be cleared if it is turned off and rebooted. 38 * 39 * <p>The Alarm Manager holds a CPU wake lock as long as the alarm receiver's 40 * onReceive() method is executing. This guarantees that the phone will not sleep 41 * until you have finished handling the broadcast. Once onReceive() returns, the 42 * Alarm Manager releases this wake lock. This means that the phone will in some 43 * cases sleep as soon as your onReceive() method completes. If your alarm receiver 44 * called {@link android.content.Context#startService Context.startService()}, it 45 * is possible that the phone will sleep before the requested service is launched. 46 * To prevent this, your BroadcastReceiver and Service will need to implement a 47 * separate wake lock policy to ensure that the phone continues running until the 48 * service becomes available. 49 * 50 * <p><b>Note: The Alarm Manager is intended for cases where you want to have 51 * your application code run at a specific time, even if your application is 52 * not currently running. For normal timing operations (ticks, timeouts, 53 * etc) it is easier and much more efficient to use 54 * {@link android.os.Handler}.</b> 55 * 56 * <p class="caution"><strong>Note:</strong> Beginning with API 19 57 * ({@link android.os.Build.VERSION_CODES#KITKAT}) alarm delivery is inexact: 58 * the OS will shift alarms in order to minimize wakeups and battery use. There are 59 * new APIs to support applications which need strict delivery guarantees; see 60 * {@link #setWindow(int, long, long, PendingIntent)} and 61 * {@link #setExact(int, long, PendingIntent)}. Applications whose {@code targetSdkVersion} 62 * is earlier than API 19 will continue to see the previous behavior in which all 63 * alarms are delivered exactly when requested. 64 * 65 * <p>You do not 66 * instantiate this class directly; instead, retrieve it through 67 * {@link android.content.Context#getSystemService 68 * Context.getSystemService(Context.ALARM_SERVICE)}. 69 */ 70public class AlarmManager 71{ 72 private static final String TAG = "AlarmManager"; 73 74 /** 75 * Alarm time in {@link System#currentTimeMillis System.currentTimeMillis()} 76 * (wall clock time in UTC), which will wake up the device when 77 * it goes off. 78 */ 79 public static final int RTC_WAKEUP = 0; 80 /** 81 * Alarm time in {@link System#currentTimeMillis System.currentTimeMillis()} 82 * (wall clock time in UTC). This alarm does not wake the 83 * device up; if it goes off while the device is asleep, it will not be 84 * delivered until the next time the device wakes up. 85 */ 86 public static final int RTC = 1; 87 /** 88 * Alarm time in {@link android.os.SystemClock#elapsedRealtime 89 * SystemClock.elapsedRealtime()} (time since boot, including sleep), 90 * which will wake up the device when it goes off. 91 */ 92 public static final int ELAPSED_REALTIME_WAKEUP = 2; 93 /** 94 * Alarm time in {@link android.os.SystemClock#elapsedRealtime 95 * SystemClock.elapsedRealtime()} (time since boot, including sleep). 96 * This alarm does not wake the device up; if it goes off while the device 97 * is asleep, it will not be delivered until the next time the device 98 * wakes up. 99 */ 100 public static final int ELAPSED_REALTIME = 3; 101 102 /** 103 * Broadcast Action: Sent after the value returned by 104 * {@link #getNextAlarmClock()} has changed. 105 * 106 * <p class="note">This is a protected intent that can only be sent by the system. 107 * It is only sent to registered receivers.</p> 108 */ 109 @SdkConstant(SdkConstant.SdkConstantType.BROADCAST_INTENT_ACTION) 110 public static final String ACTION_NEXT_ALARM_CLOCK_CHANGED = 111 "android.app.action.NEXT_ALARM_CLOCK_CHANGED"; 112 113 /** @hide */ 114 public static final long WINDOW_EXACT = 0; 115 /** @hide */ 116 public static final long WINDOW_HEURISTIC = -1; 117 118 private final IAlarmManager mService; 119 private final boolean mAlwaysExact; 120 121 122 /** 123 * package private on purpose 124 */ 125 AlarmManager(IAlarmManager service, Context ctx) { 126 mService = service; 127 128 final int sdkVersion = ctx.getApplicationInfo().targetSdkVersion; 129 mAlwaysExact = (sdkVersion < Build.VERSION_CODES.KITKAT); 130 } 131 132 private long legacyExactLength() { 133 return (mAlwaysExact ? WINDOW_EXACT : WINDOW_HEURISTIC); 134 } 135 136 /** 137 * <p>Schedule an alarm. <b>Note: for timing operations (ticks, timeouts, 138 * etc) it is easier and much more efficient to use {@link android.os.Handler}.</b> 139 * If there is already an alarm scheduled for the same IntentSender, that previous 140 * alarm will first be canceled. 141 * 142 * <p>If the stated trigger time is in the past, the alarm will be triggered 143 * immediately. If there is already an alarm for this Intent 144 * scheduled (with the equality of two intents being defined by 145 * {@link Intent#filterEquals}), then it will be removed and replaced by 146 * this one. 147 * 148 * <p> 149 * The alarm is an Intent broadcast that goes to a broadcast receiver that 150 * you registered with {@link android.content.Context#registerReceiver} 151 * or through the <receiver> tag in an AndroidManifest.xml file. 152 * 153 * <p> 154 * Alarm intents are delivered with a data extra of type int called 155 * {@link Intent#EXTRA_ALARM_COUNT Intent.EXTRA_ALARM_COUNT} that indicates 156 * how many past alarm events have been accumulated into this intent 157 * broadcast. Recurring alarms that have gone undelivered because the 158 * phone was asleep may have a count greater than one when delivered. 159 * 160 * <div class="note"> 161 * <p> 162 * <b>Note:</b> Beginning in API 19, the trigger time passed to this method 163 * is treated as inexact: the alarm will not be delivered before this time, but 164 * may be deferred and delivered some time later. The OS will use 165 * this policy in order to "batch" alarms together across the entire system, 166 * minimizing the number of times the device needs to "wake up" and minimizing 167 * battery use. In general, alarms scheduled in the near future will not 168 * be deferred as long as alarms scheduled far in the future. 169 * 170 * <p> 171 * With the new batching policy, delivery ordering guarantees are not as 172 * strong as they were previously. If the application sets multiple alarms, 173 * it is possible that these alarms' <em>actual</em> delivery ordering may not match 174 * the order of their <em>requested</em> delivery times. If your application has 175 * strong ordering requirements there are other APIs that you can use to get 176 * the necessary behavior; see {@link #setWindow(int, long, long, PendingIntent)} 177 * and {@link #setExact(int, long, PendingIntent)}. 178 * 179 * <p> 180 * Applications whose {@code targetSdkVersion} is before API 19 will 181 * continue to get the previous alarm behavior: all of their scheduled alarms 182 * will be treated as exact. 183 * </div> 184 * 185 * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, 186 * {@link #RTC}, or {@link #RTC_WAKEUP}. 187 * @param triggerAtMillis time in milliseconds that the alarm should go 188 * off, using the appropriate clock (depending on the alarm type). 189 * @param operation Action to perform when the alarm goes off; 190 * typically comes from {@link PendingIntent#getBroadcast 191 * IntentSender.getBroadcast()}. 192 * 193 * @see android.os.Handler 194 * @see #setExact 195 * @see #setRepeating 196 * @see #setWindow 197 * @see #cancel 198 * @see android.content.Context#sendBroadcast 199 * @see android.content.Context#registerReceiver 200 * @see android.content.Intent#filterEquals 201 * @see #ELAPSED_REALTIME 202 * @see #ELAPSED_REALTIME_WAKEUP 203 * @see #RTC 204 * @see #RTC_WAKEUP 205 */ 206 public void set(int type, long triggerAtMillis, PendingIntent operation) { 207 setImpl(type, triggerAtMillis, legacyExactLength(), 0, operation, null, null); 208 } 209 210 /** 211 * Schedule a repeating alarm. <b>Note: for timing operations (ticks, 212 * timeouts, etc) it is easier and much more efficient to use 213 * {@link android.os.Handler}.</b> If there is already an alarm scheduled 214 * for the same IntentSender, it will first be canceled. 215 * 216 * <p>Like {@link #set}, except you can also supply a period at which 217 * the alarm will automatically repeat. This alarm continues 218 * repeating until explicitly removed with {@link #cancel}. If the stated 219 * trigger time is in the past, the alarm will be triggered immediately, with an 220 * alarm count depending on how far in the past the trigger time is relative 221 * to the repeat interval. 222 * 223 * <p>If an alarm is delayed (by system sleep, for example, for non 224 * _WAKEUP alarm types), a skipped repeat will be delivered as soon as 225 * possible. After that, future alarms will be delivered according to the 226 * original schedule; they do not drift over time. For example, if you have 227 * set a recurring alarm for the top of every hour but the phone was asleep 228 * from 7:45 until 8:45, an alarm will be sent as soon as the phone awakens, 229 * then the next alarm will be sent at 9:00. 230 * 231 * <p>If your application wants to allow the delivery times to drift in 232 * order to guarantee that at least a certain time interval always elapses 233 * between alarms, then the approach to take is to use one-time alarms, 234 * scheduling the next one yourself when handling each alarm delivery. 235 * 236 * <p class="note"> 237 * <b>Note:</b> as of API 19, all repeating alarms are inexact. If your 238 * application needs precise delivery times then it must use one-time 239 * exact alarms, rescheduling each time as described above. Legacy applications 240 * whose {@code targetSdkVersion} is earlier than API 19 will continue to have all 241 * of their alarms, including repeating alarms, treated as exact. 242 * 243 * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, 244 * {@link #RTC}, or {@link #RTC_WAKEUP}. 245 * @param triggerAtMillis time in milliseconds that the alarm should first 246 * go off, using the appropriate clock (depending on the alarm type). 247 * @param intervalMillis interval in milliseconds between subsequent repeats 248 * of the alarm. 249 * @param operation Action to perform when the alarm goes off; 250 * typically comes from {@link PendingIntent#getBroadcast 251 * IntentSender.getBroadcast()}. 252 * 253 * @see android.os.Handler 254 * @see #set 255 * @see #setExact 256 * @see #setWindow 257 * @see #cancel 258 * @see android.content.Context#sendBroadcast 259 * @see android.content.Context#registerReceiver 260 * @see android.content.Intent#filterEquals 261 * @see #ELAPSED_REALTIME 262 * @see #ELAPSED_REALTIME_WAKEUP 263 * @see #RTC 264 * @see #RTC_WAKEUP 265 */ 266 public void setRepeating(int type, long triggerAtMillis, 267 long intervalMillis, PendingIntent operation) { 268 setImpl(type, triggerAtMillis, legacyExactLength(), intervalMillis, operation, null, null); 269 } 270 271 /** 272 * Schedule an alarm to be delivered within a given window of time. This method 273 * is similar to {@link #set(int, long, PendingIntent)}, but allows the 274 * application to precisely control the degree to which its delivery might be 275 * adjusted by the OS. This method allows an application to take advantage of the 276 * battery optimizations that arise from delivery batching even when it has 277 * modest timeliness requirements for its alarms. 278 * 279 * <p> 280 * This method can also be used to achieve strict ordering guarantees among 281 * multiple alarms by ensuring that the windows requested for each alarm do 282 * not intersect. 283 * 284 * <p> 285 * When precise delivery is not required, applications should use the standard 286 * {@link #set(int, long, PendingIntent)} method. This will give the OS the most 287 * flexibility to minimize wakeups and battery use. For alarms that must be delivered 288 * at precisely-specified times with no acceptable variation, applications can use 289 * {@link #setExact(int, long, PendingIntent)}. 290 * 291 * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, 292 * {@link #RTC}, or {@link #RTC_WAKEUP}. 293 * @param windowStartMillis The earliest time, in milliseconds, that the alarm should 294 * be delivered, expressed in the appropriate clock's units (depending on the alarm 295 * type). 296 * @param windowLengthMillis The length of the requested delivery window, 297 * in milliseconds. The alarm will be delivered no later than this many 298 * milliseconds after {@code windowStartMillis}. Note that this parameter 299 * is a <i>duration,</i> not the timestamp of the end of the window. 300 * @param operation Action to perform when the alarm goes off; 301 * typically comes from {@link PendingIntent#getBroadcast 302 * IntentSender.getBroadcast()}. 303 * 304 * @see #set 305 * @see #setExact 306 * @see #setRepeating 307 * @see #cancel 308 * @see android.content.Context#sendBroadcast 309 * @see android.content.Context#registerReceiver 310 * @see android.content.Intent#filterEquals 311 * @see #ELAPSED_REALTIME 312 * @see #ELAPSED_REALTIME_WAKEUP 313 * @see #RTC 314 * @see #RTC_WAKEUP 315 */ 316 public void setWindow(int type, long windowStartMillis, long windowLengthMillis, 317 PendingIntent operation) { 318 setImpl(type, windowStartMillis, windowLengthMillis, 0, operation, null, null); 319 } 320 321 /** 322 * Schedule an alarm to be delivered precisely at the stated time. 323 * 324 * <p> 325 * This method is like {@link #set(int, long, PendingIntent)}, but does not permit 326 * the OS to adjust the delivery time. The alarm will be delivered as nearly as 327 * possible to the requested trigger time. 328 * 329 * <p> 330 * <b>Note:</b> only alarms for which there is a strong demand for exact-time 331 * delivery (such as an alarm clock ringing at the requested time) should be 332 * scheduled as exact. Applications are strongly discouraged from using exact 333 * alarms unnecessarily as they reduce the OS's ability to minimize battery use. 334 * 335 * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, 336 * {@link #RTC}, or {@link #RTC_WAKEUP}. 337 * @param triggerAtMillis time in milliseconds that the alarm should go 338 * off, using the appropriate clock (depending on the alarm type). 339 * @param operation Action to perform when the alarm goes off; 340 * typically comes from {@link PendingIntent#getBroadcast 341 * IntentSender.getBroadcast()}. 342 * 343 * @see #set 344 * @see #setRepeating 345 * @see #setWindow 346 * @see #cancel 347 * @see android.content.Context#sendBroadcast 348 * @see android.content.Context#registerReceiver 349 * @see android.content.Intent#filterEquals 350 * @see #ELAPSED_REALTIME 351 * @see #ELAPSED_REALTIME_WAKEUP 352 * @see #RTC 353 * @see #RTC_WAKEUP 354 */ 355 public void setExact(int type, long triggerAtMillis, PendingIntent operation) { 356 setImpl(type, triggerAtMillis, WINDOW_EXACT, 0, operation, null, null); 357 } 358 359 /** 360 * Schedule an alarm that represents an alarm clock. 361 * 362 * The system may choose to display information about this alarm to the user. 363 * 364 * <p> 365 * This method is like {@link #setExact(int, long, PendingIntent)}, but implies 366 * {@link #RTC_WAKEUP}. 367 * 368 * @param info 369 * @param operation Action to perform when the alarm goes off; 370 * typically comes from {@link PendingIntent#getBroadcast 371 * IntentSender.getBroadcast()}. 372 * 373 * @see #set 374 * @see #setRepeating 375 * @see #setWindow 376 * @see #setExact 377 * @see #cancel 378 * @see #getNextAlarmClock() 379 * @see android.content.Context#sendBroadcast 380 * @see android.content.Context#registerReceiver 381 * @see android.content.Intent#filterEquals 382 */ 383 public void setAlarmClock(AlarmClockInfo info, PendingIntent operation) { 384 setImpl(RTC_WAKEUP, info.getTriggerTime(), WINDOW_EXACT, 0, operation, null, info); 385 } 386 387 /** @hide */ 388 @SystemApi 389 public void set(int type, long triggerAtMillis, long windowMillis, long intervalMillis, 390 PendingIntent operation, WorkSource workSource) { 391 setImpl(type, triggerAtMillis, windowMillis, intervalMillis, operation, workSource, null); 392 } 393 394 private void setImpl(int type, long triggerAtMillis, long windowMillis, long intervalMillis, 395 PendingIntent operation, WorkSource workSource, AlarmClockInfo alarmClock) { 396 if (triggerAtMillis < 0) { 397 /* NOTYET 398 if (mAlwaysExact) { 399 // Fatal error for KLP+ apps to use negative trigger times 400 throw new IllegalArgumentException("Invalid alarm trigger time " 401 + triggerAtMillis); 402 } 403 */ 404 triggerAtMillis = 0; 405 } 406 407 try { 408 mService.set(type, triggerAtMillis, windowMillis, intervalMillis, operation, 409 workSource, alarmClock); 410 } catch (RemoteException ex) { 411 } 412 } 413 414 /** 415 * Available inexact recurrence interval recognized by 416 * {@link #setInexactRepeating(int, long, long, PendingIntent)} 417 * when running on Android prior to API 19. 418 */ 419 public static final long INTERVAL_FIFTEEN_MINUTES = 15 * 60 * 1000; 420 421 /** 422 * Available inexact recurrence interval recognized by 423 * {@link #setInexactRepeating(int, long, long, PendingIntent)} 424 * when running on Android prior to API 19. 425 */ 426 public static final long INTERVAL_HALF_HOUR = 2*INTERVAL_FIFTEEN_MINUTES; 427 428 /** 429 * Available inexact recurrence interval recognized by 430 * {@link #setInexactRepeating(int, long, long, PendingIntent)} 431 * when running on Android prior to API 19. 432 */ 433 public static final long INTERVAL_HOUR = 2*INTERVAL_HALF_HOUR; 434 435 /** 436 * Available inexact recurrence interval recognized by 437 * {@link #setInexactRepeating(int, long, long, PendingIntent)} 438 * when running on Android prior to API 19. 439 */ 440 public static final long INTERVAL_HALF_DAY = 12*INTERVAL_HOUR; 441 442 /** 443 * Available inexact recurrence interval recognized by 444 * {@link #setInexactRepeating(int, long, long, PendingIntent)} 445 * when running on Android prior to API 19. 446 */ 447 public static final long INTERVAL_DAY = 2*INTERVAL_HALF_DAY; 448 449 /** 450 * Schedule a repeating alarm that has inexact trigger time requirements; 451 * for example, an alarm that repeats every hour, but not necessarily at 452 * the top of every hour. These alarms are more power-efficient than 453 * the strict recurrences traditionally supplied by {@link #setRepeating}, since the 454 * system can adjust alarms' delivery times to cause them to fire simultaneously, 455 * avoiding waking the device from sleep more than necessary. 456 * 457 * <p>Your alarm's first trigger will not be before the requested time, 458 * but it might not occur for almost a full interval after that time. In 459 * addition, while the overall period of the repeating alarm will be as 460 * requested, the time between any two successive firings of the alarm 461 * may vary. If your application demands very low jitter, use 462 * one-shot alarms with an appropriate window instead; see {@link 463 * #setWindow(int, long, long, PendingIntent)} and 464 * {@link #setExact(int, long, PendingIntent)}. 465 * 466 * <p class="note"> 467 * As of API 19, all repeating alarms are inexact. Because this method has 468 * been available since API 3, your application can safely call it and be 469 * assured that it will get similar behavior on both current and older versions 470 * of Android. 471 * 472 * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, 473 * {@link #RTC}, or {@link #RTC_WAKEUP}. 474 * @param triggerAtMillis time in milliseconds that the alarm should first 475 * go off, using the appropriate clock (depending on the alarm type). This 476 * is inexact: the alarm will not fire before this time, but there may be a 477 * delay of almost an entire alarm interval before the first invocation of 478 * the alarm. 479 * @param intervalMillis interval in milliseconds between subsequent repeats 480 * of the alarm. Prior to API 19, if this is one of INTERVAL_FIFTEEN_MINUTES, 481 * INTERVAL_HALF_HOUR, INTERVAL_HOUR, INTERVAL_HALF_DAY, or INTERVAL_DAY 482 * then the alarm will be phase-aligned with other alarms to reduce the 483 * number of wakeups. Otherwise, the alarm will be set as though the 484 * application had called {@link #setRepeating}. As of API 19, all repeating 485 * alarms will be inexact and subject to batching with other alarms regardless 486 * of their stated repeat interval. 487 * @param operation Action to perform when the alarm goes off; 488 * typically comes from {@link PendingIntent#getBroadcast 489 * IntentSender.getBroadcast()}. 490 * 491 * @see android.os.Handler 492 * @see #set 493 * @see #cancel 494 * @see android.content.Context#sendBroadcast 495 * @see android.content.Context#registerReceiver 496 * @see android.content.Intent#filterEquals 497 * @see #ELAPSED_REALTIME 498 * @see #ELAPSED_REALTIME_WAKEUP 499 * @see #RTC 500 * @see #RTC_WAKEUP 501 * @see #INTERVAL_FIFTEEN_MINUTES 502 * @see #INTERVAL_HALF_HOUR 503 * @see #INTERVAL_HOUR 504 * @see #INTERVAL_HALF_DAY 505 * @see #INTERVAL_DAY 506 */ 507 public void setInexactRepeating(int type, long triggerAtMillis, 508 long intervalMillis, PendingIntent operation) { 509 setImpl(type, triggerAtMillis, WINDOW_HEURISTIC, intervalMillis, operation, null, null); 510 } 511 512 /** 513 * Remove any alarms with a matching {@link Intent}. 514 * Any alarm, of any type, whose Intent matches this one (as defined by 515 * {@link Intent#filterEquals}), will be canceled. 516 * 517 * @param operation IntentSender which matches a previously added 518 * IntentSender. 519 * 520 * @see #set 521 */ 522 public void cancel(PendingIntent operation) { 523 try { 524 mService.remove(operation); 525 } catch (RemoteException ex) { 526 } 527 } 528 529 /** 530 * Set the system wall clock time. 531 * Requires the permission android.permission.SET_TIME. 532 * 533 * @param millis time in milliseconds since the Epoch 534 */ 535 public void setTime(long millis) { 536 try { 537 mService.setTime(millis); 538 } catch (RemoteException ex) { 539 } 540 } 541 542 /** 543 * Set the system default time zone. 544 * Requires the permission android.permission.SET_TIME_ZONE. 545 * 546 * @param timeZone in the format understood by {@link java.util.TimeZone} 547 */ 548 public void setTimeZone(String timeZone) { 549 try { 550 mService.setTimeZone(timeZone); 551 } catch (RemoteException ex) { 552 } 553 } 554 555 /** 556 * Gets information about the next alarm clock currently scheduled. 557 * 558 * The alarm clocks considered are those scheduled by {@link #setAlarmClock} 559 * from any package of the calling user. 560 * 561 * @see #setAlarmClock 562 * @see AlarmClockInfo 563 */ 564 public AlarmClockInfo getNextAlarmClock() { 565 return getNextAlarmClock(UserHandle.myUserId()); 566 } 567 568 /** 569 * Gets information about the next alarm clock currently scheduled. 570 * 571 * The alarm clocks considered are those scheduled by {@link #setAlarmClock} 572 * from any package of the given {@parm userId}. 573 * 574 * @see #setAlarmClock 575 * @see AlarmClockInfo 576 * 577 * @hide 578 */ 579 public AlarmClockInfo getNextAlarmClock(int userId) { 580 try { 581 return mService.getNextAlarmClock(userId); 582 } catch (RemoteException ex) { 583 return null; 584 } 585 } 586 587 /** 588 * An immutable description of an alarm clock. 589 * 590 * @see AlarmManager#setAlarmClock 591 * @see AlarmManager#getNextAlarmClock 592 */ 593 public static final class AlarmClockInfo implements Parcelable { 594 595 private final long mTriggerTime; 596 private final PendingIntent mShowIntent; 597 598 /** 599 * Creates a new alarm clock description. 600 * 601 * @param triggerTime time at which the underlying alarm is triggered in wall time 602 * milliseconds since the epoch 603 * @param showIntent an intent that can be used to show or edit details of 604 * the alarm clock. 605 */ 606 public AlarmClockInfo(long triggerTime, PendingIntent showIntent) { 607 mTriggerTime = triggerTime; 608 mShowIntent = showIntent; 609 } 610 611 /** 612 * Use the {@link #CREATOR} 613 * @hide 614 */ 615 AlarmClockInfo(Parcel in) { 616 mTriggerTime = in.readLong(); 617 mShowIntent = in.readParcelable(PendingIntent.class.getClassLoader()); 618 } 619 620 /** 621 * Returns the time at which the alarm is going to trigger. 622 * 623 * This value is UTC wall clock time in milliseconds, as returned by 624 * {@link System#currentTimeMillis()} for example. 625 */ 626 public long getTriggerTime() { 627 return mTriggerTime; 628 } 629 630 /** 631 * Returns an intent intent that can be used to show or edit details of the alarm clock in 632 * the application that scheduled it. 633 * 634 * <p class="note">Beware that any application can retrieve and send this intent, 635 * potentially with additional fields filled in. See 636 * {@link PendingIntent#send(android.content.Context, int, android.content.Intent) 637 * PendingIntent.send()} and {@link android.content.Intent#fillIn Intent.fillIn()} 638 * for details. 639 */ 640 public PendingIntent getShowIntent() { 641 return mShowIntent; 642 } 643 644 @Override 645 public int describeContents() { 646 return 0; 647 } 648 649 @Override 650 public void writeToParcel(Parcel dest, int flags) { 651 dest.writeLong(mTriggerTime); 652 dest.writeParcelable(mShowIntent, flags); 653 } 654 655 public static final Creator<AlarmClockInfo> CREATOR = new Creator<AlarmClockInfo>() { 656 @Override 657 public AlarmClockInfo createFromParcel(Parcel in) { 658 return new AlarmClockInfo(in); 659 } 660 661 @Override 662 public AlarmClockInfo[] newArray(int size) { 663 return new AlarmClockInfo[size]; 664 } 665 }; 666 } 667} 668