AlarmManagerCompat

Added in 1.1.0

public final class AlarmManagerCompat


Compatibility library for AlarmManager with fallbacks for older platforms.

Summary

Public methods

static boolean

Called to check if the caller can schedule exact alarms.

static void
setAlarmClock(
    @NonNull AlarmManager alarmManager,
    long triggerTime,
    @NonNull PendingIntent showIntent,
    @NonNull PendingIntent operation
)

Schedule an alarm that represents an alarm clock.

static void
setAndAllowWhileIdle(
    @NonNull AlarmManager alarmManager,
    int type,
    long triggerAtMillis,
    @NonNull PendingIntent operation
)

Like set, but this alarm will be allowed to execute even when the system is in low-power idle modes.

static void
@ReplaceWith(expression = "alarmManager.setExact(type, triggerAtMillis, operation)")
setExact(
    @NonNull AlarmManager alarmManager,
    int type,
    long triggerAtMillis,
    @NonNull PendingIntent operation
)

This method is deprecated.

Call setExact directly.

static void
setExactAndAllowWhileIdle(
    @NonNull AlarmManager alarmManager,
    int type,
    long triggerAtMillis,
    @NonNull PendingIntent operation
)

Like setExact, but this alarm will be allowed to execute even when the system is in low-power idle modes.

Public methods

canScheduleExactAlarms

Added in 1.13.0
public static boolean canScheduleExactAlarms(@NonNull AlarmManager alarmManager)

Called to check if the caller can schedule exact alarms. Your app schedules exact alarms when it calls any of the setExact... or setAlarmClock API methods.

Apps targeting S or higher can schedule exact alarms only if they have the SCHEDULE_EXACT_ALARM permission or they are on the device's power-save exemption list. These apps can also start ACTION_REQUEST_SCHEDULE_EXACT_ALARM to request this permission from the user.

Apps targeting lower sdk versions, can always schedule exact alarms.

Parameters
@NonNull AlarmManager alarmManager

AlarmManager instance used to set the alarm

Returns
boolean

true if the caller can schedule exact alarms, false otherwise.

setAlarmClock

Added in 1.1.0
public static void setAlarmClock(
    @NonNull AlarmManager alarmManager,
    long triggerTime,
    @NonNull PendingIntent showIntent,
    @NonNull 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 setExact, but implies RTC_WAKEUP.

Parameters
@NonNull AlarmManager alarmManager

AlarmManager instance used to set the alarm

long triggerTime

time at which the underlying alarm is triggered in wall time milliseconds since the epoch

@NonNull PendingIntent showIntent

an intent that can be used to show or edit details of the alarm clock.

@NonNull PendingIntent operation

Action to perform when the alarm goes off; typically comes from IntentSender.getBroadcast().

setAndAllowWhileIdle

Added in 1.1.0
public static void setAndAllowWhileIdle(
    @NonNull AlarmManager alarmManager,
    int type,
    long triggerAtMillis,
    @NonNull PendingIntent operation
)

Like set, but this alarm will be allowed to execute even when the system is in low-power idle modes. This type of alarm must only be used for situations where it is actually required that the alarm go off while in idle -- a reasonable example would be for a calendar notification that should make a sound so the user is aware of it. When the alarm is dispatched, the app will also be added to the system's temporary allow-list for approximately 10 seconds to allow that application to acquire further wake locks in which to complete its work.

These alarms can significantly impact the power use of the device when idle (and thus cause significant battery blame to the app scheduling them), so they should be used with care. To reduce abuse, there are restrictions on how frequently these alarms will go off for a particular application. Under normal system operation, it will not dispatch these alarms more than about every minute (at which point every such pending alarm is dispatched); when in low-power idle modes this duration may be significantly longer, such as 15 minutes.

Unlike other alarms, the system is free to reschedule this type of alarm to happen out of order with any other alarms, even those from the same app. This will clearly happen when the device is idle (since this alarm can go off while idle, when any other alarms from the app will be held until later), but may also happen even when not idle.

Regardless of the app's target SDK version, this call always allows batching of the alarm.

Parameters
@NonNull AlarmManager alarmManager

AlarmManager instance used to set the alarm

int type

One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP, RTC, or RTC_WAKEUP.

long triggerAtMillis

time in milliseconds that the alarm should go off, using the appropriate clock (depending on the alarm type).

@NonNull PendingIntent operation

Action to perform when the alarm goes off; typically comes from IntentSender.getBroadcast().

setExact

Added in 1.1.0
Deprecated in 1.15.0
@ReplaceWith(expression = "alarmManager.setExact(type, triggerAtMillis, operation)")
public static void setExact(
    @NonNull AlarmManager alarmManager,
    int type,
    long triggerAtMillis,
    @NonNull PendingIntent operation
)

Schedule an alarm to be delivered precisely at the stated time.

This method is like set, 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.

Parameters
@NonNull AlarmManager alarmManager

AlarmManager instance used to set the alarm

int type

One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP, RTC, or RTC_WAKEUP.

long triggerAtMillis

time in milliseconds that the alarm should go off, using the appropriate clock (depending on the alarm type).

@NonNull PendingIntent operation

Action to perform when the alarm goes off; typically comes from IntentSender.getBroadcast().

setExactAndAllowWhileIdle

Added in 1.1.0
public static void setExactAndAllowWhileIdle(
    @NonNull AlarmManager alarmManager,
    int type,
    long triggerAtMillis,
    @NonNull PendingIntent operation
)

Like setExact, but this alarm will be allowed to execute even when the system is in low-power idle modes. If you don't need exact scheduling of the alarm but still need to execute while idle, consider using setAndAllowWhileIdle. This type of alarm must only be used for situations where it is actually required that the alarm go off while in idle -- a reasonable example would be for a calendar notification that should make a sound so the user is aware of it. When the alarm is dispatched, the app will also be added to the system's temporary allow-list for approximately 10 seconds to allow that application to acquire further wake locks in which to complete its work.

These alarms can significantly impact the power use of the device when idle (and thus cause significant battery blame to the app scheduling them), so they should be used with care. To reduce abuse, there are restrictions on how frequently these alarms will go off for a particular application. Under normal system operation, it will not dispatch these alarms more than about every minute (at which point every such pending alarm is dispatched); when in low-power idle modes this duration may be significantly longer, such as 15 minutes.

Unlike other alarms, the system is free to reschedule this type of alarm to happen out of order with any other alarms, even those from the same app. This will clearly happen when the device is idle (since this alarm can go off while idle, when any other alarms from the app will be held until later), but may also happen even when not idle. Note that the OS will allow itself more flexibility for scheduling these alarms than regular exact alarms, since the application has opted into this behavior. When the device is idle it may take even more liberties with scheduling in order to optimize for battery life.

Parameters
@NonNull AlarmManager alarmManager

AlarmManager instance used to set the alarm

int type

One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP, RTC, or RTC_WAKEUP.

long triggerAtMillis

time in milliseconds that the alarm should go off, using the appropriate clock (depending on the alarm type).

@NonNull PendingIntent operation

Action to perform when the alarm goes off; typically comes from IntentSender.getBroadcast().