Merge "Update the Service#onTimeout() javadoc." into main

1 files changed, 18 insertions, 0 deletions

diff --git a/core/java/android/app/Service.java b/core/java/android/app/Service.java
index f092945a5d28..9b3fb5c73415 100644
--- a/core/java/android/app/Service.java
+++ b/core/java/android/app/Service.java
@@ -1197,6 +1197,24 @@ public abstract class Service extends ContextWrapper implements ComponentCallbac
     /**
      * Callback called when a particular foreground service type has timed out.
      *
+     * <p>This callback is meant to give the app a small grace period of a few seconds to finish
+     * the foreground service of the offending type - if it fails to do so, the app will be
+     * declared an ANR.
+     *
+     * <p>The foreground service of the offending type can be stopped within the time limit by
+     * {@link android.app.Service#stopSelf()},
+     * {@link android.content.Context#stopService(android.content.Intent)} or their overloads.
+     * {@link android.app.Service#stopForeground(int)} can be used as well, which demotes the
+     * service to a "background" service, which will soon be stopped by the system.
+     *
+     * <p>The specific time limit for each type (if one exists) is mentioned in the documentation
+     * for that foreground service type.
+     *
+     * <p>Note: time limits are restricted to a rolling 24-hour window - for example, if a
+     * foreground service type has a time limit of 6 hours, that time counter begins as soon as the
+     * foreground service starts. This time limit will only be reset once every 24 hours or if the
+     * app comes into the foreground state.
+     *
      * @param startId the startId passed to {@link #onStartCommand(Intent, int, int)} when
      *                the service started.
      * @param fgsType the {@link ServiceInfo.ForegroundServiceType foreground service type} which