Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Fixing details on when clients unbind from Bound Service

Browse Source 
Docs were slightly contradictory on when clients should unbind.
Changed a few sections to point to one "source of truth" section
that explains the appropriate times to call unbindService().
Updated with corrections to issues found by Andrew and Dave.

Bug: 8135078
Change-Id: If8afb998cbd2efceef075ee6633cf0744c50d1df
This commit is contained in:
Daniel Yu
2015-11-20 14:08:34 -08:00
parent e2f1304401
commit ea58be972d
1 changed files with 16 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/html/guide/components/bound-services.jd
View File

@@ -15,7 +15,11 @@ parent.link=services.html
<li><a href="#Messenger">Using a Messenger</a></li>
</ol>
</li>
<li><a href="#Binding">Binding to a Service</a></li>
<li><a href="#Binding">Binding to a Service</a>
<ol>
<li><a href="#Additional_Notes">Additional notes</a></li>
</ol>
</li>
<li><a href="#Lifecycle">Managing the Lifecycle of a Bound Service</a></li>
</ol>
@@ -309,8 +313,11 @@ public class BindingActivity extends Activity {
android.content.ServiceConnection#onServiceConnected onServiceConnected()} callback. The next
section provides more information about this process of binding to the service.</p>
<p class="note"><strong>Note:</strong> The example above doesn't explicitly unbind from the service,
but all clients should unbind at an appropriate time (such as when the activity pauses).</p>
<p class="note"><strong>Note:</strong> In the example above, the
{@link android.app.Activity#onStop onStop()} method unbinds the client from the service. Clients
should unbind from services at appropriate times, as discussed in
<a href="#Additional_Notes">Additional Notes</a>.
</p>
<p>For more sample code, see the <a
href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code
@@ -538,10 +545,11 @@ onServiceConnected()} callback method, you can begin making calls to the service
the methods defined by the interface.</li>
<li>To disconnect from the service, call {@link
android.content.Context#unbindService unbindService()}.
<p>When your client is destroyed, it will unbind from the service, but you should always unbind
when you're done interacting with the service or when your activity pauses so that the service can
shutdown while its not being used. (Appropriate times to bind and unbind is discussed
more below.)</p>
<p>If your client is still bound to a service when your app destroys the client, destruction
causes the client to unbind. It is better practice to unbind the client as soon as it is done
interacting with the service. Doing so allows the idle service to shut down. For more information
about appropriate times to bind and unbind, see <a href="#Additional_Notes">Additional Notes</a>.
</p>
</li>
</ol>
@@ -591,7 +599,7 @@ and {@link android.content.Context#BIND_NOT_FOREGROUND}, or {@code 0} for none.<
</ul>
<h3>Additional notes</h3>
<h3 id="Additional_Notes">Additional notes</h3>
<p>Here are some important notes about binding to a service:</p>
<ul>