Merge "DOCS: document API 19+ Alarm Manager API and behaviors" into klp-dev
This commit is contained in:
Christopher Tate
committed by
Android (Google) Code Review
Android (Google) Code Review
commit
6aedab9b64
@ -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.
|
||||
*
|
||||
@ -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;
|
||||
@ -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.
|
||||
*
|
||||
@ -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
|
||||
@ -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.
|
||||
*
|
||||
* @param type One of ELAPSED_REALTIME, ELAPSED_REALTIME_WAKEUP, RTC or
|
||||
* RTC_WAKEUP.
|
||||
* <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 {@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
|
||||
@ -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);
|
||||
@ -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
|
||||
|
||||
Reference in New Issue
Block a user