Lines Matching refs:to
18 <li><a href="#Binding">Binding to a Service</a></li>
45 (such as activities) to bind to the service, send requests, receive responses, and even perform
49 <p>This document shows you how to create a bound service, including how to bind
50 to the service from other application components. However, you should also refer to the <a
52 information about services in general, such as how to deliver notifications from a service, set
53 the service to run in the foreground, and more.</p>
59 other applications to bind to it and interact with it. To provide binding for a
62 clients can use to interact with the service.</p>
66 <h3>Binding to a Started Service</h3>
71 service to run indefinitely, and also allow a client to bind to the service by calling {@link
73 <p>If you do allow your service to be started and bound, then when the service has been
79 <em>or</em> {@link android.app.Service#onStartCommand onStartCommand()}, it's sometimes necessary to
80 implement both. For example, a music player might find it useful to allow its service to run
81 indefinitely and also provide binding. This way, an activity can start the service to play some
82 music and the music continues to play even if the user leaves the application. Then, when the user
83 returns to the application, the activity can bind to the service to regain control of playback.</p>
85 <p>Be sure to read the section about <a href="#Lifecycle">Managing the Lifecycle of a Bound
86 Service</a>, for more information about the service lifecycle when adding binding to a
91 <p>A client can bind to the service by calling {@link android.content.Context#bindService
98 android.content.ServiceConnection}, to deliver the {@link android.os.IBinder} that
99 the client can use to communicate with the service.</p>
101 <p>Multiple clients can connect to the service at once. However, the system calls your service's
102 {@link android.app.Service#onBind onBind()} method to retrieve the {@link android.os.IBinder} only
103 when the first client binds. The system then delivers the same {@link android.os.IBinder} to any
119 that provides the programming interface that clients can use to interact with the service. There
124 <dd>If your service is private to your own application and runs in the same process as the client
128 can use it to directly access public methods available in either the {@link android.os.Binder}
135 <dd>If you need your interface to work across different processes, you can create
137 defines a {@link android.os.Handler} that responds to different types of {@link
140 with the client, allowing the client to send commands to the service using {@link
143 <p>This is the simplest way to perform interprocess communication (IPC), because the {@link
144 android.os.Messenger} queues all requests into a single thread so that you don't have to design
145 your service to be thread-safe.</p>
149 <dd>AIDL (Android Interface Definition Language) performs all the work to decompose objects into
150 primitives that the operating system can understand and marshall them across processes to perform
154 however, you want your service to handle multiple requests simultaneously, then you can use AIDL
158 this file to generate an abstract class that implements the interface and handles IPC, which you
163 <p class="note"><strong>Note:</strong> Most applications <strong>should not</strong> use AIDL to
166 and this document does not discuss how to use it for your service. If you're certain that you need
167 to use AIDL directly, see the <a href="{@docRoot}guide/components/aidl.html">AIDL</a>
175 <p>If your service is used only by the local application and does not need to work across processes,
177 access to public methods in the service.</p>
181 application that needs to bind an activity to its own service that's playing music in the
184 <p>Here's how to set it up:</p>
198 make calls to the bound service using the methods provided.</li>
206 <p>For example, here's a service that provides clients access to methods in the service through
211 // Binder given to clients
218 * runs in the same process as its clients, we don't need to deal with IPC.
239 <p>The {@code LocalBinder} provides the {@code getService()} method for clients to retrieve the
240 current instance of {@code LocalService}. This allows clients to call public methods in the
243 <p>Here's an activity that binds to {@code LocalService} and calls {@code getRandomNumber()}
260 // Bind to LocalService
275 /** Called when a button is clicked (the button in the layout file attaches to
281 // occur in a separate thread to avoid slowing down the activity performance.
287 /** Defines callbacks for service binding, passed to bindService() */
293 // We've bound to LocalService, cast the IBinder and get LocalService instance
307 <p>The above sample shows how the client binds to the service using an implementation of
310 section provides more information about this process of binding to the service.</p>
330 <h4>Compared to AIDL</h4>
331 <p>When you need to perform IPC, using a {@link android.os.Messenger} for your interface is
333 all calls to the service, whereas, a pure AIDL interface sends simultaneous requests to the
335 <p>For most applications, the service doesn't need to perform multi-threading, so using a {@link
336 android.os.Messenger} allows the service to handle one call at a time. If it's important
338 href="{@docRoot}guide/components/aidl.html">AIDL</a> to define your interface.</p>
342 <p>If you need your service to communicate with remote processes, then you can use a
343 {@link android.os.Messenger} to provide the interface for your service. This technique allows
344 you to perform interprocess communication (IPC) without the need to use AIDL.</p>
346 <p>Here's a summary of how to use a {@link android.os.Messenger}:</p>
351 <li>The {@link android.os.Handler} is used to create a {@link android.os.Messenger} object
352 (which is a reference to the {@link android.os.Handler}).</li>
354 returns to clients from {@link android.app.Service#onBind onBind()}.</li>
355 <li>Clients use the {@link android.os.IBinder} to instantiate the {@link android.os.Messenger}
356 (that references the service's {@link android.os.Handler}), which the client uses to send
357 {@link android.os.Message} objects to the service.</li>
364 <p>In this way, there are no "methods" for the client to call on the service. Instead, the
372 /** Command to the service to display a message */
392 * Target we publish for clients to send messages to IncomingHandler.
397 * When binding to the service, we return an interface to our messenger
398 * for sending messages to the service.
410 and decides what to do, based on the {@link android.os.Message#what} member.</p>
412 <p>All that a client needs to do is create a {@link android.os.Messenger} based on the {@link
414 android.os.Messenger#send send()}. For example, here's a simple activity that binds to the
415 service and delivers the {@code MSG_SAY_HELLO} message to the service:</p>
431 // established, giving us the object we can use to
449 // Create and send a message to the service, using a supported 'what' value
467 // Bind to the service
484 <p>Notice that this example does not show how the service can respond to the client. If you want the
485 service to respond, then you need to also create a {@link android.os.Messenger} in the client. Then
487 onServiceConnected()} callback, it sends a {@link android.os.Message} to the service that includes
491 <p>You can see an example of how to provide two-way messaging in the <a
501 <h2 id="Binding">Binding to a Service</h2>
503 <p>Application components (clients) can bind to a service by calling
509 bindService()} returns immediately and does <em>not</em> return the {@link android.os.IBinder} to
511 android.content.ServiceConnection} and pass it to {@link android.content.Context#bindService
513 system calls to deliver the {@link android.os.IBinder}.</p>
516 to a service—you <strong>cannot</strong> bind to a service from a broadcast receiver.</p>
518 <p>So, to bind to a service from your client, you must: </p>
524 <dd>The system calls this to deliver the {@link android.os.IBinder} returned by
528 <dd>The Android system calls this when the connection to the service is unexpectedly
537 onServiceConnected()} callback method, you can begin making calls to the service, using
543 shutdown while its not being used. (Appropriate times to bind and unbind is discussed
548 <p>For example, the following snippet connects the client to the service created above by
550 {@link android.os.IBinder} to the {@code LocalService} class and request the {@code
558 // Because we have bound to an explicit
560 // cast its IBinder to a concrete class and directly access it.
574 <p>With this {@link android.content.ServiceConnection}, the client can bind to a service by passing
575 it to {@link android.content.Context#bindService bindService()}. For example:</p>
584 {@link android.content.Intent} that explicitly names the service to bind (thought the intent
588 android.content.Context#BIND_AUTO_CREATE} in order to create the service if its not already alive.
596 <p>Here are some important notes about binding to a service:</p>
604 <li>If you only need to interact with the service while your activity is visible, you
607 <li>If you want your activity to receive responses even while it is stopped in the
610 activity needs to use the service the entire time it's running (even in the background), so if
617 and you should keep the processing that occurs at these transitions to a minimum. Also, if
618 multiple activities in your application bind to the same service and there is a transition between
626 <p>For more sample code, showing how to bind to a service, see the <a
639 to manage the lifecycle of your service if it's purely a bound
640 service—the Android system manages it for you based on whether it is bound to any clients.</p>
642 <p>However, if you choose to implement the {@link android.app.Service#onStartCommand
644 service is now considered to be <em>started</em>. In this case, the service runs until the service
646 android.content.Context#stopService stopService()}, regardless of whether it is bound to any
651 {@code true} if you would like to receive a call to {@link android.app.Service#onRebind
652 onRebind()} the next time a client binds to the service (instead of receiving a call to {@link