Merge "Update documentation related to MODES_API changes" into main (e5f5702d) · Commits · e / os / android_frameworks_base

core/api/current.txt

+1 −1

Original line number	Diff line number	Diff line
		@@ -5395,7 +5395,7 @@ package android.app {

		public final class AutomaticZenRule implements android.os.Parcelable {
		ctor @Deprecated public AutomaticZenRule(String, android.content.ComponentName, android.net.Uri, int, boolean);
		ctor public AutomaticZenRule(@NonNull String, @Nullable android.content.ComponentName, @Nullable android.content.ComponentName, @NonNull android.net.Uri, @Nullable android.service.notification.ZenPolicy, int, boolean);
		ctor @Deprecated public AutomaticZenRule(@NonNull String, @Nullable android.content.ComponentName, @Nullable android.content.ComponentName, @NonNull android.net.Uri, @Nullable android.service.notification.ZenPolicy, int, boolean);
		ctor public AutomaticZenRule(android.os.Parcel);
		method public int describeContents();
		method public android.net.Uri getConditionId();

core/java/android/app/AutomaticZenRule.java

+14 −4

Original line number	Diff line number	Diff line
		@@ -173,8 +173,8 @@ public final class AutomaticZenRule implements Parcelable {
		* interrupt the user (e.g. via sound & vibration) while this rule
		* is active.
		* @param enabled Whether the rule is enabled.
		* @deprecated use {@link #AutomaticZenRule(String, ComponentName, ComponentName, Uri,
		* ZenPolicy, int, boolean)}.
		*
		* @deprecated Use {@link AutomaticZenRule.Builder} to construct an {@link AutomaticZenRule}.
		*/
		@Deprecated
		public AutomaticZenRule(String name, ComponentName owner, Uri conditionId,
		@@ -206,8 +206,10 @@ public final class AutomaticZenRule implements Parcelable {
		* while this rule is active. This overrides the global policy while this rule is
		* action ({@link Condition#STATE_TRUE}).
		* @param enabled Whether the rule is enabled.
		*
		* @deprecated Use {@link AutomaticZenRule.Builder} to construct an {@link AutomaticZenRule}.
		*/
		// TODO (b/309088420): deprecate this constructor in favor of the builder
		@Deprecated
		public AutomaticZenRule(@NonNull String name, @Nullable ComponentName owner,
		@Nullable ComponentName configurationActivity, @NonNull Uri conditionId,
		@Nullable ZenPolicy policy, int interruptionFilter, boolean enabled) {
		@@ -368,6 +370,9 @@ public final class AutomaticZenRule implements Parcelable {

		/**
		* Sets the zen policy.
		*
		* <p>When updating an existing rule via {@link NotificationManager#updateAutomaticZenRule},
		* a {@code null} value here means the previous policy is retained.
		*/
		public void setZenPolicy(@Nullable ZenPolicy zenPolicy) {
		this.mZenPolicy = (zenPolicy == null ? null : zenPolicy.copy());
		@@ -390,7 +395,12 @@ public final class AutomaticZenRule implements Parcelable {
		* Sets the configuration activity - an activity that handles
		* {@link NotificationManager#ACTION_AUTOMATIC_ZEN_RULE} that shows the user more information
		* about this rule and/or allows them to configure it. This is required to be non-null for rules
		* that are not backed by {@link android.service.notification.ConditionProviderService}.
		* that are not backed by a {@link android.service.notification.ConditionProviderService}.
		*
		* <p>This is exclusive with the {@code owner} supplied in the constructor; rules where a
		* configuration activity is set will not use the
		* {@link android.service.notification.ConditionProviderService} supplied there to determine
		* whether the rule should be active.
		*/
		public void setConfigurationActivity(@Nullable ComponentName componentName) {
		this.configurationActivity = getTrimmedComponentName(componentName);

core/java/android/app/NotificationManager.java

+45 −21

Original line number	Diff line number	Diff line
		@@ -270,13 +270,16 @@ public class NotificationManager {
		* Integer extra for {@link #ACTION_AUTOMATIC_ZEN_RULE_STATUS_CHANGED} containing the state of
		* the {@link AutomaticZenRule}.
		*
		* <p>
		* The value will be one of {@link #AUTOMATIC_RULE_STATUS_ENABLED},
		* <p>The value will be one of {@link #AUTOMATIC_RULE_STATUS_ENABLED},
		* {@link #AUTOMATIC_RULE_STATUS_DISABLED}, {@link #AUTOMATIC_RULE_STATUS_REMOVED},
		* {@link #AUTOMATIC_RULE_STATUS_ACTIVATED}, {@link #AUTOMATIC_RULE_STATUS_DEACTIVATED}, or
		* {@link #AUTOMATIC_RULE_STATUS_UNKNOWN}.
		* </p>
		*
		* <p>Note that the {@link #AUTOMATIC_RULE_STATUS_ACTIVATED} and
		* {@link #AUTOMATIC_RULE_STATUS_DEACTIVATED} statuses are only sent to packages targeting
		* {@link Build.VERSION_CODES#VANILLA_ICE_CREAM} and above; apps targeting a lower SDK version
		* will be sent {@link #AUTOMATIC_RULE_STATUS_UNKNOWN} in their place instead.
		*/
		// TODO (b/309101513): Add new status types to javadoc
		public static final String EXTRA_AUTOMATIC_ZEN_RULE_STATUS =
		"android.app.extra.AUTOMATIC_ZEN_RULE_STATUS";

		@@ -370,11 +373,15 @@ public class NotificationManager {
		= "android.app.action.NOTIFICATION_POLICY_ACCESS_GRANTED_CHANGED";

		/**
		* Intent that is broadcast when the state of getNotificationPolicy() changes.
		* Intent that is broadcast when the state of {@link #getNotificationPolicy()} changes.
		*
		* <p>This broadcast is only sent to registered receivers and (starting from
		* {@link Build.VERSION_CODES#Q}) receivers in packages that have been granted Do Not
		* Disturb access (see {@link #isNotificationPolicyAccessGranted()}).
		*
		* <p>Starting with {@link Build.VERSION_CODES#VANILLA_ICE_CREAM}, most calls to
		* {@link #setNotificationPolicy(Policy)} will update the app's implicit rule policy instead of
		* the global policy, so this broadcast will be sent much less frequently.
		*/
		@SdkConstant(SdkConstant.SdkConstantType.BROADCAST_INTENT_ACTION)
		public static final String ACTION_NOTIFICATION_POLICY_CHANGED
		@@ -1378,12 +1385,16 @@ public class NotificationManager {
		/**
		* Updates the given zen rule.
		*
		* <p>
		* Throws a SecurityException if policy access is not granted to this package.
		* <p>Before {@link Build.VERSION_CODES#VANILLA_ICE_CREAM}, updating a rule that is not backed
		* up by a {@link android.service.notification.ConditionProviderService} will deactivate it if
		* it was previously active. Starting with {@link Build.VERSION_CODES#VANILLA_ICE_CREAM}, this
		* will only happen if the rule's definition is actually changing.
		*
		* <p>Throws a SecurityException if policy access is not granted to this package.
		* See {@link #isNotificationPolicyAccessGranted}.
		*
		* <p>
		* Callers can only update rules that they own. See {@link AutomaticZenRule#getOwner}.
		* <p>Callers can only update rules that they own. See {@link AutomaticZenRule#getOwner}.
		*
		* @param id The id of the rule to update
		* @param automaticZenRule the rule to update.
		* @return Whether the rule was successfully updated.
		@@ -1744,9 +1755,11 @@ public class NotificationManager {
		/**
		* Gets the current user-specified default notification policy.
		*
		* <p>
		* <p>For apps targeting {@link Build.VERSION_CODES#VANILLA_ICE_CREAM} and above (with some
		* exceptions, such as companion device managers) this method will return the policy associated
		* to their implicit {@link AutomaticZenRule} instead, if it exists. See
		* {@link #setNotificationPolicy(Policy)}.
		*/
		// TODO(b/309457271): Update documentation with VANILLA_ICE_CREAM behavior.
		public Policy getNotificationPolicy() {
		INotificationManager service = getService();
		try {
		@@ -1757,15 +1770,20 @@ public class NotificationManager {
		}

		/**
		* Sets the current notification policy.
		* Sets the current notification policy (which applies when {@link #setInterruptionFilter} is
		* called with the {@link #INTERRUPTION_FILTER_PRIORITY} value).
		*
		* <p>
		* Only available if policy access is granted to this package.
		* See {@link #isNotificationPolicyAccessGranted}.
		* <p>Apps targeting {@link Build.VERSION_CODES#VANILLA_ICE_CREAM} and above (with some
		* exceptions, such as companion device managers) cannot modify the global notification policy.
		* Calling this method will instead create or update an {@link AutomaticZenRule} associated to
		* the app, using a {@link ZenPolicy} corresponding to the {@link Policy} supplied here, and
		* which will be activated/deactivated by calls to {@link #setInterruptionFilter(int)}.
		*
		* <p>Only available if policy access is granted to this package. See
		* {@link #isNotificationPolicyAccessGranted}.
		*
		* @param policy The new desired policy.
		*/
		// TODO(b/309457271): Update documentation with VANILLA_ICE_CREAM behavior.
		public void setNotificationPolicy(@NonNull Policy policy) {
		setNotificationPolicy(policy, /* fromUser= */ false);
		}
		@@ -2786,11 +2804,17 @@ public class NotificationManager {
		* The interruption filter defines which notifications are allowed to
		* interrupt the user (e.g. via sound & vibration) and is applied
		* globally.
		* <p>
		* Only available if policy access is granted to this package. See
		*
		* <p>Apps targeting {@link Build.VERSION_CODES#VANILLA_ICE_CREAM} and above (with some
		* exceptions, such as companion device managers) cannot modify the global interruption filter.
		* Calling this method will instead activate or deactivate an {@link AutomaticZenRule}
		* associated to the app, using a {@link ZenPolicy} that corresponds to the {@link Policy}
		* supplied to {@link #setNotificationPolicy(Policy)} (or the global policy when one wasn't
		* provided).
		*
		* <p> Only available if policy access is granted to this package. See
		* {@link #isNotificationPolicyAccessGranted}.
		*/
		// TODO(b/309457271): Update documentation with VANILLA_ICE_CREAM behavior.
		public final void setInterruptionFilter(@InterruptionFilter int interruptionFilter) {
		setInterruptionFilter(interruptionFilter, /* fromUser= */ false);
		}

core/java/android/service/notification/NotificationListenerService.java

+5 −0

Original line number	Diff line number	Diff line
		@@ -1212,6 +1212,11 @@ public abstract class NotificationListenerService extends Service {
		* <p>
		* Listen for updates using {@link #onInterruptionFilterChanged(int)}.
		*
		* <p>Apps targeting {@link Build.VERSION_CODES#VANILLA_ICE_CREAM} and above (with some
		* exceptions, such as companion device managers) cannot modify the global interruption filter.
		* Calling this method will instead activate or deactivate an
		* {@link android.app.AutomaticZenRule} associated to the app.
		*
		* <p>The service should wait for the {@link #onListenerConnected()} event
		* before performing this operation.
		*