drgreen/android_frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Revised API documentation of Context and ServiceConnection. See b/213625234."

Browse Source
This commit is contained in:
Jon Eckenrode 2022-02-15 21:47:29 +00:00 committed by Gerrit Code Review
commit 08bb407612
2 changed files with 33 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
core/java/android/content/Context.java
View File

@ -3434,7 +3434,7 @@ public abstract class Context {
public abstract boolean stopServiceAsUser(Intent service, UserHandle user); public abstract boolean stopServiceAsUser(Intent service, UserHandle user);
/** /**
* Connect to an application service, creating it if needed. This defines * Connects to an application service, creating it if needed. This defines
* a dependency between your application and the service. The given * a dependency between your application and the service. The given
* <var>conn</var> will receive the service object when it is created and be * <var>conn</var> will receive the service object when it is created and be
* told if it dies and restarts. The service will be considered required * told if it dies and restarts. The service will be considered required
@ -3449,11 +3449,8 @@ public abstract class Context {
* will be invoked instead of * will be invoked instead of
* {@link ServiceConnection#onServiceConnected(ComponentName, IBinder) onServiceConnected()}. * {@link ServiceConnection#onServiceConnected(ComponentName, IBinder) onServiceConnected()}.
* *
* <p>This method will throw {@link SecurityException} if the calling app does not * <p class="note"><b>Note:</b> This method <em>cannot</em> be called from a
* have permission to bind to the given service. * {@link BroadcastReceiver} component. A pattern you can use to
*
* <p class="note">Note: this method <em>cannot be called from a
* {@link BroadcastReceiver} component</em>. A pattern you can use to
* communicate from a BroadcastReceiver to a Service is to call * communicate from a BroadcastReceiver to a Service is to call
* {@link #startService} with the arguments containing the command to be * {@link #startService} with the arguments containing the command to be
* sent, with the service calling its * sent, with the service calling its
@ -3468,34 +3465,34 @@ public abstract class Context {
* specify an explicit component name. * specify an explicit component name.
* @param conn Receives information as the service is started and stopped. * @param conn Receives information as the service is started and stopped.
* This must be a valid ServiceConnection object; it must not be null. * This must be a valid ServiceConnection object; it must not be null.
* @param flags Operation options for the binding. May be 0, * @param flags Operation options for the binding. Can be:
* {@link #BIND_AUTO_CREATE}, {@link #BIND_DEBUG_UNBIND}, * <ul>
* {@link #BIND_NOT_FOREGROUND}, {@link #BIND_ABOVE_CLIENT}, * <li>0
* {@link #BIND_ALLOW_OOM_MANAGEMENT}, {@link #BIND_WAIVE_PRIORITY}. * <li>{@link #BIND_AUTO_CREATE}
* {@link #BIND_IMPORTANT}, {@link #BIND_ADJUST_WITH_ACTIVITY}, * <li>{@link #BIND_DEBUG_UNBIND}
* {@link #BIND_NOT_PERCEPTIBLE}, or {@link #BIND_INCLUDE_CAPABILITIES}. * <li>{@link #BIND_NOT_FOREGROUND}
* @return {@code true} if the system is in the process of bringing up a * <li>{@link #BIND_ABOVE_CLIENT}
* <li>{@link #BIND_ALLOW_OOM_MANAGEMENT}
* <li>{@link #BIND_WAIVE_PRIORITY}
* <li>{@link #BIND_IMPORTANT}
* <li>{@link #BIND_ADJUST_WITH_ACTIVITY}
* <li>{@link #BIND_NOT_PERCEPTIBLE}
* <li>{@link #BIND_INCLUDE_CAPABILITIES}
* </ul>
*
* @return {@code true} if the system is in the process of bringing up a
* service that your client has permission to bind to; {@code false} * service that your client has permission to bind to; {@code false}
* if the system couldn't find the service or if your client doesn't * if the system couldn't find the service or if your client doesn't
* have permission to bind to it. If this value is {@code true}, you * have permission to bind to it. You should call {@link #unbindService}
* should later call {@link #unbindService} to release the * to release the connection even if this method returned {@code false}.
* connection.
* *
* @throws SecurityException If the caller does not have permission to access the service * @throws SecurityException If the caller does not have permission to
* or the service can not be found. * access the service or the service cannot be found. Call
* {@link #unbindService} to release the connection when this exception
* is thrown.
* *
* @see #unbindService * @see #unbindService
* @see #startService * @see #startService
* @see #BIND_AUTO_CREATE
* @see #BIND_DEBUG_UNBIND
* @see #BIND_NOT_FOREGROUND
* @see #BIND_ABOVE_CLIENT
* @see #BIND_ALLOW_OOM_MANAGEMENT
* @see #BIND_WAIVE_PRIORITY
* @see #BIND_IMPORTANT
* @see #BIND_ADJUST_WITH_ACTIVITY
* @see #BIND_NOT_PERCEPTIBLE
* @see #BIND_INCLUDE_CAPABILITIES
*/ */
public abstract boolean bindService(@RequiresPermission Intent service, public abstract boolean bindService(@RequiresPermission Intent service,
@NonNull ServiceConnection conn, @BindServiceFlags int flags); @NonNull ServiceConnection conn, @BindServiceFlags int flags);

12
core/java/android/content/ServiceConnection.java
View File

@ -63,8 +63,12 @@ public interface ServiceConnection {
* happen, for example, if the application hosting the service it is bound to * happen, for example, if the application hosting the service it is bound to
* has been updated. * has been updated.
* *
* @param name The concrete component name of the service whose * <p class="note"><b>Note:</b> The app that requested the binding must call
* connection is dead. * {@link Context#unbindService(ServiceConnection)} to release the tracking
* resources associated with this ServiceConnection even if this callback was
* invoked following {@link Context#bindService Context.bindService() bindService()}.
*
* @param name The concrete component name of the service whose connection is dead.
*/ */
default void onBindingDied(ComponentName name) { default void onBindingDied(ComponentName name) {
} }
@ -72,10 +76,10 @@ public interface ServiceConnection {
/** /**
* Called when the service being bound has returned {@code null} from its * Called when the service being bound has returned {@code null} from its
* {@link android.app.Service#onBind(Intent) onBind()} method. This indicates * {@link android.app.Service#onBind(Intent) onBind()} method. This indicates
* that the attempting service binding represented by this ServiceConnection * that the attempted service binding represented by this ServiceConnection
* will never become usable. * will never become usable.
* *
* <p class="note">The app which requested the binding must still call * <p class="note"><b>Note:</b> The app that requested the binding must still call
* {@link Context#unbindService(ServiceConnection)} to release the tracking * {@link Context#unbindService(ServiceConnection)} to release the tracking
* resources associated with this ServiceConnection even if this callback was * resources associated with this ServiceConnection even if this callback was
* invoked following {@link Context#bindService Context.bindService() bindService()}. * invoked following {@link Context#bindService Context.bindService() bindService()}.