bound-services.jd revision e40c4636d970c50f7719e7d5067963be93c25750
12150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainpage.title=Bound Services 22150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainparent.title=Services 32150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainparent.link=services.html 42150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main@jd:body 52150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 62150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 72150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<div id="qv-wrapper"> 82150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<ol id="qv"> 92150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<h2>Quickview</h2> 102150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<ul> 112150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>A bound service allows other components to bind to it, in order to interact with it and 122150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainperform interprocess communication</li> 132150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>A bound service is destroyed once all clients unbind, unless the service was also started</li> 142150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</ul> 152150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<h2>In this document</h2> 162150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<ol> 172150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li><a href="#Basics">The Basics</a></li> 182150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li><a href="#Creating">Creating a Bound Service</a> 192150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <ol> 202150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li><a href="#Binder">Extending the Binder class</a></li> 212150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li><a href="#Messenger">Using a Messenger</a></li> 222150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main </ol> 232150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main </li> 242150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li><a href="#Binding">Binding to a Service</a></li> 252150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li><a href="#Lifecycle">Managing the Lifecycle of a Bound Service</a></li> 262150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</ol> 272150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 282150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<h2>Key classes</h2> 292150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<ol> 302150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>{@link android.app.Service}</li> 312150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>{@link android.content.ServiceConnection}</li> 322150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>{@link android.os.IBinder}</li> 332150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</ol> 342150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 352150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<h2>Samples</h2> 362150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<ol> 372150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">{@code 382150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main RemoteService}</a></li> 392150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li><a href="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code 402150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main LocalService}</a></li> 412150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</ol> 422150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 432150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<h2>See also</h2> 442150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<ol> 4550e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main <li><a href="{@docRoot}guide/components/services.html">Services</a></li> 462150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</ol> 472150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</div> 482150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 492150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 502150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>A bound service is the server in a client-server interface. A bound service allows components 512150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main(such as activities) to bind to the service, send requests, receive responses, and even perform 522150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maininterprocess communication (IPC). A bound service typically lives only while it serves another 532150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainapplication component and does not run in the background indefinitely.</p> 542150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 552150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>This document shows you how to create a bound service, including how to bind 562150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainto the service from other application components. However, you should also refer to the <a 5750e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainhref="{@docRoot}guide/components/services.html">Services</a> document for additional 582150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maininformation about services in general, such as how to deliver notifications from a service, set 592150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainthe service to run in the foreground, and more.</p> 602150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 612150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 622150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<h2 id="Basics">The Basics</h2> 632150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 642150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>A bound service is an implementation of the {@link android.app.Service} class that allows 652150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainother applications to bind to it and interact with it. To provide binding for a 662150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainservice, you must implement the {@link android.app.Service#onBind onBind()} callback method. This 672150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainmethod returns an {@link android.os.IBinder} object that defines the programming interface that 682150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainclients can use to interact with the service.</p> 692150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 702150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<div class="sidebox-wrapper"> 712150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<div class="sidebox"> 722150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <h3>Binding to a Started Service</h3> 732150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 7450e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Main<p>As discussed in the <a href="{@docRoot}guide/components/services.html">Services</a> 752150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maindocument, you can create a service that is both started and bound. That is, the service can be 762150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainstarted by calling {@link android.content.Context#startService startService()}, which allows the 772150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainservice to run indefinitely, and also allow a client to bind to the service by calling {@link 782150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.Context#bindService bindService()}. 792150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <p>If you do allow your service to be started and bound, then when the service has been 802150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainstarted, the system does <em>not</em> destroy the service when all clients unbind. Instead, you must 812150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainexplicitly stop the service, by calling {@link android.app.Service#stopSelf stopSelf()} or {@link 822150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.Context#stopService stopService()}.</p> 832150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 842150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>Although you should usually implement either {@link android.app.Service#onBind onBind()} 852150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<em>or</em> {@link android.app.Service#onStartCommand onStartCommand()}, it's sometimes necessary to 862150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainimplement both. For example, a music player might find it useful to allow its service to run 872150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainindefinitely and also provide binding. This way, an activity can start the service to play some 882150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainmusic and the music continues to play even if the user leaves the application. Then, when the user 892150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainreturns to the application, the activity can bind to the service to regain control of playback.</p> 902150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 912150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>Be sure to read the section about <a href="#Lifecycle">Managing the Lifecycle of a Bound 922150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainService</a>, for more information about the service lifecycle when adding binding to a 932150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainstarted service.</p> 942150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</div> 952150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</div> 962150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 972150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>A client can bind to the service by calling {@link android.content.Context#bindService 982150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainbindService()}. When it does, it must provide an implementation of {@link 992150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.ServiceConnection}, which monitors the connection with the service. The {@link 1002150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.Context#bindService bindService()} method returns immediately without a value, but 1012150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainwhen the Android system creates the connection between the 1022150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainclient and service, it calls {@link 1032150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.ServiceConnection#onServiceConnected onServiceConnected()} on the {@link 1042150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.ServiceConnection}, to deliver the {@link android.os.IBinder} that 1052150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainthe client can use to communicate with the service.</p> 1062150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1072150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>Multiple clients can connect to the service at once. However, the system calls your service's 1082150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main{@link android.app.Service#onBind onBind()} method to retrieve the {@link android.os.IBinder} only 1092150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainwhen the first client binds. The system then delivers the same {@link android.os.IBinder} to any 1102150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainadditional clients that bind, without calling {@link android.app.Service#onBind onBind()} again.</p> 1112150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1122150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>When the last client unbinds from the service, the system destroys the service (unless the 1132150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainservice was also started by {@link android.content.Context#startService startService()}).</p> 1142150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1152150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>When you implement your bound service, the most important part is defining the interface 1162150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainthat your {@link android.app.Service#onBind onBind()} callback method returns. There are a few 1172150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maindifferent ways you can define your service's {@link android.os.IBinder} interface and the following 1182150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainsection discusses each technique.</p> 1192150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1202150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1212150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1222150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<h2 id="Creating">Creating a Bound Service</h2> 1232150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1242150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>When creating a service that provides binding, you must provide an {@link android.os.IBinder} 1252150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainthat provides the programming interface that clients can use to interact with the service. There 1262150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainare three ways you can define the interface:</p> 1272150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1282150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<dl> 1292150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <dt><a href="#Binder">Extending the Binder class</a></dt> 1302150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <dd>If your service is private to your own application and runs in the same process as the client 1312150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main(which is common), you should create your interface by extending the {@link android.os.Binder} class 1322150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainand returning an instance of it from 1332150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main{@link android.app.Service#onBind onBind()}. The client receives the {@link android.os.Binder} and 1342150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maincan use it to directly access public methods available in either the {@link android.os.Binder} 1352150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainimplementation or even the {@link android.app.Service}. 1362150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <p>This is the preferred technique when your service is merely a background worker for your own 1372150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainapplication. The only reason you would not create your interface this way is because 1382150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainyour service is used by other applications or across separate processes.</dd> 1392150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1402150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <dt><a href="#Messenger">Using a Messenger</a></dt> 1412150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <dd>If you need your interface to work across different processes, you can create 1422150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainan interface for the service with a {@link android.os.Messenger}. In this manner, the service 1432150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maindefines a {@link android.os.Handler} that responds to different types of {@link 1442150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.os.Message} objects. This {@link android.os.Handler} 1452150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainis the basis for a {@link android.os.Messenger} that can then share an {@link android.os.IBinder} 1462150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainwith the client, allowing the client to send commands to the service using {@link 1472150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.os.Message} objects. Additionally, the client can define a {@link android.os.Messenger} of 1482150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainits own so the service can send messages back. 1492150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <p>This is the simplest way to perform interprocess communication (IPC), because the {@link 1502150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.os.Messenger} queues all requests into a single thread so that you don't have to design 1512150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainyour service to be thread-safe.</p> 1522150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main </dd> 1532150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1542150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <dt>Using AIDL</dt> 1552150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <dd>AIDL (Android Interface Definition Language) performs all the work to decompose objects into 1562150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainprimitives that the operating system can understand and marshall them across processes to perform 1572150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainIPC. The previous technique, using a {@link android.os.Messenger}, is actually based on AIDL as 1582150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainits underlying structure. As mentioned above, the {@link android.os.Messenger} creates a queue of 1592150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainall the client requests in a single thread, so the service receives requests one at a time. If, 1602150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainhowever, you want your service to handle multiple requests simultaneously, then you can use AIDL 1612150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maindirectly. In this case, your service must be capable of multi-threading and be built thread-safe. 1622150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <p>To use AIDL directly, you must 1632150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maincreate an {@code .aidl} file that defines the programming interface. The Android SDK tools use 1642150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainthis file to generate an abstract class that implements the interface and handles IPC, which you 1652150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maincan then extend within your service.</p> 1662150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main </dd> 1672150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</dl> 1682150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1692150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <p class="note"><strong>Note:</strong> Most applications <strong>should not</strong> use AIDL to 1702150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maincreate a bound service, because it may require multithreading capabilities and 1712150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maincan result in a more complicated implementation. As such, AIDL is not suitable for most applications 1722150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainand this document does not discuss how to use it for your service. If you're certain that you need 173e40c4636d970c50f7719e7d5067963be93c25750Scott Mainto use AIDL directly, see the <a href="{@docRoot}guide/components/aidl.html">AIDL</a> 1742150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maindocument.</p> 1752150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1762150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1772150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1782150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1792150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<h3 id="Binder">Extending the Binder class</h3> 1802150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1812150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>If your service is used only by the local application and does not need to work across processes, 1822150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainthen you can implement your own {@link android.os.Binder} class that provides your client direct 1832150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainaccess to public methods in the service.</p> 1842150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1852150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p class="note"><strong>Note:</strong> This works only if the client and service are in the same 1862150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainapplication and process, which is most common. For example, this would work well for a music 1872150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainapplication that needs to bind an activity to its own service that's playing music in the 1882150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainbackground.</p> 1892150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 1902150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>Here's how to set it up:</p> 1912150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<ol> 1922150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>In your service, create an instance of {@link android.os.Binder} that either: 1932150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <ul> 1942150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>contains public methods that the client can call</li> 1952150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>returns the current {@link android.app.Service} instance, which has public methods the 1962150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainclient can call</li> 1972150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>or, returns an instance of another class hosted by the service with public methods the 1982150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainclient can call</li> 1992150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main </ul> 2002150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>Return this instance of {@link android.os.Binder} from the {@link 2012150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.app.Service#onBind onBind()} callback method.</li> 2022150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>In the client, receive the {@link android.os.Binder} from the {@link 2032150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.ServiceConnection#onServiceConnected onServiceConnected()} callback method and 2042150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainmake calls to the bound service using the methods provided.</li> 2052150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</ol> 2062150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2072150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p class="note"><strong>Note:</strong> The reason the service and client must be in the same 2082150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainapplication is so the client can cast the returned object and properly call its APIs. The service 2092150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainand client must also be in the same process, because this technique does not perform any 2102150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainmarshalling across processes.</p> 2112150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2122150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>For example, here's a service that provides clients access to methods in the service through 2132150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maina {@link android.os.Binder} implementation:</p> 2142150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2152150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<pre> 2162150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainpublic class LocalService extends Service { 2172150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // Binder given to clients 2182150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main private final IBinder mBinder = new LocalBinder(); 2192150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // Random number generator 2202150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main private final Random mGenerator = new Random(); 2212150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2222150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main /** 2232150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main * Class used for the client Binder. Because we know this service always 2242150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main * runs in the same process as its clients, we don't need to deal with IPC. 2252150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main */ 2262150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main public class LocalBinder extends Binder { 2272150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main LocalService getService() { 2282150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // Return this instance of LocalService so clients can call public methods 2292150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main return LocalService.this; 2302150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 2312150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 2322150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2332150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main @Override 2342150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main public IBinder onBind(Intent intent) { 2352150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main return mBinder; 2362150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 2372150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2382150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main /** method for clients */ 2392150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main public int getRandomNumber() { 2402150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main return mGenerator.nextInt(100); 2412150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 2422150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main} 2432150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</pre> 2442150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2452150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>The {@code LocalBinder} provides the {@code getService()} method for clients to retrieve the 2462150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maincurrent instance of {@code LocalService}. This allows clients to call public methods in the 2472150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainservice. For example, clients can call {@code getRandomNumber()} from the service.</p> 2482150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2492150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>Here's an activity that binds to {@code LocalService} and calls {@code getRandomNumber()} 2502150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainwhen a button is clicked:</p> 2512150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2522150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<pre> 2532150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainpublic class BindingActivity extends Activity { 2542150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main LocalService mService; 2552150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main boolean mBound = false; 2562150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2572150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main @Override 2582150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main protected void onCreate(Bundle savedInstanceState) { 2592150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main super.onCreate(savedInstanceState); 2602150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main setContentView(R.layout.main); 2612150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 2622150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2632150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main @Override 2642150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main protected void onStart() { 2652150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main super.onStart(); 2662150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // Bind to LocalService 2672150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main Intent intent = new Intent(this, LocalService.class); 2682150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main bindService(intent, mConnection, Context.BIND_AUTO_CREATE); 2692150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 2702150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2712150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main @Override 2722150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main protected void onStop() { 2732150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main super.onStop(); 2742150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // Unbind from the service 2752150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main if (mBound) { 2762150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main unbindService(mConnection); 2772150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main mBound = false; 2782150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 2792150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 2802150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2812150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main /** Called when a button is clicked (the button in the layout file attaches to 2822150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main * this method with the android:onClick attribute) */ 2832150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main public void onButtonClick(View v) { 2842150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main if (mBound) { 2852150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // Call a method from the LocalService. 2862150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // However, if this call were something that might hang, then this request should 2872150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // occur in a separate thread to avoid slowing down the activity performance. 2882150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main int num = mService.getRandomNumber(); 2892150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main Toast.makeText(this, "number: " + num, Toast.LENGTH_SHORT).show(); 2902150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 2912150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 2922150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2932150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main /** Defines callbacks for service binding, passed to bindService() */ 2942150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main private ServiceConnection mConnection = new ServiceConnection() { 2952150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 2962150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main @Override 2972150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main public void onServiceConnected(ComponentName className, 2982150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main IBinder service) { 2992150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // We've bound to LocalService, cast the IBinder and get LocalService instance 3002150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main LocalBinder binder = (LocalBinder) service; 3012150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main mService = binder.getService(); 3022150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main mBound = true; 3032150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 3042150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3052150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main @Override 3062150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main public void onServiceDisconnected(ComponentName arg0) { 3072150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main mBound = false; 3082150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 3092150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main }; 3102150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main} 3112150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</pre> 3122150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3132150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>The above sample shows how the client binds to the service using an implementation of 3142150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main{@link android.content.ServiceConnection} and the {@link 3152150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.ServiceConnection#onServiceConnected onServiceConnected()} callback. The next 3162150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainsection provides more information about this process of binding to the service.</p> 3172150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3182150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p class="note"><strong>Note:</strong> The example above doesn't explicitly unbind from the service, 3192150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainbut all clients should unbind at an appropriate time (such as when the activity pauses).</p> 3202150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3212150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>For more sample code, see the <a 3222150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainhref="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalService.html">{@code 3232150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainLocalService.java}</a> class and the <a 3242150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainhref="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/LocalServiceActivities.html">{@code 3252150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainLocalServiceActivities.java}</a> class in <a 3262150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainhref="{@docRoot}resources/samples/ApiDemos/index.html">ApiDemos</a>.</p> 3272150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3282150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3292150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3302150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3312150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3322150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<h3 id="Messenger">Using a Messenger</h3> 3332150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3342150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<div class="sidebox-wrapper"> 3352150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<div class="sidebox"> 3362150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <h4>Compared to AIDL</h4> 3372150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <p>When you need to perform IPC, using a {@link android.os.Messenger} for your interface is 3382150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainsimpler than implementing it with AIDL, because {@link android.os.Messenger} queues 3392150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainall calls to the service, whereas, a pure AIDL interface sends simultaneous requests to the 3402150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainservice, which must then handle multi-threading.</p> 3412150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <p>For most applications, the service doesn't need to perform multi-threading, so using a {@link 3422150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.os.Messenger} allows the service to handle one call at a time. If it's important 3432150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainthat your service be multi-threaded, then you should use <a 344e40c4636d970c50f7719e7d5067963be93c25750Scott Mainhref="{@docRoot}guide/components/aidl.html">AIDL</a> to define your interface.</p> 3452150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</div> 3462150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</div> 3472150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3482150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>If you need your service to communicate with remote processes, then you can use a 3492150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main{@link android.os.Messenger} to provide the interface for your service. This technique allows 3502150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainyou to perform interprocess communication (IPC) without the need to use AIDL.</p> 3512150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3522150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>Here's a summary of how to use a {@link android.os.Messenger}:</p> 3532150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3542150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<ul> 3552150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>The service implements a {@link android.os.Handler} that receives a callback for each 3562150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maincall from a client.</li> 3572150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>The {@link android.os.Handler} is used to create a {@link android.os.Messenger} object 3582150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main(which is a reference to the {@link android.os.Handler}).</li> 3592150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>The {@link android.os.Messenger} creates an {@link android.os.IBinder} that the service 3602150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainreturns to clients from {@link android.app.Service#onBind onBind()}.</li> 3612150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>Clients use the {@link android.os.IBinder} to instantiate the {@link android.os.Messenger} 3622150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main(that references the service's {@link android.os.Handler}), which the client uses to send 3632150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main{@link android.os.Message} objects to the service.</li> 3642150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>The service receives each {@link android.os.Message} in its {@link 3652150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.os.Handler}—specifically, in the {@link android.os.Handler#handleMessage 3662150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainhandleMessage()} method.</li> 3672150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</ul> 3682150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3692150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3702150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>In this way, there are no "methods" for the client to call on the service. Instead, the 3712150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainclient delivers "messages" ({@link android.os.Message} objects) that the service receives in 3722150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainits {@link android.os.Handler}.</p> 3732150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3742150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>Here's a simple example service that uses a {@link android.os.Messenger} interface:</p> 3752150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3762150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<pre> 3772150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainpublic class MessengerService extends Service { 3782150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main /** Command to the service to display a message */ 3792150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main static final int MSG_SAY_HELLO = 1; 3802150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3812150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main /** 3822150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main * Handler of incoming messages from clients. 3832150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main */ 3842150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main class IncomingHandler extends Handler { 3852150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main @Override 3862150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main public void handleMessage(Message msg) { 3872150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main switch (msg.what) { 3882150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main case MSG_SAY_HELLO: 3892150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main Toast.makeText(getApplicationContext(), "hello!", Toast.LENGTH_SHORT).show(); 3902150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main break; 3912150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main default: 3922150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main super.handleMessage(msg); 3932150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 3942150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 3952150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 3962150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 3972150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main /** 3982150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main * Target we publish for clients to send messages to IncomingHandler. 3992150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main */ 4002150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main final Messenger mMessenger = new Messenger(new IncomingHandler()); 4012150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 4022150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main /** 4032150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main * When binding to the service, we return an interface to our messenger 4042150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main * for sending messages to the service. 4052150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main */ 4062150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main @Override 4072150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main public IBinder onBind(Intent intent) { 4082150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main Toast.makeText(getApplicationContext(), "binding", Toast.LENGTH_SHORT).show(); 4092150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main return mMessenger.getBinder(); 4102150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 4112150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main} 4122150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</pre> 4132150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 4142150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>Notice that the {@link android.os.Handler#handleMessage handleMessage()} method in the 4152150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main{@link android.os.Handler} is where the service receives the incoming {@link android.os.Message} 4162150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainand decides what to do, based on the {@link android.os.Message#what} member.</p> 4172150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 4182150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>All that a client needs to do is create a {@link android.os.Messenger} based on the {@link 4192150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.os.IBinder} returned by the service and send a message using {@link 4202150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.os.Messenger#send send()}. For example, here's a simple activity that binds to the 4212150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainservice and delivers the {@code MSG_SAY_HELLO} message to the service:</p> 4222150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 4232150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<pre> 4242150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainpublic class ActivityMessenger extends Activity { 4252150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main /** Messenger for communicating with the service. */ 4262150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main Messenger mService = null; 4272150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 4282150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main /** Flag indicating whether we have called bind on the service. */ 4292150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main boolean mBound; 4302150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 4312150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main /** 4322150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main * Class for interacting with the main interface of the service. 4332150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main */ 4342150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main private ServiceConnection mConnection = new ServiceConnection() { 4352150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main public void onServiceConnected(ComponentName className, IBinder service) { 4362150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // This is called when the connection with the service has been 4372150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // established, giving us the object we can use to 4382150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // interact with the service. We are communicating with the 4392150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // service using a Messenger, so here we get a client-side 4402150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // representation of that from the raw IBinder object. 4412150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main mService = new Messenger(service); 4422150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main mBound = true; 4432150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 4442150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 4452150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main public void onServiceDisconnected(ComponentName className) { 4462150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // This is called when the connection with the service has been 4472150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // unexpectedly disconnected -- that is, its process crashed. 4482150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main mService = null; 4492150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main mBound = false; 4502150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 4512150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main }; 4522150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 4532150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main public void sayHello(View v) { 4542150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main if (!mBound) return; 4552150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // Create and send a message to the service, using a supported 'what' value 4562150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main Message msg = Message.obtain(null, MessengerService.MSG_SAY_HELLO, 0, 0); 4572150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main try { 4582150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main mService.send(msg); 4592150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } catch (RemoteException e) { 4602150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main e.printStackTrace(); 4612150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 4622150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 4632150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 4642150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main @Override 4652150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main protected void onCreate(Bundle savedInstanceState) { 4662150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main super.onCreate(savedInstanceState); 4672150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main setContentView(R.layout.main); 4682150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 4692150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 4702150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main @Override 4712150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main protected void onStart() { 4722150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main super.onStart(); 4732150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // Bind to the service 4742150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main bindService(new Intent(this, MessengerService.class), mConnection, 4752150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main Context.BIND_AUTO_CREATE); 4762150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 4772150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 4782150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main @Override 4792150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main protected void onStop() { 4802150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main super.onStop(); 4812150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // Unbind from the service 4822150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main if (mBound) { 4832150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main unbindService(mConnection); 4842150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main mBound = false; 4852150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 4862150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 4872150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main} 4882150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</pre> 4892150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 4902150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>Notice that this example does not show how the service can respond to the client. If you want the 4912150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainservice to respond, then you need to also create a {@link android.os.Messenger} in the client. Then 4922150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainwhen the client receives the {@link android.content.ServiceConnection#onServiceConnected 4932150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainonServiceConnected()} callback, it sends a {@link android.os.Message} to the service that includes 4942150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainthe client's {@link android.os.Messenger} in the {@link android.os.Message#replyTo} parameter 4952150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainof the {@link android.os.Messenger#send send()} method.</p> 4962150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 4972150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>You can see an example of how to provide two-way messaging in the <a 4982150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainhref="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/MessengerService.html">{@code 4992150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainMessengerService.java}</a> (service) and <a 5002150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainhref="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/MessengerServiceActivities.html">{@code 5012150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainMessengerServiceActivities.java}</a> (client) samples.</p> 5022150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5032150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5042150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5052150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5062150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5072150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<h2 id="Binding">Binding to a Service</h2> 5082150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5092150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>Application components (clients) can bind to a service by calling 5102150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main{@link android.content.Context#bindService bindService()}. The Android 5112150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainsystem then calls the service's {@link android.app.Service#onBind 5122150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainonBind()} method, which returns an {@link android.os.IBinder} for interacting with the service.</p> 5132150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5142150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>The binding is asynchronous. {@link android.content.Context#bindService 5152150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainbindService()} returns immediately and does <em>not</em> return the {@link android.os.IBinder} to 5162150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainthe client. To receive the {@link android.os.IBinder}, the client must create an instance of {@link 5172150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.ServiceConnection} and pass it to {@link android.content.Context#bindService 5182150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainbindService()}. The {@link android.content.ServiceConnection} includes a callback method that the 5192150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainsystem calls to deliver the {@link android.os.IBinder}.</p> 5202150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5212150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p class="note"><strong>Note:</strong> Only activities, services, and content providers can bind 5222150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainto a service—you <strong>cannot</strong> bind to a service from a broadcast receiver.</p> 5232150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5242150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>So, to bind to a service from your client, you must: </p> 5252150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<ol> 5262150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>Implement {@link android.content.ServiceConnection}. 5272150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <p>Your implementation must override two callback methods:</p> 5282150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <dl> 5292150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <dt>{@link android.content.ServiceConnection#onServiceConnected onServiceConnected()}</dt> 5302150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <dd>The system calls this to deliver the {@link android.os.IBinder} returned by 5312150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainthe service's {@link android.app.Service#onBind onBind()} method.</dd> 5322150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <dt>{@link android.content.ServiceConnection#onServiceDisconnected 5332150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainonServiceDisconnected()}</dt> 5342150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <dd>The Android system calls this when the connection to the service is unexpectedly 5352150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainlost, such as when the service has crashed or has been killed. This is <em>not</em> called when the 5362150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainclient unbinds.</dd> 5372150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main </dl> 5382150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main </li> 5392150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>Call {@link 5402150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.Context#bindService bindService()}, passing the {@link 5412150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.ServiceConnection} implementation. </li> 5422150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>When the system calls your {@link android.content.ServiceConnection#onServiceConnected 5432150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainonServiceConnected()} callback method, you can begin making calls to the service, using 5442150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainthe methods defined by the interface.</li> 5452150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>To disconnect from the service, call {@link 5462150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.Context#unbindService unbindService()}. 5472150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <p>When your client is destroyed, it will unbind from the service, but you should always unbind 5482150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainwhen you're done interacting with the service or when your activity pauses so that the service can 5492150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainshutdown while its not being used. (Appropriate times to bind and unbind is discussed 5502150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainmore below.)</p> 5512150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main </li> 5522150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</ol> 5532150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5542150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>For example, the following snippet connects the client to the service created above by 5552150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<a href="#Binder">extending the Binder class</a>, so all it must do is cast the returned 5562150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main{@link android.os.IBinder} to the {@code LocalService} class and request the {@code 5572150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainLocalService} instance:</p> 5582150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5592150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<pre> 5602150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainLocalService mService; 5612150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainprivate ServiceConnection mConnection = new ServiceConnection() { 5622150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // Called when the connection with the service is established 5632150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main public void onServiceConnected(ComponentName className, IBinder service) { 5642150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // Because we have bound to an explicit 5652150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // service that is running in our own process, we can 5662150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // cast its IBinder to a concrete class and directly access it. 5672150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main LocalBinder binder = (LocalBinder) service; 5682150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main mService = binder.getService(); 5692150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main mBound = true; 5702150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 5712150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5722150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main // Called when the connection with the service disconnects unexpectedly 5732150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main public void onServiceDisconnected(ComponentName className) { 5742150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main Log.e(TAG, "onServiceDisconnected"); 5752150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main mBound = false; 5762150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main } 5772150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main}; 5782150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</pre> 5792150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5802150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>With this {@link android.content.ServiceConnection}, the client can bind to a service by passing 5812150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainthis it to {@link android.content.Context#bindService bindService()}. For example:</p> 5822150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5832150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<pre> 5842150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainIntent intent = new Intent(this, LocalService.class); 5852150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainbindService(intent, mConnection, Context.BIND_AUTO_CREATE); 5862150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</pre> 5872150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5882150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<ul> 5892150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>The first parameter of {@link android.content.Context#bindService bindService()} is an 5902150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main{@link android.content.Intent} that explicitly names the service to bind (thought the intent 5912150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maincould be implicit).</li> 5922150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<li>The second parameter is the {@link android.content.ServiceConnection} object.</li> 5932150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<li>The third parameter is a flag indicating options for the binding. It should usually be {@link 5942150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.Context#BIND_AUTO_CREATE} in order to create the service if its not already alive. 5952150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainOther possible values are {@link android.content.Context#BIND_DEBUG_UNBIND} 5962150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainand {@link android.content.Context#BIND_NOT_FOREGROUND}, or {@code 0} for none.</li> 5972150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</ul> 5982150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 5992150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6002150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<h3>Additional notes</h3> 6012150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6022150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>Here are some important notes about binding to a service:</p> 6032150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<ul> 6042150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>You should always trap {@link android.os.DeadObjectException} exceptions, which are thrown 6052150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainwhen the connection has broken. This is the only exception thrown by remote methods.</li> 6062150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>Objects are reference counted across processes. </li> 6072150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>You should usually pair the binding and unbinding during 6082150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainmatching bring-up and tear-down moments of the client's lifecycle. For example: 6092150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <ul> 6102150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>If you only need to interact with the service while your activity is visible, you 6112150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainshould bind during {@link android.app.Activity#onStart onStart()} and unbind during {@link 6122150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.app.Activity#onStop onStop()}.</li> 6132150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <li>If you want your activity to receive responses even while it is stopped in the 6142150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainbackground, then you can bind during {@link android.app.Activity#onCreate onCreate()} and unbind 6152150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainduring {@link android.app.Activity#onDestroy onDestroy()}. Beware that this implies that your 6162150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainactivity needs to use the service the entire time it's running (even in the background), so if 6172150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainthe service is in another process, then you increase the weight of the process and it becomes 6182150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainmore likely that the system will kill it.</li> 6192150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main </ul> 6202150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main <p class="note"><strong>Note:</strong> You should usually <strong>not</strong> bind and unbind 6212150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainduring your activity's {@link android.app.Activity#onResume onResume()} and {@link 6222150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.app.Activity#onPause onPause()}, because these callbacks occur at every lifecycle transition 6232150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainand you should keep the processing that occurs at these transitions to a minimum. Also, if 6242150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainmultiple activities in your application bind to the same service and there is a transition between 6252150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maintwo of those activities, the service may be destroyed and recreated as the current activity unbinds 6262150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main(during pause) before the next one binds (during resume). (This activity transition for how 6272150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainactivities coordinate their lifecycles is described in the <a 62850e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainhref="{@docRoot}guide/components/activities.html#CoordinatingActivities">Activities</a> 6292150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Maindocument.)</p> 6302150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</ul> 6312150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6322150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>For more sample code, showing how to bind to a service, see the <a 6332150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainhref="{@docRoot}resources/samples/ApiDemos/src/com/example/android/apis/app/RemoteService.html">{@code 6342150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainRemoteService.java}</a> class in <a 6352150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainhref="{@docRoot}resources/samples/ApiDemos/index.html">ApiDemos</a>.</p> 6362150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6372150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6382150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6392150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6402150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6412150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<h2 id="Lifecycle">Managing the Lifecycle of a Bound Service</h2> 6422150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6432150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<div class="figure" style="width:588px"> 6442150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<img src="{@docRoot}images/fundamentals/service_binding_tree_lifecycle.png" alt="" /> 6452150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p class="img-caption"><strong>Figure 1.</strong> The lifecycle for a service that is started 6462150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainand also allows binding.</p> 6472150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main</div> 6482150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6492150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>When a service is unbound from all clients, the Android system destroys it (unless it was also 6502150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainstarted with {@link android.app.Service#onStartCommand onStartCommand()}). As such, you don't have 6512150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainto manage the lifecycle of your service if it's purely a bound 6522150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainservice—the Android system manages it for you based on whether it is bound to any clients.</p> 6532150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6542150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>However, if you choose to implement the {@link android.app.Service#onStartCommand 6552150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainonStartCommand()} callback method, then you must explicitly stop the service, because the 6562150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainservice is now considered to be <em>started</em>. In this case, the service runs until the service 6572150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainstops itself with {@link android.app.Service#stopSelf()} or another component calls {@link 6582150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.content.Context#stopService stopService()}, regardless of whether it is bound to any 6592150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainclients.</p> 6602150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6612150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>Additionally, if your service is started and accepts binding, then when the system calls 6622150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainyour {@link android.app.Service#onUnbind onUnbind()} method, you can optionally return 6632150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main{@code true} if you would like to receive a call to {@link android.app.Service#onRebind 6642150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainonRebind()} the next time a client binds to the service (instead of receiving a call to {@link 6652150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Mainandroid.app.Service#onBind onBind()}). {@link android.app.Service#onRebind 6662150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainonRebind()} returns void, but the client still receives the {@link android.os.IBinder} in its 6672150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main{@link android.content.ServiceConnection#onServiceConnected onServiceConnected()} callback. 6682150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott MainBelow, figure 1 illustrates the logic for this kind of lifecycle.</p> 6692150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6702150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main<p>For more information about the lifecycle of an started service, see the <a 67150e990c64fa23ce94efa76b9e72df7f8ec3cee6aScott Mainhref="{@docRoot}guide/components/services.html#Lifecycle">Services</a> document.</p> 6722150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6732150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6742150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 6752150553dc374204a1cb3033ed3fa65c2f22dd5e7Scott Main 676