AlarmManager.java revision 235510e67210f90de30c2d5582a2077ccc589619
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.content.Context; 21import android.content.Intent; 22import android.os.Build; 23import android.os.Parcel; 24import android.os.Parcelable; 25import android.os.RemoteException; 26import android.os.UserHandle; 27import android.os.WorkSource; 28import android.os.Parcelable.Creator; 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 public void set(int type, long triggerAtMillis, long windowMillis, long intervalMillis, 389 PendingIntent operation, WorkSource workSource) { 390 setImpl(type, triggerAtMillis, windowMillis, intervalMillis, operation, workSource, null); 391 } 392 393 private void setImpl(int type, long triggerAtMillis, long windowMillis, long intervalMillis, 394 PendingIntent operation, WorkSource workSource, AlarmClockInfo alarmClock) { 395 if (triggerAtMillis < 0) { 396 /* NOTYET 397 if (mAlwaysExact) { 398 // Fatal error for KLP+ apps to use negative trigger times 399 throw new IllegalArgumentException("Invalid alarm trigger time " 400 + triggerAtMillis); 401 } 402 */ 403 triggerAtMillis = 0; 404 } 405 406 try { 407 mService.set(type, triggerAtMillis, windowMillis, intervalMillis, operation, 408 workSource, alarmClock); 409 } catch (RemoteException ex) { 410 } 411 } 412 413 /** 414 * Available inexact recurrence interval recognized by 415 * {@link #setInexactRepeating(int, long, long, PendingIntent)} 416 * when running on Android prior to API 19. 417 */ 418 public static final long INTERVAL_FIFTEEN_MINUTES = 15 * 60 * 1000; 419 420 /** 421 * Available inexact recurrence interval recognized by 422 * {@link #setInexactRepeating(int, long, long, PendingIntent)} 423 * when running on Android prior to API 19. 424 */ 425 public static final long INTERVAL_HALF_HOUR = 2*INTERVAL_FIFTEEN_MINUTES; 426 427 /** 428 * Available inexact recurrence interval recognized by 429 * {@link #setInexactRepeating(int, long, long, PendingIntent)} 430 * when running on Android prior to API 19. 431 */ 432 public static final long INTERVAL_HOUR = 2*INTERVAL_HALF_HOUR; 433 434 /** 435 * Available inexact recurrence interval recognized by 436 * {@link #setInexactRepeating(int, long, long, PendingIntent)} 437 * when running on Android prior to API 19. 438 */ 439 public static final long INTERVAL_HALF_DAY = 12*INTERVAL_HOUR; 440 441 /** 442 * Available inexact recurrence interval recognized by 443 * {@link #setInexactRepeating(int, long, long, PendingIntent)} 444 * when running on Android prior to API 19. 445 */ 446 public static final long INTERVAL_DAY = 2*INTERVAL_HALF_DAY; 447 448 /** 449 * Schedule a repeating alarm that has inexact trigger time requirements; 450 * for example, an alarm that repeats every hour, but not necessarily at 451 * the top of every hour. These alarms are more power-efficient than 452 * the strict recurrences traditionally supplied by {@link #setRepeating}, since the 453 * system can adjust alarms' delivery times to cause them to fire simultaneously, 454 * avoiding waking the device from sleep more than necessary. 455 * 456 * <p>Your alarm's first trigger will not be before the requested time, 457 * but it might not occur for almost a full interval after that time. In 458 * addition, while the overall period of the repeating alarm will be as 459 * requested, the time between any two successive firings of the alarm 460 * may vary. If your application demands very low jitter, use 461 * one-shot alarms with an appropriate window instead; see {@link 462 * #setWindow(int, long, long, PendingIntent)} and 463 * {@link #setExact(int, long, PendingIntent)}. 464 * 465 * <p class="note"> 466 * As of API 19, all repeating alarms are inexact. Because this method has 467 * been available since API 3, your application can safely call it and be 468 * assured that it will get similar behavior on both current and older versions 469 * of Android. 470 * 471 * @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, 472 * {@link #RTC}, or {@link #RTC_WAKEUP}. 473 * @param triggerAtMillis time in milliseconds that the alarm should first 474 * go off, using the appropriate clock (depending on the alarm type). This 475 * is inexact: the alarm will not fire before this time, but there may be a 476 * delay of almost an entire alarm interval before the first invocation of 477 * the alarm. 478 * @param intervalMillis interval in milliseconds between subsequent repeats 479 * of the alarm. Prior to API 19, if this is one of INTERVAL_FIFTEEN_MINUTES, 480 * INTERVAL_HALF_HOUR, INTERVAL_HOUR, INTERVAL_HALF_DAY, or INTERVAL_DAY 481 * then the alarm will be phase-aligned with other alarms to reduce the 482 * number of wakeups. Otherwise, the alarm will be set as though the 483 * application had called {@link #setRepeating}. As of API 19, all repeating 484 * alarms will be inexact and subject to batching with other alarms regardless 485 * of their stated repeat interval. 486 * @param operation Action to perform when the alarm goes off; 487 * typically comes from {@link PendingIntent#getBroadcast 488 * IntentSender.getBroadcast()}. 489 * 490 * @see android.os.Handler 491 * @see #set 492 * @see #cancel 493 * @see android.content.Context#sendBroadcast 494 * @see android.content.Context#registerReceiver 495 * @see android.content.Intent#filterEquals 496 * @see #ELAPSED_REALTIME 497 * @see #ELAPSED_REALTIME_WAKEUP 498 * @see #RTC 499 * @see #RTC_WAKEUP 500 * @see #INTERVAL_FIFTEEN_MINUTES 501 * @see #INTERVAL_HALF_HOUR 502 * @see #INTERVAL_HOUR 503 * @see #INTERVAL_HALF_DAY 504 * @see #INTERVAL_DAY 505 */ 506 public void setInexactRepeating(int type, long triggerAtMillis, 507 long intervalMillis, PendingIntent operation) { 508 setImpl(type, triggerAtMillis, WINDOW_HEURISTIC, intervalMillis, operation, null, null); 509 } 510 511 /** 512 * Remove any alarms with a matching {@link Intent}. 513 * Any alarm, of any type, whose Intent matches this one (as defined by 514 * {@link Intent#filterEquals}), will be canceled. 515 * 516 * @param operation IntentSender which matches a previously added 517 * IntentSender. 518 * 519 * @see #set 520 */ 521 public void cancel(PendingIntent operation) { 522 try { 523 mService.remove(operation); 524 } catch (RemoteException ex) { 525 } 526 } 527 528 /** 529 * Set the system wall clock time. 530 * Requires the permission android.permission.SET_TIME. 531 * 532 * @param millis time in milliseconds since the Epoch 533 */ 534 public void setTime(long millis) { 535 try { 536 mService.setTime(millis); 537 } catch (RemoteException ex) { 538 } 539 } 540 541 /** 542 * Set the system default time zone. 543 * Requires the permission android.permission.SET_TIME_ZONE. 544 * 545 * @param timeZone in the format understood by {@link java.util.TimeZone} 546 */ 547 public void setTimeZone(String timeZone) { 548 try { 549 mService.setTimeZone(timeZone); 550 } catch (RemoteException ex) { 551 } 552 } 553 554 /** 555 * Gets information about the next alarm clock currently scheduled. 556 * 557 * The alarm clocks considered are those scheduled by {@link #setAlarmClock} 558 * from any package of the calling user. 559 * 560 * @see #setAlarmClock 561 * @see AlarmClockInfo 562 */ 563 public AlarmClockInfo getNextAlarmClock() { 564 return getNextAlarmClock(UserHandle.myUserId()); 565 } 566 567 /** 568 * Gets information about the next alarm clock currently scheduled. 569 * 570 * The alarm clocks considered are those scheduled by {@link #setAlarmClock} 571 * from any package of the given {@parm userId}. 572 * 573 * @see #setAlarmClock 574 * @see AlarmClockInfo 575 * 576 * @hide 577 */ 578 public AlarmClockInfo getNextAlarmClock(int userId) { 579 try { 580 return mService.getNextAlarmClock(userId); 581 } catch (RemoteException ex) { 582 return null; 583 } 584 } 585 586 /** 587 * An immutable description of an alarm clock. 588 * 589 * @see AlarmManager#setAlarmClock 590 * @see AlarmManager#getNextAlarmClock 591 */ 592 public static final class AlarmClockInfo implements Parcelable { 593 594 private final long mTriggerTime; 595 private final PendingIntent mShowIntent; 596 597 /** 598 * Creates a new alarm clock description. 599 * 600 * @param triggerTime time at which the underlying alarm is triggered in wall time 601 * milliseconds since the epoch 602 * @param showIntent an intent that can be used to show or edit details of 603 * the alarm clock. 604 */ 605 public AlarmClockInfo(long triggerTime, PendingIntent showIntent) { 606 mTriggerTime = triggerTime; 607 mShowIntent = showIntent; 608 } 609 610 /** 611 * Use the {@link #CREATOR} 612 * @hide 613 */ 614 AlarmClockInfo(Parcel in) { 615 mTriggerTime = in.readLong(); 616 mShowIntent = in.readParcelable(PendingIntent.class.getClassLoader()); 617 } 618 619 /** 620 * Returns the time at which the alarm is going to trigger. 621 * 622 * This value is UTC wall clock time in milliseconds, as returned by 623 * {@link System#currentTimeMillis()} for example. 624 */ 625 public long getTriggerTime() { 626 return mTriggerTime; 627 } 628 629 /** 630 * Returns an intent intent that can be used to show or edit details of the alarm clock in 631 * the application that scheduled it. 632 * 633 * <p class="note">Beware that any application can retrieve and send this intent, 634 * potentially with additional fields filled in. See 635 * {@link PendingIntent#send(android.content.Context, int, android.content.Intent) 636 * PendingIntent.send()} and {@link android.content.Intent#fillIn Intent.fillIn()} 637 * for details. 638 */ 639 public PendingIntent getShowIntent() { 640 return mShowIntent; 641 } 642 643 @Override 644 public int describeContents() { 645 return 0; 646 } 647 648 @Override 649 public void writeToParcel(Parcel dest, int flags) { 650 dest.writeLong(mTriggerTime); 651 dest.writeParcelable(mShowIntent, flags); 652 } 653 654 public static final Creator<AlarmClockInfo> CREATOR = new Creator<AlarmClockInfo>() { 655 @Override 656 public AlarmClockInfo createFromParcel(Parcel in) { 657 return new AlarmClockInfo(in); 658 } 659 660 @Override 661 public AlarmClockInfo[] newArray(int size) { 662 return new AlarmClockInfo[size]; 663 } 664 }; 665 } 666} 667