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);
/**
* 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
* <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
@ -3449,11 +3449,8 @@ public abstract class Context {
* will be invoked instead of
* {@link ServiceConnection#onServiceConnected(ComponentName, IBinder) onServiceConnected()}.
*
* <p>This method will throw {@link SecurityException} if the calling app does not
* have permission to bind to the given service.
*
* <p class="note">Note: this method <em>cannot be called from a
* {@link BroadcastReceiver} component</em>. A pattern you can use to
* <p class="note"><b>Note:</b> This method <em>cannot</em> be called from a
* {@link BroadcastReceiver} component. A pattern you can use to
* communicate from a BroadcastReceiver to a Service is to call
* {@link #startService} with the arguments containing the command to be
* sent, with the service calling its
@ -3468,34 +3465,34 @@ public abstract class Context {
* specify an explicit component name.
* @param conn Receives information as the service is started and stopped.
* This must be a valid ServiceConnection object; it must not be null.
* @param flags Operation options for the binding. May be 0,
* {@link #BIND_AUTO_CREATE}, {@link #BIND_DEBUG_UNBIND},
* {@link #BIND_NOT_FOREGROUND}, {@link #BIND_ABOVE_CLIENT},
* {@link #BIND_ALLOW_OOM_MANAGEMENT}, {@link #BIND_WAIVE_PRIORITY}.
* {@link #BIND_IMPORTANT}, {@link #BIND_ADJUST_WITH_ACTIVITY},
* {@link #BIND_NOT_PERCEPTIBLE}, or {@link #BIND_INCLUDE_CAPABILITIES}.
* @return {@code true} if the system is in the process of bringing up a
* @param flags Operation options for the binding. Can be:
* <ul>
* <li>0
* <li>{@link #BIND_AUTO_CREATE}
* <li>{@link #BIND_DEBUG_UNBIND}
* <li>{@link #BIND_NOT_FOREGROUND}
* <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}
* 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
* should later call {@link #unbindService} to release the
* connection.
* have permission to bind to it. You should call {@link #unbindService}
* to release the connection even if this method returned {@code false}.
*
* @throws SecurityException If the caller does not have permission to access the service
* or the service can not be found.
* @throws SecurityException If the caller does not have permission to
* access the service or the service cannot be found. Call
* {@link #unbindService} to release the connection when this exception
* is thrown.
*
* @see #unbindService
* @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,
@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
* has been updated.
*
* @param name The concrete component name of the service whose
* connection is dead.
* <p class="note"><b>Note:</b> The app that requested the binding must call
* {@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) {
}
@ -72,10 +76,10 @@ public interface ServiceConnection {
/**
* Called when the service being bound has returned {@code null} from its
* {@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.
*
* <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
* resources associated with this ServiceConnection even if this callback was
* invoked following {@link Context#bindService Context.bindService() bindService()}.