Lines Matching full:service
11 <li>A bound service allows other components to bind to it, in order to interact with it and
13 <li>A bound service is destroyed once all clients unbind, unless the service was also started</li>
18 <li><a href="#Creating">Creating a Bound Service</a>
24 <li><a href="#Binding">Binding to a Service</a></li>
25 <li><a href="#Lifecycle">Managing the Lifecycle of a Bound Service</a></li>
30 <li>{@link android.app.Service}</li>
50 <p>A bound service is the server in a client-server interface. A bound service allows components
51 (such as activities) to bind to the service, send requests, receive responses, and even perform
52 interprocess communication (IPC). A bound service typically lives only while it serves another
55 <p>This document shows you how to create a bound service, including how to bind
56 to the service from other application components. However, you should also refer to the <a
58 information about services in general, such as how to deliver notifications from a service, set
59 the service to run in the foreground, and more.</p>
64 <p>A bound service is an implementation of the {@link android.app.Service} class that allows
66 service, you must implement the {@link android.app.Service#onBind onBind()} callback method. This
68 clients can use to interact with the service.</p>
72 <h3>Binding to a Started Service</h3>
75 document, you can create a service that is both started and bound. That is, the service can be
77 service to run indefinitely, and also allow a client to bind to the service by calling {@link
79 <p>If you do allow your service to be started and bound, then when the service has been
80 started, the system does <em>not</em> destroy the service when all clients unbind. Instead, you must
81 explicitly stop the service, by calling {@link android.app.Service#stopSelf stopSelf()} or {@link
84 <p>Although you should usually implement either {@link android.app.Service#onBind onBind()}
85 <em>or</em> {@link android.app.Service#onStartCommand onStartCommand()}, it's sometimes necessary to
86 implement both. For example, a music player might find it useful to allow its service to run
87 indefinitely and also provide binding. This way, an activity can start the service to play some
89 returns to the application, the activity can bind to the service to regain control of playback.</p>
92 Service</a>, for more information about the service lifecycle when adding binding to a
93 started service.</p>
97 <p>A client can bind to the service by calling {@link android.content.Context#bindService
99 android.content.ServiceConnection}, which monitors the connection with the service. The {@link
102 client and service, it calls {@link
105 the client can use to communicate with the service.</p>
107 <p>Multiple clients can connect to the service at once. However, the system calls your service's
108 {@link android.app.Service#onBind onBind()} method to retrieve the {@link android.os.IBinder} only
110 additional clients that bind, without calling {@link android.app.Service#onBind onBind()} again.</p>
112 <p>When the last client unbinds from the service, the system destroys the service (unless the
113 service was also started by {@link android.content.Context#startService startService()}).</p>
115 <p>When you implement your bound service, the most important part is defining the interface
116 that your {@link android.app.Service#onBind onBind()} callback method returns. There are a few
117 different ways you can define your service's {@link android.os.IBinder} interface and the following
122 <h2 id="Creating">Creating a Bound Service</h2>
124 <p>When creating a service that provides binding, you must provide an {@link android.os.IBinder}
125 that provides the programming interface that clients can use to interact with the service. There
130 <dd>If your service is private to your own application and runs in the same process as the client
133 {@link android.app.Service#onBind onBind()}. The client receives the {@link android.os.Binder} and
135 implementation or even the {@link android.app.Service}.
136 <p>This is the preferred technique when your service is merely a background worker for your own
138 your service is used by other applications or across separate processes.</dd>
142 an interface for the service with a {@link android.os.Messenger}. In this manner, the service
146 with the client, allowing the client to send commands to the service using {@link
148 its own so the service can send messages back.
151 your service to be thread-safe.</p>
159 all the client requests in a single thread, so the service receives requests one at a time. If,
160 however, you want your service to handle multiple requests simultaneously, then you can use AIDL
161 directly. In this case, your service must be capable of multi-threading and be built thread-safe.
165 can then extend within your service.</p>
170 create a bound service, because it may require multithreading capabilities and
172 and this document does not discuss how to use it for your service. If you're certain that you need
181 <p>If your service is used only by the local application and does not need to work across processes,
183 access to public methods in the service.</p>
185 <p class="note"><strong>Note:</strong> This works only if the client and service are in the same
187 application that needs to bind an activity to its own service that's playing music in the
192 <li>In your service, create an instance of {@link android.os.Binder} that either:
195 <li>returns the current {@link android.app.Service} instance, which has public methods the
197 <li>or, returns an instance of another class hosted by the service with public methods the
201 android.app.Service#onBind onBind()} callback method.</li>
204 make calls to the bound service using the methods provided.</li>
207 <p class="note"><strong>Note:</strong> The reason the service and client must be in the same
208 application is so the client can cast the returned object and properly call its APIs. The service
212 <p>For example, here's a service that provides clients access to methods in the service through
216 public class LocalService extends Service {
223 * Class used for the client Binder. Because we know this service always
247 service. For example, clients can call {@code getRandomNumber()} from the service.</p>
274 // Unbind from the service
293 /** Defines callbacks for service binding, passed to bindService() */
298 IBinder service) {
300 LocalBinder binder = (LocalBinder) service;
313 <p>The above sample shows how the client binds to the service using an implementation of
316 section provides more information about this process of binding to the service.</p>
318 <p class="note"><strong>Note:</strong> The example above doesn't explicitly unbind from the service,
339 all calls to the service, whereas, a pure AIDL interface sends simultaneous requests to the
340 service, which must then handle multi-threading.</p>
341 <p>For most applications, the service doesn't need to perform multi-threading, so using a {@link
342 android.os.Messenger} allows the service to handle one call at a time. If it's important
343 that your service be multi-threaded, then you should use <a
348 <p>If you need your service to communicate with remote processes, then you can use a
349 {@link android.os.Messenger} to provide the interface for your service. This technique allows
355 <li>The service implements a {@link android.os.Handler} that receives a callback for each
359 <li>The {@link android.os.Messenger} creates an {@link android.os.IBinder} that the service
360 returns to clients from {@link android.app.Service#onBind onBind()}.</li>
362 (that references the service's {@link android.os.Handler}), which the client uses to send
363 {@link android.os.Message} objects to the service.</li>
364 <li>The service receives each {@link android.os.Message} in its {@link
370 <p>In this way, there are no "methods" for the client to call on the service. Instead, the
371 client delivers "messages" ({@link android.os.Message} objects) that the service receives in
374 <p>Here's a simple example service that uses a {@link android.os.Messenger} interface:</p>
377 public class MessengerService extends Service {
378 /** Command to the service to display a message */
403 * When binding to the service, we return an interface to our messenger
404 * for sending messages to the service.
415 {@link android.os.Handler} is where the service receives the incoming {@link android.os.Message}
419 android.os.IBinder} returned by the service and send a message using {@link
421 service and delivers the {@code MSG_SAY_HELLO} message to the service:</p>
425 /** Messenger for communicating with the service. */
428 /** Flag indicating whether we have called bind on the service. */
432 * Class for interacting with the main interface of the service.
435 public void onServiceConnected(ComponentName className, IBinder service) {
436 // This is called when the connection with the service has been
438 // interact with the service. We are communicating with the
439 // service using a Messenger, so here we get a client-side
441 mService = new Messenger(service);
446 // This is called when the connection with the service has been
455 // Create and send a message to the service, using a supported 'what' value
473 // Bind to the service
481 // Unbind from the service
490 <p>Notice that this example does not show how the service can respond to the client. If you want the
491 service to respond, then you need to also create a {@link android.os.Messenger} in the client. Then
493 onServiceConnected()} callback, it sends a {@link android.os.Message} to the service that includes
499 MessengerService.java}</a> (service) and <a
507 <h2 id="Binding">Binding to a Service</h2>
509 <p>Application components (clients) can bind to a service by calling
511 system then calls the service's {@link android.app.Service#onBind
512 onBind()} method, which returns an {@link android.os.IBinder} for interacting with the service.</p>
522 to a service—you <strong>cannot</strong> bind to a service from a broadcast receiver.</p>
524 <p>So, to bind to a service from your client, you must: </p>
531 the service's {@link android.app.Service#onBind onBind()} method.</dd>
534 <dd>The Android system calls this when the connection to the service is unexpectedly
535 lost, such as when the service has crashed or has been killed. This is <em>not</em> called when the
543 onServiceConnected()} callback method, you can begin making calls to the service, using
545 <li>To disconnect from the service, call {@link
547 <p>When your client is destroyed, it will unbind from the service, but you should always unbind
548 when you're done interacting with the service or when your activity pauses so that the service can
554 <p>For example, the following snippet connects the client to the service created above by
562 // Called when the connection with the service is established
563 public void onServiceConnected(ComponentName className, IBinder service) {
565 // service that is running in our own process, we can
567 LocalBinder binder = (LocalBinder) service;
572 // Called when the connection with the service disconnects unexpectedly
580 <p>With this {@link android.content.ServiceConnection}, the client can bind to a service by passing
590 {@link android.content.Intent} that explicitly names the service to bind (thought the intent
594 android.content.Context#BIND_AUTO_CREATE} in order to create the service if its not already alive.
602 <p>Here are some important notes about binding to a service:</p>
610 <li>If you only need to interact with the service while your activity is visible, you
616 activity needs to use the service the entire time it's running (even in the background), so if
617 the service is in another process, then you increase the weight of the process and it becomes
624 multiple activities in your application bind to the same service and there is a transition between
625 two of those activities, the service may be destroyed and recreated as the current activity unbinds
632 <p>For more sample code, showing how to bind to a service, see the <a
641 <h2 id="Lifecycle">Managing the Lifecycle of a Bound Service</h2>
643 <p>When a service is unbound from all clients, the Android system destroys it (unless it was also
644 started with {@link android.app.Service#onStartCommand onStartCommand()}). As such, you don't have
645 to manage the lifecycle of your service if it's purely a bound
646 service—the Android system manages it for you based on whether it is bound to any clients.</p>
648 <p>However, if you choose to implement the {@link android.app.Service#onStartCommand
649 onStartCommand()} callback method, then you must explicitly stop the service, because the
650 service is now considered to be <em>started</em>. In this case, the service runs until the service
651 stops itself with {@link android.app.Service#stopSelf()} or another component calls {@link
655 <p>Additionally, if your service is started and accepts binding, then when the system calls
656 your {@link android.app.Service#onUnbind onUnbind()} method, you can optionally return
657 {@code true} if you would like to receive a call to {@link android.app.Service#onRebind
658 onRebind()} the next time a client binds to the service (instead of receiving a call to {@link
659 android.app.Service#onBind onBind()}). {@link android.app.Service#onRebind
666 <p class="img-caption"><strong>Figure 1.</strong> The lifecycle for a service that is started
670 <p>For more information about the lifecycle of an started service, see the <a
