From d195a9972be1a5f57ecd829e99b8e32519cd19c3 Mon Sep 17 00:00:00 2001 From: Kevin Hufnagle Date: Thu, 29 Jun 2017 15:58:48 -0700 Subject: [PATCH] Merged-In: I0906de76abf4124d74f7f4f80ac0eab3cbf94f7e docs: Revised descriptions of binding and connecting to services. Clarified that Context.bindService() returning true only indicates that the system has found a service to bind to the client and that ServiceConnection.onServiceConnected() might not be called if the service encounters an error, such as crashing during startup. Test: make ds-docs Bug: 63118511 Change-Id: I0906de76abf4124d74f7f4f80ac0eab3cbf94f7e --- core/java/android/content/Context.java | 10 ++++++---- core/java/android/content/ServiceConnection.java | 5 +++++ 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/core/java/android/content/Context.java b/core/java/android/content/Context.java index 25342aa51c27..2977fb43f442 100644 --- a/core/java/android/content/Context.java +++ b/core/java/android/content/Context.java @@ -2822,10 +2822,12 @@ public abstract class Context { * {@link #BIND_NOT_FOREGROUND}, {@link #BIND_ABOVE_CLIENT}, * {@link #BIND_ALLOW_OOM_MANAGEMENT}, or * {@link #BIND_WAIVE_PRIORITY}. - * @return If you have successfully bound to the service, {@code true} is returned; - * {@code false} is returned if the connection is not made so you will not - * receive the service object. However, you should still call - * {@link #unbindService} to release the connection. + * @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. * * @throws SecurityException If the caller does not have permission to access the service * or the service can not be found. diff --git a/core/java/android/content/ServiceConnection.java b/core/java/android/content/ServiceConnection.java index 6ff4900212ff..cf8bd41935ad 100644 --- a/core/java/android/content/ServiceConnection.java +++ b/core/java/android/content/ServiceConnection.java @@ -31,6 +31,11 @@ public interface ServiceConnection { * the {@link android.os.IBinder} of the communication channel to the * Service. * + *

Note: If the system has started to bind your + * client app to a service, it's possible that your app will never receive + * this callback. Your app won't receive a callback if there's an issue with + * the service, such as the service crashing while being created. + * * @param name The concrete component name of the service that has * been connected. * -- 2.11.0