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