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      */
AlarmManager(IAlarmManager service, Context ctx)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 
legacyExactLength()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 &lt;receiver&gt; 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      */
set(int type, long triggerAtMillis, PendingIntent operation)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      */
setRepeating(int type, long triggerAtMillis, long intervalMillis, PendingIntent operation)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      */
setWindow(int type, long windowStartMillis, long windowLengthMillis, PendingIntent operation)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      */
setExact(int type, long triggerAtMillis, PendingIntent operation)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      */
setAlarmClock(AlarmClockInfo info, PendingIntent operation)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
set(int type, long triggerAtMillis, long windowMillis, long intervalMillis, PendingIntent operation, WorkSource workSource)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 
setImpl(int type, long triggerAtMillis, long windowMillis, long intervalMillis, PendingIntent operation, WorkSource workSource, AlarmClockInfo alarmClock)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      */
setInexactRepeating(int type, long triggerAtMillis, long intervalMillis, PendingIntent operation)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      */
cancel(PendingIntent operation)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      */
setTime(long millis)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      */
setTimeZone(String timeZone)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      */
getNextAlarmClock()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      */
getNextAlarmClock(int userId)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          */
AlarmClockInfo(long triggerTime, PendingIntent showIntent)607         public AlarmClockInfo(long triggerTime, PendingIntent showIntent) {
608             mTriggerTime = triggerTime;
609             mShowIntent = showIntent;
610         }
611 
612         /**
613          * Use the {@link #CREATOR}
614          * @hide
615          */
AlarmClockInfo(Parcel in)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          */
getTriggerTime()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          */
getShowIntent()641         public PendingIntent getShowIntent() {
642             return mShowIntent;
643         }
644 
645         @Override
describeContents()646         public int describeContents() {
647             return 0;
648         }
649 
650         @Override
writeToParcel(Parcel dest, int flags)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