am f7d74870: am 6364c26c: Merge "Un-deprecate setInexactRepeating() and tweak docs" into klp-dev (13c4645b) · Commits · e / os / android_frameworks_base

api/current.txt

+6 −6

core/java/android/app/AlarmManager.java

+52 −33

Original line number	Original line	Diff line number	Diff line
	@@ -48,6 +48,15 @@ import android.os.WorkSource;
	* etc) it is easier and much more efficient to use		* etc) it is easier and much more efficient to use
	* {@link android.os.Handler}.</b>		* {@link android.os.Handler}.</b>
	*		*
			* <p class="caution"><strong>Note:</strong> Beginning with API 19
			* ({@link android.os.Build.VERSION_CODES#KITKAT}) alarm delivery is inexact:
			* the OS will shift alarms in order to minimize wakeups and battery use. There are
			* new APIs to support applications which need strict delivery guarantees; see
			* {@link #setWindow(int, long, long, PendingIntent)} and
			* {@link #setExact(int, long, PendingIntent)}. Applications whose {@code targetSdkVersion}
			* is earlier than API 19 will continue to see the previous behavior in which all
			* alarms are delivered exactly when requested.
			*
	* <p>You do not		* <p>You do not
	* instantiate this class directly; instead, retrieve it through		* instantiate this class directly; instead, retrieve it through
	* {@link android.content.Context#getSystemService		* {@link android.content.Context#getSystemService
	@@ -132,6 +141,7 @@ public class AlarmManager
	* broadcast. Recurring alarms that have gone undelivered because the		* broadcast. Recurring alarms that have gone undelivered because the
	* phone was asleep may have a count greater than one when delivered.		* phone was asleep may have a count greater than one when delivered.
	*		*
			* <div class="note">
	* <p>		* <p>
	* <b>Note:</b> Beginning in API 19, the trigger time passed to this method		* <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		* is treated as inexact: the alarm will not be delivered before this time, but
	@@ -144,16 +154,17 @@ public class AlarmManager
	* <p>		* <p>
	* With the new batching policy, delivery ordering guarantees are not as		* With the new batching policy, delivery ordering guarantees are not as
	* strong as they were previously. If the application sets multiple alarms,		* 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		* it is possible that these alarms' <em>actual</em> delivery ordering may not match
	* the order of their <i>requested</i> delivery times. If your application has		* the order of their <em>requested</em> delivery times. If your application has
	* strong ordering requirements there are other APIs that you can use to get		* strong ordering requirements there are other APIs that you can use to get
	* the necessary behavior; see {@link #setWindow(int, long, long, PendingIntent)}		* the necessary behavior; see {@link #setWindow(int, long, long, PendingIntent)}
	* and {@link #setExact(int, long, PendingIntent)}.		* and {@link #setExact(int, long, PendingIntent)}.
	*		*
	* <p>		* <p>
	* <b>Note:</b> Applications whose targetSdkVersion is before API 19 will		* Applications whose {@code targetSdkVersion} is before API 19 will
	* continue to get the previous alarm behavior: all of their scheduled alarms		* continue to get the previous alarm behavior: all of their scheduled alarms
	* will be treated as exact.		* will be treated as exact.
			* </div>
	*		*
	* @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},		* @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},
	* {@link #RTC}, or {@link #RTC_WAKEUP}.		* {@link #RTC}, or {@link #RTC_WAKEUP}.
	@@ -206,11 +217,11 @@ public class AlarmManager
	* between alarms, then the approach to take is to use one-time alarms,		* between alarms, then the approach to take is to use one-time alarms,
	* scheduling the next one yourself when handling each alarm delivery.		* scheduling the next one yourself when handling each alarm delivery.
	*		*
	* <p>		* <p class="note">
	* <b>Note:</b> as of API 19, all repeating alarms are inexact. If your		* <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		* application needs precise delivery times then it must use one-time
	* exact alarms, rescheduling each time as described above. Legacy applications		* exact alarms, rescheduling each time as described above. Legacy applications
	* whose targetSdkVersion is earlier than API 19 will continue to have all		* whose {@code targetSdkVersion} is earlier than API 19 will continue to have all
	* of their alarms, including repeating alarms, treated as exact.		* of their alarms, including repeating alarms, treated as exact.
	*		*
	* @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},		* @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},
	@@ -250,18 +261,19 @@ public class AlarmManager
	* modest timeliness requirements for its alarms.		* modest timeliness requirements for its alarms.
	*		*
	* <p>		* <p>
	* This method can also be used to achieve strict ordering guarantees by ensuring		* This method can also be used to achieve strict ordering guarantees among
	* that the windows requested for each alarm do not intersect.		* multiple alarms by ensuring that the windows requested for each alarm do
			* not intersect.
	*		*
	* <p>		* <p>
	* When precise delivery is not required, applications should use the standard		* When precise delivery is not required, applications should use the standard
	* {@link #set(int, long, PendingIntent)} method. This will give the OS the most		* {@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		* flexibility to minimize wakeups and battery use. For alarms that must be delivered
	* at precisely-specified times with no acceptable variation, applications can use		* at precisely-specified times with no acceptable variation, applications can use
	* {@link #setExact(int, long, PendingIntent)}.		* {@link #setExact(int, long, PendingIntent)}.
	*		*
	* @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},		* @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},
	* {@link #RTC}, or {@link #RTC_WAKEUP		* {@link #RTC}, or {@link #RTC_WAKEUP}.
	* @param windowStartMillis The earliest time, in milliseconds, that the alarm should		* @param windowStartMillis The earliest time, in milliseconds, that the alarm should
	* be delivered, expressed in the appropriate clock's units (depending on the alarm		* be delivered, expressed in the appropriate clock's units (depending on the alarm
	* type).		* type).
	@@ -355,46 +367,46 @@ public class AlarmManager
	}		}

	/**		/**
	* @deprecated setInexactRepeating() is deprecated; as of API 19 all		* Available inexact recurrence interval recognized by
	* repeating alarms are inexact.		* {@link #setInexactRepeating(int, long, long, PendingIntent)}
			* when running on Android prior to API 19.
	*/		*/
	@Deprecated
	public static final long INTERVAL_FIFTEEN_MINUTES = 15 * 60 * 1000;		public static final long INTERVAL_FIFTEEN_MINUTES = 15 * 60 * 1000;

	/**		/**
	* @deprecated setInexactRepeating() is deprecated; as of API 19 all		* Available inexact recurrence interval recognized by
	* repeating alarms are inexact.		* {@link #setInexactRepeating(int, long, long, PendingIntent)}
			* when running on Android prior to API 19.
	*/		*/
	@Deprecated
	public static final long INTERVAL_HALF_HOUR = 2*INTERVAL_FIFTEEN_MINUTES;		public static final long INTERVAL_HALF_HOUR = 2*INTERVAL_FIFTEEN_MINUTES;

	/**		/**
	* @deprecated setInexactRepeating() is deprecated; as of API 19 all		* Available inexact recurrence interval recognized by
	* repeating alarms are inexact.		* {@link #setInexactRepeating(int, long, long, PendingIntent)}
			* when running on Android prior to API 19.
	*/		*/
	@Deprecated
	public static final long INTERVAL_HOUR = 2*INTERVAL_HALF_HOUR;		public static final long INTERVAL_HOUR = 2*INTERVAL_HALF_HOUR;

	/**		/**
	* @deprecated setInexactRepeating() is deprecated; as of API 19 all		* Available inexact recurrence interval recognized by
	* repeating alarms are inexact.		* {@link #setInexactRepeating(int, long, long, PendingIntent)}
			* when running on Android prior to API 19.
	*/		*/
	@Deprecated
	public static final long INTERVAL_HALF_DAY = 12*INTERVAL_HOUR;		public static final long INTERVAL_HALF_DAY = 12*INTERVAL_HOUR;

	/**		/**
	* @deprecated setInexactRepeating() is deprecated; as of API 19 all		* Available inexact recurrence interval recognized by
	* repeating alarms are inexact.		* {@link #setInexactRepeating(int, long, long, PendingIntent)}
			* when running on Android prior to API 19.
	*/		*/
	@Deprecated
	public static final long INTERVAL_DAY = 2*INTERVAL_HALF_DAY;		public static final long INTERVAL_DAY = 2*INTERVAL_HALF_DAY;

	/**		/**
	* Schedule a repeating alarm that has inexact trigger time requirements;		* Schedule a repeating alarm that has inexact trigger time requirements;
	* for example, an alarm that repeats every hour, but not necessarily at		* 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 top of every hour. These alarms are more power-efficient than
	* the strict recurrences supplied by {@link #setRepeating}, since the		* the strict recurrences traditionally supplied by {@link #setRepeating}, since the
	* system can adjust alarms' phase to cause them to fire simultaneously,		* system can adjust alarms' delivery times to cause them to fire simultaneously,
	* avoiding waking the device from sleep more than necessary.		* avoiding waking the device from sleep more than necessary.
	*		*
	* <p>Your alarm's first trigger will not be before the requested time,		* <p>Your alarm's first trigger will not be before the requested time,
	@@ -402,7 +414,15 @@ public class AlarmManager
	* addition, while the overall period of the repeating alarm will be as		* addition, while the overall period of the repeating alarm will be as
	* requested, the time between any two successive firings of the alarm		* requested, the time between any two successive firings of the alarm
	* may vary. If your application demands very low jitter, use		* may vary. If your application demands very low jitter, use
	* {@link #setRepeating} instead.		* 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},		* @param type One of {@link #ELAPSED_REALTIME}, {@link #ELAPSED_REALTIME_WAKEUP},
	* {@link #RTC}, or {@link #RTC_WAKEUP}.		* {@link #RTC}, or {@link #RTC_WAKEUP}.
	@@ -412,17 +432,17 @@ public class AlarmManager
	* delay of almost an entire alarm interval before the first invocation of		* delay of almost an entire alarm interval before the first invocation of
	* the alarm.		* the alarm.
	* @param intervalMillis interval in milliseconds between subsequent repeats		* @param intervalMillis interval in milliseconds between subsequent repeats
	* of the alarm. If this is one of INTERVAL_FIFTEEN_MINUTES,		* 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		* INTERVAL_HALF_HOUR, INTERVAL_HOUR, INTERVAL_HALF_DAY, or INTERVAL_DAY
	* then the alarm will be phase-aligned with other alarms to reduce the		* 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		* number of wakeups. Otherwise, the alarm will be set as though the
	* application had called {@link #setRepeating}.		* 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;		* @param operation Action to perform when the alarm goes off;
	* typically comes from {@link PendingIntent#getBroadcast		* typically comes from {@link PendingIntent#getBroadcast
	* IntentSender.getBroadcast()}.		* IntentSender.getBroadcast()}.
	*		*
	* @deprecated As of API 19, all repeating alarms are inexact.
	*
	* @see android.os.Handler		* @see android.os.Handler
	* @see #set		* @see #set
	* @see #cancel		* @see #cancel
	@@ -439,7 +459,6 @@ public class AlarmManager
	* @see #INTERVAL_HALF_DAY		* @see #INTERVAL_HALF_DAY
	* @see #INTERVAL_DAY		* @see #INTERVAL_DAY
	*/		*/
	@Deprecated
	public void setInexactRepeating(int type, long triggerAtMillis,		public void setInexactRepeating(int type, long triggerAtMillis,
	long intervalMillis, PendingIntent operation) {		long intervalMillis, PendingIntent operation) {
	setImpl(type, triggerAtMillis, WINDOW_HEURISTIC, intervalMillis, operation, null);		setImpl(type, triggerAtMillis, WINDOW_HEURISTIC, intervalMillis, operation, null);