Lines Matching refs:to
11 <li>A bound service allows other components to bind to it, in order to interact with it and
24 <li><a href="#Binding">Binding to a Service</a></li>
51 (such as activities) to bind to the service, send requests, receive responses, and even perform
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>
65 other applications to bind to it and interact with it. To provide binding for a
68 clients can use to interact with the service.</p>
72 <h3>Binding to a Started Service</h3>
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
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
88 music and the music continues to play even if the user leaves the application. Then, when the user
89 returns to the application, the activity can bind to the service to regain control of playback.</p>
91 <p>Be sure to read the section about <a href="#Lifecycle">Managing the Lifecycle of a Bound
92 Service</a>, for more information about the service lifecycle when adding binding to a
97 <p>A client can bind to the service by calling {@link android.content.Context#bindService
104 android.content.ServiceConnection}, to deliver the {@link android.os.IBinder} that
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
109 when the first client binds. The system then delivers the same {@link android.os.IBinder} to any
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
134 can use it to directly access public methods available in either the {@link android.os.Binder}
141 <dd>If you need your interface to work across different processes, you can create
143 defines a {@link android.os.Handler} that responds to different types of {@link
146 with the client, allowing the client to send commands to the service using {@link
149 <p>This is the simplest way to perform interprocess communication (IPC), because the {@link
150 android.os.Messenger} queues all requests into a single thread so that you don't have to design
151 your service to be thread-safe.</p>
155 <dd>AIDL (Android Interface Definition Language) performs all the work to decompose objects into
156 primitives that the operating system can understand and marshall them across processes to perform
160 however, you want your service to handle multiple requests simultaneously, then you can use AIDL
164 this file to generate an abstract class that implements the interface and handles IPC, which you
169 <p class="note"><strong>Note:</strong> Most applications <strong>should not</strong> use AIDL to
172 and this document does not discuss how to use it for your service. If you're certain that you need
173 to use AIDL directly, see the <a href="{@docRoot}guide/components/aidl.html">AIDL</a>
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>
187 application that needs to bind an activity to its own service that's playing music in the
190 <p>Here's how to set it up:</p>
204 make calls to the bound service using the methods provided.</li>
212 <p>For example, here's a service that provides clients access to methods in the service through
217 // Binder given to clients
224 * runs in the same process as its clients, we don't need to deal with IPC.
245 <p>The {@code LocalBinder} provides the {@code getService()} method for clients to retrieve the
246 current instance of {@code LocalService}. This allows clients to call public methods in the
249 <p>Here's an activity that binds to {@code LocalService} and calls {@code getRandomNumber()}
266 // Bind to LocalService
281 /** Called when a button is clicked (the button in the layout file attaches to
287 // occur in a separate thread to avoid slowing down the activity performance.
293 /** Defines callbacks for service binding, passed to bindService() */
299 // We've bound to LocalService, cast the IBinder and get LocalService instance
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>
336 <h4>Compared to AIDL</h4>
337 <p>When you need to perform IPC, using a {@link android.os.Messenger} for your interface is
339 all calls to the service, whereas, a pure AIDL interface sends simultaneous requests to the
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
344 href="{@docRoot}guide/components/aidl.html">AIDL</a> to define your interface.</p>
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
350 you to perform interprocess communication (IPC) without the need to use AIDL.</p>
352 <p>Here's a summary of how to use a {@link android.os.Messenger}:</p>
357 <li>The {@link android.os.Handler} is used to create a {@link android.os.Messenger} object
358 (which is a reference to the {@link android.os.Handler}).</li>
360 returns to clients from {@link android.app.Service#onBind onBind()}.</li>
361 <li>Clients use the {@link android.os.IBinder} to instantiate the {@link android.os.Messenger}
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>
370 <p>In this way, there are no "methods" for the client to call on the service. Instead, the
378 /** Command to the service to display a message */
398 * Target we publish for clients to send messages to IncomingHandler.
403 * When binding to the service, we return an interface to our messenger
404 * for sending messages to the service.
416 and decides what to do, based on the {@link android.os.Message#what} member.</p>
418 <p>All that a client needs to do is create a {@link android.os.Messenger} based on the {@link
420 android.os.Messenger#send send()}. For example, here's a simple activity that binds to the
421 service and delivers the {@code MSG_SAY_HELLO} message to the service:</p>
437 // established, giving us the object we can use to
455 // Create and send a message to the service, using a supported 'what' value
473 // Bind to 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
497 <p>You can see an example of how to provide two-way messaging in the <a
507 <h2 id="Binding">Binding to a Service</h2>
509 <p>Application components (clients) can bind to a service by calling
515 bindService()} returns immediately and does <em>not</em> return the {@link android.os.IBinder} to
517 android.content.ServiceConnection} and pass it to {@link android.content.Context#bindService
519 system calls to deliver the {@link android.os.IBinder}.</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>
530 <dd>The system calls this to deliver the {@link android.os.IBinder} returned by
534 <dd>The Android system calls this when the connection to the service is unexpectedly
543 onServiceConnected()} callback method, you can begin making calls to the service, using
549 shutdown while its not being used. (Appropriate times to bind and unbind is discussed
554 <p>For example, the following snippet connects the client to the service created above by
556 {@link android.os.IBinder} to the {@code LocalService} class and request the {@code
564 // Because we have bound to an explicit
566 // cast its IBinder to a concrete class and directly access it.
580 <p>With this {@link android.content.ServiceConnection}, the client can bind to a service by passing
581 this it to {@link android.content.Context#bindService bindService()}. For example:</p>
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
613 <li>If you want your activity to receive responses even while it is stopped in the
616 activity needs to use the service the entire time it's running (even in the background), so if
623 and you should keep the processing that occurs at these transitions to a minimum. Also, if
624 multiple activities in your application bind to the same service and there is a transition between
632 <p>For more sample code, showing how to bind to a service, see the <a
651 to manage the lifecycle of your service if it's purely a bound
652 service—the Android system manages it for you based on whether it is bound to any clients.</p>
654 <p>However, if you choose to implement the {@link android.app.Service#onStartCommand
656 service is now considered to be <em>started</em>. In this case, the service runs until the service
658 android.content.Context#stopService stopService()}, regardless of whether it is bound to any
663 {@code true} if you would like to receive a call to {@link android.app.Service#onRebind
664 onRebind()} the next time a client binds to the service (instead of receiving a call to {@link