AlarmManagerpublic class AlarmManager extends Object | This class provides access to the system alarm services. These allow you
to schedule your application to be run at some point in the future. When
an alarm goes off, the {@link Intent} that had been registered for it
is broadcast by the system, automatically starting the target application
if it is not already running. Registered alarms are retained while the
device is asleep (and can optionally wake the device up if they go off
during that time), but will be cleared if it is turned off and rebooted.
The Alarm Manager holds a CPU wake lock as long as the alarm receiver's
onReceive() method is executing. This guarantees that the phone will not sleep
until you have finished handling the broadcast. Once onReceive() returns, the
Alarm Manager releases this wake lock. This means that the phone will in some
cases sleep as soon as your onReceive() method completes. If your alarm receiver
called {@link android.content.Context#startService Context.startService()}, it
is possible that the phone will sleep before the requested service is launched.
To prevent this, your BroadcastReceiver and Service will need to implement a
separate wake lock policy to ensure that the phone continues running until the
service becomes available.
Note: The Alarm Manager is intended for cases where you want to have
your application code run at a specific time, even if your application is
not currently running. For normal timing operations (ticks, timeouts,
etc) it is easier and much more efficient to use
{@link android.os.Handler}.
Note: Beginning with API 19
({@link android.os.Build.VERSION_CODES#KITKAT}) alarm delivery is inexact:
the OS will shift alarms in order to minimize wakeups and battery use. There are
new APIs to support applications which need strict delivery guarantees; see
{@link #setWindow(int, long, long, PendingIntent)} and
{@link #setExact(int, long, PendingIntent)}. Applications whose {@code targetSdkVersion}
is earlier than API 19 will continue to see the previous behavior in which all
alarms are delivered exactly when requested.
You do not
instantiate this class directly; instead, retrieve it through
{@link android.content.Context#getSystemService
Context.getSystemService(Context.ALARM_SERVICE)}. |
| Fields Summary |
|---|
| private static final String | TAG | | public static final int | RTC_WAKEUPAlarm time in {@link System#currentTimeMillis System.currentTimeMillis()}
(wall clock time in UTC), which will wake up the device when
it goes off. | | public static final int | RTCAlarm time in {@link System#currentTimeMillis System.currentTimeMillis()}
(wall clock time in UTC). This alarm does not wake the
device up; if it goes off while the device is asleep, it will not be
delivered until the next time the device wakes up. | | public static final int | ELAPSED_REALTIME_WAKEUPAlarm time in {@link android.os.SystemClock#elapsedRealtime
SystemClock.elapsedRealtime()} (time since boot, including sleep),
which will wake up the device when it goes off. | | public static final int | ELAPSED_REALTIMEAlarm time in {@link android.os.SystemClock#elapsedRealtime
SystemClock.elapsedRealtime()} (time since boot, including sleep).
This alarm does not wake the device up; if it goes off while the device
is asleep, it will not be delivered until the next time the device
wakes up. | | public static final String | ACTION_NEXT_ALARM_CLOCK_CHANGEDBroadcast Action: Sent after the value returned by
{@link #getNextAlarmClock()} has changed.
This is a protected intent that can only be sent by the system.
It is only sent to registered receivers. | | public static final long | WINDOW_EXACT | | public static final long | WINDOW_HEURISTIC | | private final IAlarmManager | mService | | private final boolean | mAlwaysExact | | public static final long | INTERVAL_FIFTEEN_MINUTESAvailable inexact recurrence interval recognized by
{@link #setInexactRepeating(int, long, long, PendingIntent)}
when running on Android prior to API 19. | | public static final long | INTERVAL_HALF_HOURAvailable inexact recurrence interval recognized by
{@link #setInexactRepeating(int, long, long, PendingIntent)}
when running on Android prior to API 19. | | public static final long | INTERVAL_HOURAvailable inexact recurrence interval recognized by
{@link #setInexactRepeating(int, long, long, PendingIntent)}
when running on Android prior to API 19. | | public static final long | INTERVAL_HALF_DAYAvailable inexact recurrence interval recognized by
{@link #setInexactRepeating(int, long, long, PendingIntent)}
when running on Android prior to API 19. | | public static final long | INTERVAL_DAYAvailable inexact recurrence interval recognized by
{@link #setInexactRepeating(int, long, long, PendingIntent)}
when running on Android prior to API 19. |
| Constructors Summary |
|---|
AlarmManager(IAlarmManager service, android.content.Context ctx)package private on purpose
mService = service;
final int sdkVersion = ctx.getApplicationInfo().targetSdkVersion;
mAlwaysExact = (sdkVersion < Build.VERSION_CODES.KITKAT);
|
| Methods Summary |
|---|
| public void | cancel(PendingIntent operation)Remove any alarms with a matching {@link Intent}.
Any alarm, of any type, whose Intent matches this one (as defined by
{@link Intent#filterEquals}), will be canceled.
try {
mService.remove(operation);
} catch (RemoteException ex) {
}
| | public android.app.AlarmManager$AlarmClockInfo | getNextAlarmClock()Gets information about the next alarm clock currently scheduled.
The alarm clocks considered are those scheduled by {@link #setAlarmClock}
from any package of the calling user.
return getNextAlarmClock(UserHandle.myUserId());
| | public android.app.AlarmManager$AlarmClockInfo | getNextAlarmClock(int userId)Gets information about the next alarm clock currently scheduled.
The alarm clocks considered are those scheduled by {@link #setAlarmClock}
from any package of the given {@parm userId}.
try {
return mService.getNextAlarmClock(userId);
} catch (RemoteException ex) {
return null;
}
| | private long | legacyExactLength()
return (mAlwaysExact ? WINDOW_EXACT : WINDOW_HEURISTIC);
| | public void | set(int type, long triggerAtMillis, PendingIntent operation)Schedule an alarm. Note: for timing operations (ticks, timeouts,
etc) it is easier and much more efficient to use {@link android.os.Handler}.
If there is already an alarm scheduled for the same IntentSender, that previous
alarm will first be canceled.
If the stated trigger time is in the past, the alarm will be triggered
immediately. If there is already an alarm for this Intent
scheduled (with the equality of two intents being defined by
{@link Intent#filterEquals}), then it will be removed and replaced by
this one.
The alarm is an Intent broadcast that goes to a broadcast receiver that
you registered with {@link android.content.Context#registerReceiver}
or through the <receiver> tag in an AndroidManifest.xml file.
Alarm intents are delivered with a data extra of type int called
{@link Intent#EXTRA_ALARM_COUNT Intent.EXTRA_ALARM_COUNT} that indicates
how many past alarm events have been accumulated into this intent
broadcast. Recurring alarms that have gone undelivered because the
phone was asleep may have a count greater than one when delivered.
Note: Beginning in API 19, the trigger time passed to this method
is treated as inexact: the alarm will not be delivered before this time, but
may be deferred and delivered some time later. The OS will use
this policy in order to "batch" alarms together across the entire system,
minimizing the number of times the device needs to "wake up" and minimizing
battery use. In general, alarms scheduled in the near future will not
be deferred as long as alarms scheduled far in the future.
With the new batching policy, delivery ordering guarantees are not as
strong as they were previously. If the application sets multiple alarms,
it is possible that these alarms' actual delivery ordering may not match
the order of their requested delivery times. If your application has
strong ordering requirements there are other APIs that you can use to get
the necessary behavior; see {@link #setWindow(int, long, long, PendingIntent)}
and {@link #setExact(int, long, PendingIntent)}.
Applications whose {@code targetSdkVersion} is before API 19 will
continue to get the previous alarm behavior: all of their scheduled alarms
will be treated as exact.
setImpl(type, triggerAtMillis, legacyExactLength(), 0, operation, null, null);
| | public void | set(int type, long triggerAtMillis, long windowMillis, long intervalMillis, PendingIntent operation, android.os.WorkSource workSource)
setImpl(type, triggerAtMillis, windowMillis, intervalMillis, operation, workSource, null);
| | public void | setAlarmClock(android.app.AlarmManager$AlarmClockInfo info, PendingIntent operation)Schedule an alarm that represents an alarm clock.
The system may choose to display information about this alarm to the user.
This method is like {@link #setExact(int, long, PendingIntent)}, but implies
{@link #RTC_WAKEUP}.
setImpl(RTC_WAKEUP, info.getTriggerTime(), WINDOW_EXACT, 0, operation, null, info);
| | public void | setExact(int type, long triggerAtMillis, PendingIntent operation)Schedule an alarm to be delivered precisely at the stated time.
This method is like {@link #set(int, long, PendingIntent)}, but does not permit
the OS to adjust the delivery time. The alarm will be delivered as nearly as
possible to the requested trigger time.
Note: only alarms for which there is a strong demand for exact-time
delivery (such as an alarm clock ringing at the requested time) should be
scheduled as exact. Applications are strongly discouraged from using exact
alarms unnecessarily as they reduce the OS's ability to minimize battery use.
setImpl(type, triggerAtMillis, WINDOW_EXACT, 0, operation, null, null);
| | private void | setImpl(int type, long triggerAtMillis, long windowMillis, long intervalMillis, PendingIntent operation, android.os.WorkSource workSource, android.app.AlarmManager$AlarmClockInfo alarmClock)
if (triggerAtMillis < 0) {
/* NOTYET
if (mAlwaysExact) {
// Fatal error for KLP+ apps to use negative trigger times
throw new IllegalArgumentException("Invalid alarm trigger time "
+ triggerAtMillis);
}
*/
triggerAtMillis = 0;
}
try {
mService.set(type, triggerAtMillis, windowMillis, intervalMillis, operation,
workSource, alarmClock);
} catch (RemoteException ex) {
}
| | public void | setInexactRepeating(int type, long triggerAtMillis, long intervalMillis, PendingIntent operation)Schedule a repeating alarm that has inexact trigger time requirements;
for example, an alarm that repeats every hour, but not necessarily at
the top of every hour. These alarms are more power-efficient than
the strict recurrences traditionally supplied by {@link #setRepeating}, since the
system can adjust alarms' delivery times to cause them to fire simultaneously,
avoiding waking the device from sleep more than necessary.
Your alarm's first trigger will not be before the requested time,
but it might not occur for almost a full interval after that time. In
addition, while the overall period of the repeating alarm will be as
requested, the time between any two successive firings of the alarm
may vary. If your application demands very low jitter, use
one-shot alarms with an appropriate window instead; see {@link
#setWindow(int, long, long, PendingIntent)} and
{@link #setExact(int, long, PendingIntent)}.
As of API 19, all repeating alarms are inexact. Because this method has
been available since API 3, your application can safely call it and be
assured that it will get similar behavior on both current and older versions
of Android.
setImpl(type, triggerAtMillis, WINDOW_HEURISTIC, intervalMillis, operation, null, null);
| | public void | setRepeating(int type, long triggerAtMillis, long intervalMillis, PendingIntent operation)Schedule a repeating alarm. Note: for timing operations (ticks,
timeouts, etc) it is easier and much more efficient to use
{@link android.os.Handler}. If there is already an alarm scheduled
for the same IntentSender, it will first be canceled.
Like {@link #set}, except you can also supply a period at which
the alarm will automatically repeat. This alarm continues
repeating until explicitly removed with {@link #cancel}. If the stated
trigger time is in the past, the alarm will be triggered immediately, with an
alarm count depending on how far in the past the trigger time is relative
to the repeat interval.
If an alarm is delayed (by system sleep, for example, for non
_WAKEUP alarm types), a skipped repeat will be delivered as soon as
possible. After that, future alarms will be delivered according to the
original schedule; they do not drift over time. For example, if you have
set a recurring alarm for the top of every hour but the phone was asleep
from 7:45 until 8:45, an alarm will be sent as soon as the phone awakens,
then the next alarm will be sent at 9:00.
If your application wants to allow the delivery times to drift in
order to guarantee that at least a certain time interval always elapses
between alarms, then the approach to take is to use one-time alarms,
scheduling the next one yourself when handling each alarm delivery.
Note: as of API 19, all repeating alarms are inexact. If your
application needs precise delivery times then it must use one-time
exact alarms, rescheduling each time as described above. Legacy applications
whose {@code targetSdkVersion} is earlier than API 19 will continue to have all
of their alarms, including repeating alarms, treated as exact.
setImpl(type, triggerAtMillis, legacyExactLength(), intervalMillis, operation, null, null);
| | public void | setTime(long millis)Set the system wall clock time.
Requires the permission android.permission.SET_TIME.
try {
mService.setTime(millis);
} catch (RemoteException ex) {
}
| | public void | setTimeZone(java.lang.String timeZone)Set the system default time zone.
Requires the permission android.permission.SET_TIME_ZONE.
try {
mService.setTimeZone(timeZone);
} catch (RemoteException ex) {
}
| | public void | setWindow(int type, long windowStartMillis, long windowLengthMillis, PendingIntent operation)Schedule an alarm to be delivered within a given window of time. This method
is similar to {@link #set(int, long, PendingIntent)}, but allows the
application to precisely control the degree to which its delivery might be
adjusted by the OS. This method allows an application to take advantage of the
battery optimizations that arise from delivery batching even when it has
modest timeliness requirements for its alarms.
This method can also be used to achieve strict ordering guarantees among
multiple alarms by ensuring that the windows requested for each alarm do
not intersect.
When precise delivery is not required, applications should use the standard
{@link #set(int, long, PendingIntent)} method. This will give the OS the most
flexibility to minimize wakeups and battery use. For alarms that must be delivered
at precisely-specified times with no acceptable variation, applications can use
{@link #setExact(int, long, PendingIntent)}.
setImpl(type, windowStartMillis, windowLengthMillis, 0, operation, null, null);
|
|
