public class AlarmManager extends Object
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 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
Handler
.
You do not
instantiate this class directly; instead, retrieve it through
Context.getSystemService(Context.ALARM_SERVICE)
.
Modifier and Type | Field and Description |
---|---|
static int |
ELAPSED_REALTIME
Alarm time in
SystemClock.elapsedRealtime() (time since boot, including sleep). |
static int |
ELAPSED_REALTIME_WAKEUP
Alarm time in
SystemClock.elapsedRealtime() (time since boot, including sleep),
which will wake up the device when it goes off. |
static long |
INTERVAL_DAY |
static long |
INTERVAL_FIFTEEN_MINUTES
Available inexact recurrence intervals recognized by
setInexactRepeating(int, long, long, PendingIntent) |
static long |
INTERVAL_HALF_DAY |
static long |
INTERVAL_HALF_HOUR |
static long |
INTERVAL_HOUR |
static int |
RTC
Alarm time in
System.currentTimeMillis()
(wall clock time in UTC). |
static int |
RTC_WAKEUP
Alarm time in
System.currentTimeMillis()
(wall clock time in UTC), which will wake up the device when
it goes off. |
Modifier and Type | Method and Description |
---|---|
void |
cancel(PendingIntent operation)
Remove any alarms with a matching
Intent . |
void |
set(int type,
long triggerAtMillis,
PendingIntent operation)
Schedule an alarm.
|
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.
|
void |
setRepeating(int type,
long triggerAtMillis,
long intervalMillis,
PendingIntent operation)
Schedule a repeating alarm.
|
void |
setTime(long millis)
Set the system wall clock time.
|
void |
setTimeZone(String timeZone)
Set the system default time zone.
|
public static final int RTC_WAKEUP
System.currentTimeMillis()
(wall clock time in UTC), which will wake up the device when
it goes off.public static final int RTC
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_WAKEUP
SystemClock.elapsedRealtime()
(time since boot, including sleep),
which will wake up the device when it goes off.public static final int ELAPSED_REALTIME
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 long INTERVAL_FIFTEEN_MINUTES
setInexactRepeating(int, long, long, PendingIntent)
public static final long INTERVAL_HALF_HOUR
public static final long INTERVAL_HOUR
public static final long INTERVAL_HALF_DAY
public static final long INTERVAL_DAY
public void set(int type, long triggerAtMillis, PendingIntent operation)
Handler
. If there is already an alarm scheduled
for the same IntentSender, it will first be canceled.
If the time occurs 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
Intent.filterEquals(android.content.Intent)
), 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 Context.registerReceiver(android.content.BroadcastReceiver, android.content.IntentFilter)
or through the <receiver> tag in an AndroidManifest.xml file.
Alarm intents are delivered with a data extra of type int called
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.
type
- One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP, RTC or
RTC_WAKEUP.triggerAtMillis
- time in milliseconds that the alarm should go
off, using the appropriate clock (depending on the alarm type).operation
- Action to perform when the alarm goes off;
typically comes from IntentSender.getBroadcast()
.Handler
,
setRepeating(int, long, long, android.app.PendingIntent)
,
cancel(android.app.PendingIntent)
,
Context.sendBroadcast(android.content.Intent)
,
Context.registerReceiver(android.content.BroadcastReceiver, android.content.IntentFilter)
,
Intent.filterEquals(android.content.Intent)
,
ELAPSED_REALTIME
,
ELAPSED_REALTIME_WAKEUP
,
RTC
,
RTC_WAKEUP
public void setRepeating(int type, long triggerAtMillis, long intervalMillis, PendingIntent operation)
Handler
. If there is already an alarm scheduled
for the same IntentSender, it will first be canceled.
Like set(int, long, android.app.PendingIntent)
, except you can also
supply a rate at which the alarm will repeat. This alarm continues
repeating until explicitly removed with cancel(android.app.PendingIntent)
. If the time
occurs 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.
type
- One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP}, RTC or
RTC_WAKEUP.triggerAtMillis
- time in milliseconds that the alarm should first
go off, using the appropriate clock (depending on the alarm type).intervalMillis
- interval in milliseconds between subsequent repeats
of the alarm.operation
- Action to perform when the alarm goes off;
typically comes from IntentSender.getBroadcast()
.Handler
,
set(int, long, android.app.PendingIntent)
,
cancel(android.app.PendingIntent)
,
Context.sendBroadcast(android.content.Intent)
,
Context.registerReceiver(android.content.BroadcastReceiver, android.content.IntentFilter)
,
Intent.filterEquals(android.content.Intent)
,
ELAPSED_REALTIME
,
ELAPSED_REALTIME_WAKEUP
,
RTC
,
RTC_WAKEUP
public void setInexactRepeating(int type, long triggerAtMillis, long intervalMillis, PendingIntent operation)
setRepeating(int, long, long, android.app.PendingIntent)
, since the
system can adjust alarms' phase 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
setRepeating(int, long, long, android.app.PendingIntent)
instead.
type
- One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP}, RTC or
RTC_WAKEUP.triggerAtMillis
- time in milliseconds that the alarm should first
go off, using the appropriate clock (depending on the alarm type). This
is inexact: the alarm will not fire before this time, but there may be a
delay of almost an entire alarm interval before the first invocation of
the alarm.intervalMillis
- interval in milliseconds between subsequent repeats
of the alarm. If this is one of INTERVAL_FIFTEEN_MINUTES,
INTERVAL_HALF_HOUR, INTERVAL_HOUR, INTERVAL_HALF_DAY, or INTERVAL_DAY
then the alarm will be phase-aligned with other alarms to reduce the
number of wakeups. Otherwise, the alarm will be set as though the
application had called setRepeating(int, long, long, android.app.PendingIntent)
.operation
- Action to perform when the alarm goes off;
typically comes from IntentSender.getBroadcast()
.Handler
,
set(int, long, android.app.PendingIntent)
,
cancel(android.app.PendingIntent)
,
Context.sendBroadcast(android.content.Intent)
,
Context.registerReceiver(android.content.BroadcastReceiver, android.content.IntentFilter)
,
Intent.filterEquals(android.content.Intent)
,
ELAPSED_REALTIME
,
ELAPSED_REALTIME_WAKEUP
,
RTC
,
RTC_WAKEUP
,
INTERVAL_FIFTEEN_MINUTES
,
INTERVAL_HALF_HOUR
,
INTERVAL_HOUR
,
INTERVAL_HALF_DAY
,
INTERVAL_DAY
public void cancel(PendingIntent operation)
Intent
.
Any alarm, of any type, whose Intent matches this one (as defined by
Intent.filterEquals(android.content.Intent)
), will be canceled.operation
- IntentSender which matches a previously added
IntentSender.set(int, long, android.app.PendingIntent)
public void setTime(long millis)
millis
- time in milliseconds since the Epoch