Lines Matching full:link
3 parent.link=services.html
30 <li>{@link android.app.Service}</li>
31 <li>{@link android.content.ServiceConnection}</li>
32 <li>{@link android.os.IBinder}</li>
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
67 method returns an {@link android.os.IBinder} object that defines the programming interface that
76 started by calling {@link android.content.Context#startService startService()}, which allows the
77 service to run indefinitely, and also allow a client to bind to the service by calling {@link
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
97 <p>A client can bind to the service by calling {@link android.content.Context#bindService
98 bindService()}. When it does, it must provide an implementation of {@link
99 android.content.ServiceConnection}, which monitors the connection with the service. The {@link
102 client and service, it calls {@link
103 android.content.ServiceConnection#onServiceConnected onServiceConnected()} on the {@link
104 android.content.ServiceConnection}, to deliver the {@link android.os.IBinder} that
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
110 additional clients that bind, without calling {@link android.app.Service#onBind onBind()} again.</p>
113 service was also started by {@link android.content.Context#startService startService()}).</p>
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
124 <p>When creating a service that provides binding, you must provide an {@link android.os.IBinder}
131 (which is common), you should create your interface by extending the {@link android.os.Binder} class
133 {@link android.app.Service#onBind onBind()}. The client receives the {@link android.os.Binder} and
134 can use it to directly access public methods available in either the {@link android.os.Binder}
135 implementation or even the {@link android.app.Service}.
142 an interface for the service with a {@link android.os.Messenger}. In this manner, the service
143 defines a {@link android.os.Handler} that responds to different types of {@link
144 android.os.Message} objects. This {@link android.os.Handler}
145 is the basis for a {@link android.os.Messenger} that can then share an {@link android.os.IBinder}
146 with the client, allowing the client to send commands to the service using {@link
147 android.os.Message} objects. Additionally, the client can define a {@link android.os.Messenger} of
149 <p>This is the simplest way to perform interprocess communication (IPC), because the {@link
157 IPC. The previous technique, using a {@link android.os.Messenger}, is actually based on AIDL as
158 its underlying structure. As mentioned above, the {@link android.os.Messenger} creates a queue of
182 then you can implement your own {@link android.os.Binder} class that provides your client direct
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
200 <li>Return this instance of {@link android.os.Binder} from the {@link
202 <li>In the client, receive the {@link android.os.Binder} from the {@link
213 a {@link android.os.Binder} implementation:</p>
314 {@link android.content.ServiceConnection} and the {@link
337 <p>When you need to perform IPC, using a {@link android.os.Messenger} for your interface is
338 simpler than implementing it with AIDL, because {@link android.os.Messenger} queues
341 <p>For most applications, the service doesn't need to perform multi-threading, so using a {@link
349 {@link android.os.Messenger} to provide the interface for your service. This technique allows
352 <p>Here's a summary of how to use a {@link android.os.Messenger}:</p>
355 <li>The service implements a {@link android.os.Handler} that receives a callback for each
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>
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>
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>
364 <li>The service receives each {@link android.os.Message} in its {@link
365 android.os.Handler}—specifically, in the {@link android.os.Handler#handleMessage
371 client delivers "messages" ({@link android.os.Message} objects) that the service receives in
372 its {@link android.os.Handler}.</p>
374 <p>Here's a simple example service that uses a {@link android.os.Messenger} interface:</p>
414 <p>Notice that the {@link android.os.Handler#handleMessage handleMessage()} method in the
415 {@link android.os.Handler} is where the service receives the incoming {@link android.os.Message}
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
419 android.os.IBinder} returned by the service and send a message using {@link
491 service to respond, then you need to also create a {@link android.os.Messenger} in the client. Then
492 when the client receives the {@link android.content.ServiceConnection#onServiceConnected
493 onServiceConnected()} callback, it sends a {@link android.os.Message} to the service that includes
494 the client's {@link android.os.Messenger} in the {@link android.os.Message#replyTo} parameter
495 of the {@link android.os.Messenger#send send()} method.</p>
510 {@link android.content.Context#bindService bindService()}. The Android
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>
514 <p>The binding is asynchronous. {@link android.content.Context#bindService
515 bindService()} returns immediately and does <em>not</em> return the {@link android.os.IBinder} to
516 the client. To receive the {@link android.os.IBinder}, the client must create an instance of {@link
517 android.content.ServiceConnection} and pass it to {@link android.content.Context#bindService
518 bindService()}. The {@link android.content.ServiceConnection} includes a callback method that the
519 system calls to deliver the {@link android.os.IBinder}.</p>
526 <li>Implement {@link android.content.ServiceConnection}.
529 <dt>{@link android.content.ServiceConnection#onServiceConnected onServiceConnected()}</dt>
530 <dd>The system calls this to deliver the {@link android.os.IBinder} returned by
531 the service's {@link android.app.Service#onBind onBind()} method.</dd>
532 <dt>{@link android.content.ServiceConnection#onServiceDisconnected
539 <li>Call {@link
540 android.content.Context#bindService bindService()}, passing the {@link
542 <li>When the system calls your {@link android.content.ServiceConnection#onServiceConnected
545 <li>To disconnect from the service, call {@link
556 {@link android.os.IBinder} to the {@code LocalService} class and request the {@code
580 <p>With this {@link android.content.ServiceConnection}, the client can bind to a service by passing
581 it to {@link android.content.Context#bindService bindService()}. For example:</p>
589 <li>The first parameter of {@link android.content.Context#bindService bindService()} is an
590 {@link android.content.Intent} that explicitly names the service to bind (thought the intent
592 <li>The second parameter is the {@link android.content.ServiceConnection} object.</li>
593 <li>The third parameter is a flag indicating options for the binding. It should usually be {@link
595 Other possible values are {@link android.content.Context#BIND_DEBUG_UNBIND}
596 and {@link android.content.Context#BIND_NOT_FOREGROUND}, or {@code 0} for none.</li>
604 <li>You should always trap {@link android.os.DeadObjectException} exceptions, which are thrown
611 should bind during {@link android.app.Activity#onStart onStart()} and unbind during {@link
614 background, then you can bind during {@link android.app.Activity#onCreate onCreate()} and unbind
615 during {@link android.app.Activity#onDestroy onDestroy()}. Beware that this implies that your
621 during your activity's {@link android.app.Activity#onResume onResume()} and {@link
644 started with {@link android.app.Service#onStartCommand onStartCommand()}). As such, you don't have
648 <p>However, if you choose to implement the {@link android.app.Service#onStartCommand
651 stops itself with {@link android.app.Service#stopSelf()} or another component calls {@link
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
660 onRebind()} returns void, but the client still receives the {@link android.os.IBinder} in its
661 {@link android.content.ServiceConnection#onServiceConnected onServiceConnected()} callback.
