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