java.lang.Object | |
↳ | android.os.RemoteCallbackList<E extends android.os.IInterface> |
Takes care of the grunt work of maintaining a list of remote interfaces,
typically for the use of performing callbacks from a
Service
to its clients. In particular, this:
IInterface
callbacks,
taking care to identify them through their underlying unique IBinder
(by calling IInterface.asBinder()
.
IBinder.DeathRecipient
to
each registered interface, so that it can be cleaned out of the list if its
process goes away.
To use this class, simply create a single instance along with your
service, and call its register(E)
and unregister(E)
methods
as client register and unregister with your service. To call back on to
the registered clients, use beginBroadcast()
,
getBroadcastItem(int)
, and finishBroadcast()
.
If a registered callback's process goes away, this class will take
care of automatically removing it from the list. If you want to do
additional work in this situation, you can create a subclass that
implements the onCallbackDied(E)
method.
Public Constructors | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Public Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
Prepare to start making calls to the currently registered callbacks.
| |||||||||||
Clean up the state of a broadcast previously initiated by calling
beginBroadcast() . | |||||||||||
Retrieve the cookie associated with the item
returned by
getBroadcastItem(int) . | |||||||||||
Retrieve an item in the active broadcast that was previously started
with
beginBroadcast() . | |||||||||||
Returns the number of registered callbacks.
| |||||||||||
Disable this callback list.
| |||||||||||
Called when the process hosting a callback in the list has gone away.
| |||||||||||
Old version of
onCallbackDied(E, Object) that
does not provide a cookie. | |||||||||||
Add a new callback to the list.
| |||||||||||
Simple version of
register(E, Object)
that does not take a cookie object. | |||||||||||
Remove from the list a callback that was previously added with
register(E) . |
[Expand]
Inherited Methods | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
From class
java.lang.Object
|
Prepare to start making calls to the currently registered callbacks.
This creates a copy of the callback list, which you can retrieve items
from using getBroadcastItem(int)
. Note that only one broadcast can
be active at a time, so you must be sure to always call this from the
same thread (usually by scheduling with Handler
) or
do your own synchronization. You must call finishBroadcast()
when done.
A typical loop delivering a broadcast looks like this:
int i = callbacks.beginBroadcast(); while (i > 0) { i--; try { callbacks.getBroadcastItem(i).somethingHappened(); } catch (RemoteException e) { // The RemoteCallbackList will take care of removing // the dead object for us. } } callbacks.finishBroadcast();
getBroadcastItem(int)
to determine the range of indices you
can supply.Clean up the state of a broadcast previously initiated by calling
beginBroadcast()
. This must always be called when you are done
with a broadcast.
Retrieve the cookie associated with the item
returned by getBroadcastItem(int)
.
Retrieve an item in the active broadcast that was previously started
with beginBroadcast()
. This can only be called after
the broadcast is started, and its data is no longer valid after
calling finishBroadcast()
.
Note that it is possible for the process of one of the returned
callbacks to go away before you call it, so you will need to catch
RemoteException
when calling on to the returned object.
The callback list itself, however, will take care of unregistering
these objects once it detects that it is no longer valid, so you can
handle such an exception by simply ignoring it.
index | Which of the registered callbacks you would like to
retrieve. Ranges from 0 to 1-beginBroadcast() . |
---|
Returns the number of registered callbacks. Note that the number of registered
callbacks may differ from the value returned by beginBroadcast()
since
the former returns the number of callbacks registered at the time of the call
and the second the number of callback to which the broadcast will be delivered.
This function is useful to decide whether to schedule a broadcast if this requires doing some work which otherwise would not be performed.
Disable this callback list. All registered callbacks are unregistered,
and the list is disabled so that future calls to register(E)
will
fail. This should be used when a Service is stopping, to prevent clients
from registering callbacks after it is stopped.
Called when the process hosting a callback in the list has gone away.
The default implementation calls onCallbackDied(E)
for backwards compatibility.
callback | The callback whose process has died. Note that, since its process has died, you can not make any calls on to this interface. You can, however, retrieve its IBinder and compare it with another IBinder to see if it is the same object. |
---|---|
cookie | The cookie object original provided to
register(E, Object) . |
Old version of onCallbackDied(E, Object)
that
does not provide a cookie.
Add a new callback to the list. This callback will remain in the list
until a corresponding call to unregister(E)
or its hosting process
goes away. If the callback was already registered (determined by
checking to see if the callback.asBinder()
object is already in the list), then it will be left as-is.
Registrations are not counted; a single call to unregister(E)
will remove a callback after any number calls to register it.
callback | The callback interface to be added to the list. Must not be null -- passing null here will cause a NullPointerException. Most services will want to check for null before calling this with an object given from a client, so that clients can't crash the service with bad data. |
---|---|
cookie | Optional additional data to be associated with this callback. |
kill()
had
previously been called or the callback's process has gone away.Simple version of register(E, Object)
that does not take a cookie object.
Remove from the list a callback that was previously added with
register(E)
. This uses the
callback.asBinder()
object to correctly
find the previous registration.
Registrations are not counted; a single unregister call will remove
a callback after any number calls to register(E)
for it.
callback | The callback to be removed from the list. Passing null here will cause a NullPointerException, so you will generally want to check for null before calling. |
---|