Skip to content

Most visited

Recently visited

navigation

RemoteCallbackList

public class RemoteCallbackList
extends Object

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:

  • Keeps track of a set of registered IInterface callbacks, taking care to identify them through their underlying unique IBinder (by calling IInterface.asBinder().
  • Attaches a IBinder.DeathRecipient to each registered interface, so that it can be cleaned out of the list if its process goes away.
  • Performs locking of the underlying list of interfaces to deal with multithreaded incoming calls, and a thread-safe way to iterate over a snapshot of the list without holding its lock.

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.

Summary

Public constructors

RemoteCallbackList()

Public methods

int beginBroadcast()

Prepare to start making calls to the currently registered callbacks.

void finishBroadcast()

Clean up the state of a broadcast previously initiated by calling beginBroadcast().

Object getBroadcastCookie(int index)

Retrieve the cookie associated with the item returned by getBroadcastItem(int).

E getBroadcastItem(int index)

Retrieve an item in the active broadcast that was previously started with beginBroadcast().

int getRegisteredCallbackCount()

Returns the number of registered callbacks.

void kill()

Disable this callback list.

void onCallbackDied(E callback, Object cookie)

Called when the process hosting a callback in the list has gone away.

void onCallbackDied(E callback)

Old version of onCallbackDied(E, Object) that does not provide a cookie.

boolean register(E callback, Object cookie)

Add a new callback to the list.

boolean register(E callback)

Simple version of register(E, Object) that does not take a cookie object.

boolean unregister(E callback)

Remove from the list a callback that was previously added with register(E).

Inherited methods

From class java.lang.Object

Public constructors

RemoteCallbackList

Added in API level 1
RemoteCallbackList ()

Public methods

beginBroadcast

Added in API level 1
int beginBroadcast ()

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();

Returns
int Returns the number of callbacks in the broadcast, to be used with getBroadcastItem(int) to determine the range of indices you can supply.

See also:

finishBroadcast

Added in API level 1
void finishBroadcast ()

Clean up the state of a broadcast previously initiated by calling beginBroadcast(). This must always be called when you are done with a broadcast.

See also:

getBroadcastCookie

Added in API level 4
Object getBroadcastCookie (int index)

Retrieve the cookie associated with the item returned by getBroadcastItem(int).

Parameters
index int
Returns
Object

See also:

getBroadcastItem

Added in API level 1
E getBroadcastItem (int index)

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.

Parameters
index int: Which of the registered callbacks you would like to retrieve. Ranges from 0 to 1-beginBroadcast().
Returns
E Returns the callback interface that you can call. This will always be non-null.

See also:

getRegisteredCallbackCount

Added in API level 17
int getRegisteredCallbackCount ()

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.

Returns
int The size.

kill

Added in API level 1
void kill ()

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.

See also:

onCallbackDied

Added in API level 4
void onCallbackDied (E callback, 
                Object cookie)

Called when the process hosting a callback in the list has gone away. The default implementation calls onCallbackDied(E) for backwards compatibility.

Parameters
callback E: 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 Object: The cookie object original provided to register(E, Object).

See also:

onCallbackDied

Added in API level 1
void onCallbackDied (E callback)

Old version of onCallbackDied(E, Object) that does not provide a cookie.

Parameters
callback E

register

Added in API level 4
boolean register (E callback, 
                Object 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.

Parameters
callback E: 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 Object: Optional additional data to be associated with this callback.
Returns
boolean Returns true if the callback was successfully added to the list. Returns false if it was not added, either because kill() had previously been called or the callback's process has gone away.

See also:

register

Added in API level 1
boolean register (E callback)

Simple version of register(E, Object) that does not take a cookie object.

Parameters
callback E
Returns
boolean

unregister

Added in API level 1
boolean unregister (E callback)

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.

Parameters
callback E: 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.
Returns
boolean Returns true if the callback was found and unregistered. Returns false if the given callback was not found on the list.

See also:

This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.