Loading core/java/android/app/AlarmManager.java +97 −25 Original line number Diff line number Diff line Loading @@ -109,21 +109,19 @@ public class AlarmManager } /** * TBW: discussion of fuzzy nature of alarms in KLP+. * * <p>Schedule an 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. * 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, that previous * alarm will first be canceled. * * <p>If the time occurs in the past, the alarm will be triggered * <p>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. * * <p> * The alarm is an intent broadcast that goes to a broadcast receiver that * 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. * Loading @@ -134,8 +132,31 @@ public class AlarmManager * broadcast. Recurring alarms that have gone undelivered because the * phone was asleep may have a count greater than one when delivered. * * @param type One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP, RTC or * RTC_WAKEUP. * <p> * <b>Note:</b> 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. * * <p> * 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' <i>actual</i> delivery ordering may not match * the order of their <i>requested</i> 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)}. * * <p> * <b>Note:</b> Applications whose targetSdkVersion is before API 19 will * continue to get the previous alarm behavior: all of their scheduled alarms * will be 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 go * off, using the appropriate clock (depending on the alarm type). * @param operation Action to perform when the alarm goes off; Loading Loading @@ -165,10 +186,10 @@ public class AlarmManager * {@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 rate at which the alarm will repeat. This alarm continues * repeating until explicitly removed with {@link #cancel}. If the time * occurs in the past, the alarm will be triggered immediately, with an * <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. * Loading @@ -185,8 +206,15 @@ public class AlarmManager * between alarms, then the approach to take is to use one-time alarms, * scheduling the next one yourself when handling each alarm delivery. * * @param type One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP}, RTC or * RTC_WAKEUP. * <p> * <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 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 Loading Loading @@ -214,18 +242,32 @@ public class AlarmManager } /** * Schedule an alarm to be delivered within a given window of time. * 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. * * TBW: clean up these docs * <p> * This method can also be used to achieve strict ordering guarantees 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 * ability 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 ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP, RTC or * RTC_WAKEUP. * @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 the windowStartMillis time. Note that this parameter * 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 Loading @@ -249,8 +291,38 @@ public class AlarmManager } /** * TBW: new 'exact' alarm that must be delivered as nearly as possible * to the precise time specified. * 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); Loading Loading @@ -332,8 +404,8 @@ public class AlarmManager * may vary. If your application demands very low jitter, use * {@link #setRepeating} instead. * * @param type One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP}, RTC or * RTC_WAKEUP. * @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 Loading Loading
core/java/android/app/AlarmManager.java +97 −25 Original line number Diff line number Diff line Loading @@ -109,21 +109,19 @@ public class AlarmManager } /** * TBW: discussion of fuzzy nature of alarms in KLP+. * * <p>Schedule an 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. * 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, that previous * alarm will first be canceled. * * <p>If the time occurs in the past, the alarm will be triggered * <p>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. * * <p> * The alarm is an intent broadcast that goes to a broadcast receiver that * 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. * Loading @@ -134,8 +132,31 @@ public class AlarmManager * broadcast. Recurring alarms that have gone undelivered because the * phone was asleep may have a count greater than one when delivered. * * @param type One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP, RTC or * RTC_WAKEUP. * <p> * <b>Note:</b> 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. * * <p> * 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' <i>actual</i> delivery ordering may not match * the order of their <i>requested</i> 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)}. * * <p> * <b>Note:</b> Applications whose targetSdkVersion is before API 19 will * continue to get the previous alarm behavior: all of their scheduled alarms * will be 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 go * off, using the appropriate clock (depending on the alarm type). * @param operation Action to perform when the alarm goes off; Loading Loading @@ -165,10 +186,10 @@ public class AlarmManager * {@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 rate at which the alarm will repeat. This alarm continues * repeating until explicitly removed with {@link #cancel}. If the time * occurs in the past, the alarm will be triggered immediately, with an * <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. * Loading @@ -185,8 +206,15 @@ public class AlarmManager * between alarms, then the approach to take is to use one-time alarms, * scheduling the next one yourself when handling each alarm delivery. * * @param type One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP}, RTC or * RTC_WAKEUP. * <p> * <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 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 Loading Loading @@ -214,18 +242,32 @@ public class AlarmManager } /** * Schedule an alarm to be delivered within a given window of time. * 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. * * TBW: clean up these docs * <p> * This method can also be used to achieve strict ordering guarantees 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 * ability 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 ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP, RTC or * RTC_WAKEUP. * @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 the windowStartMillis time. Note that this parameter * 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 Loading @@ -249,8 +291,38 @@ public class AlarmManager } /** * TBW: new 'exact' alarm that must be delivered as nearly as possible * to the precise time specified. * 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); Loading Loading @@ -332,8 +404,8 @@ public class AlarmManager * may vary. If your application demands very low jitter, use * {@link #setRepeating} instead. * * @param type One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP}, RTC or * RTC_WAKEUP. * @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 Loading
