/** @hide */
public void set(
int type,
long triggerAtMillis,
long windowMillis,
long intervalMillis,
PendingIntent operation,
WorkSource workSource) {
setImpl(type, triggerAtMillis, windowMillis, intervalMillis, operation, workSource);
}
/**
* 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.
*
* <p>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)}.
*
* <p class="note">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.
*
* @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, {@link #RTC},
* or {@link #RTC_WAKEUP}.
* @param 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.
* @param intervalMillis interval in milliseconds between subsequent repeats of the alarm. Prior
* to API 19, 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 {@link #setRepeating}. As of API 19, all repeating alarms will be inexact and
* subject to batching with other alarms regardless of their stated repeat interval.
* @param operation Action to perform when the alarm goes off; typically comes from {@link
* PendingIntent#getBroadcast IntentSender.getBroadcast()}.
* @see android.os.Handler
* @see #set
* @see #cancel
* @see android.content.Context#sendBroadcast
* @see android.content.Context#registerReceiver
* @see android.content.Intent#filterEquals
* @see #ELAPSED_REALTIME
* @see #ELAPSED_REALTIME_WAKEUP
* @see #RTC
* @see #RTC_WAKEUP
* @see #INTERVAL_FIFTEEN_MINUTES
* @see #INTERVAL_HALF_HOUR
* @see #INTERVAL_HOUR
* @see #INTERVAL_HALF_DAY
* @see #INTERVAL_DAY
*/
public void setInexactRepeating(
int type, long triggerAtMillis, long intervalMillis, PendingIntent operation) {
setImpl(type, triggerAtMillis, WINDOW_HEURISTIC, intervalMillis, operation, null);
}
/**
* 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.
*
* <p>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.
*
* <p>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)}.
*
* @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, {@link #RTC},
* or {@link #RTC_WAKEUP}.
* @param windowStartMillis The earliest time, in milliseconds, that the alarm should be
* delivered, expressed in the appropriate clock's units (depending on the alarm type).
* @param windowLengthMillis The length of the requested delivery window, in milliseconds. The
* alarm will be delivered no later than this many milliseconds after {@code
* windowStartMillis}. Note that this parameter is a <i>duration,</i> not the timestamp of the
* end of the window.
* @param operation Action to perform when the alarm goes off; typically comes from {@link
* PendingIntent#getBroadcast IntentSender.getBroadcast()}.
* @see #set
* @see #setExact
* @see #setRepeating
* @see #cancel
* @see android.content.Context#sendBroadcast
* @see android.content.Context#registerReceiver
* @see android.content.Intent#filterEquals
* @see #ELAPSED_REALTIME
* @see #ELAPSED_REALTIME_WAKEUP
* @see #RTC
* @see #RTC_WAKEUP
*/
public void setWindow(
int type, long windowStartMillis, long windowLengthMillis, PendingIntent operation) {
setImpl(type, windowStartMillis, windowLengthMillis, 0, operation, null);
}
/**
* Schedule an alarm to be delivered precisely at the stated time.
*
* <p>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.
*
* <p><b>Note:</b> 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.
*
* @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, {@link #RTC},
* or {@link #RTC_WAKEUP}.
* @param triggerAtMillis time in milliseconds that the alarm should go off, using the appropriate
* clock (depending on the alarm type).
* @param operation Action to perform when the alarm goes off; typically comes from {@link
* PendingIntent#getBroadcast IntentSender.getBroadcast()}.
* @see #set
* @see #setRepeating
* @see #setWindow
* @see #cancel
* @see android.content.Context#sendBroadcast
* @see android.content.Context#registerReceiver
* @see android.content.Intent#filterEquals
* @see #ELAPSED_REALTIME
* @see #ELAPSED_REALTIME_WAKEUP
* @see #RTC
* @see #RTC_WAKEUP
*/
public void setExact(int type, long triggerAtMillis, PendingIntent operation) {
setImpl(type, triggerAtMillis, WINDOW_EXACT, 0, operation, null);
}
/**
* Schedule a repeating alarm. <b>Note: for timing operations (ticks, timeouts, etc) it is easier
* and much more efficient to use {@link android.os.Handler}.</b> If there is already an alarm
* scheduled for the same IntentSender, it will first be canceled.
*
* <p>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.
*
* <p>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.
*
* <p>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.
*
* <p class="note"><b>Note:</b> 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.
*
* @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP}, {@link #RTC},
* or {@link #RTC_WAKEUP}.
* @param triggerAtMillis time in milliseconds that the alarm should first go off, using the
* appropriate clock (depending on the alarm type).
* @param intervalMillis interval in milliseconds between subsequent repeats of the alarm.
* @param operation Action to perform when the alarm goes off; typically comes from {@link
* PendingIntent#getBroadcast IntentSender.getBroadcast()}.
* @see android.os.Handler
* @see #set
* @see #setExact
* @see #setWindow
* @see #cancel
* @see android.content.Context#sendBroadcast
* @see android.content.Context#registerReceiver
* @see android.content.Intent#filterEquals
* @see #ELAPSED_REALTIME
* @see #ELAPSED_REALTIME_WAKEUP
* @see #RTC
* @see #RTC_WAKEUP
*/
public void setRepeating(
int type, long triggerAtMillis, long intervalMillis, PendingIntent operation) {
setImpl(type, triggerAtMillis, legacyExactLength(), intervalMillis, operation, null);
}
