# Print output for @column tags ?>
Developers

- Design
- Develop
- Distribute

Developer Console

## Most visited

## Recently visited

## Results for

Summary: Ctors | Methods | Inherited Methods

# 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()`.
`Object` | `getRegisteredCallbackCookie(int index)` Return any cookie associated with a currently registered callback.
`int` | `getRegisteredCallbackCount()` Returns the number of registered callbacks.
`E` | `getRegisteredCallbackItem(int index)` Return a currently registered callback.
`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, java.lang.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 `RemoteCallbackList#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`
`Object` | `clone()` Creates and returns a copy of this object.
`boolean` | `equals(Object obj)` Indicates whether some other object is "equal to" this one.
`void` | `finalize()` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.
`final Class<?>` | `getClass()` Returns the runtime class of this `Object`.
`int` | `hashCode()` Returns a hash code value for the object.
`final void` | `notify()` Wakes up a single thread that is waiting on this object's monitor.
`final void` | `notifyAll()` Wakes up all threads that are waiting on this object's monitor.
`String` | `toString()` Returns a string representation of the object.
`final void` | `wait(long timeout, int nanos)` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed.
`final void` | `wait(long timeout)` Causes the current thread to wait until either another thread invokes the `notify()` method or the `notifyAll()` method for this object, or a specified amount of time has elapsed.
`final void` | `wait()` Causes the current thread to wait until another thread invokes the `notify()` method or the `notifyAll()` method for this object.

## Public constructors

### RemoteCallbackList

    public RemoteCallbackList ()

## Public methods

### beginBroadcast

    public 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:

- `getBroadcastItem(int)`
- `finishBroadcast()`

### finishBroadcast

    public 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:

- `beginBroadcast()`

### getBroadcastCookie

    public Object getBroadcastCookie (int index)

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

Parameters
`index` | `int`

Returns
`Object` |

See also:

- `getBroadcastItem(int)`

### getBroadcastItem

    public 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:

- `beginBroadcast()`

### getRegisteredCallbackCookie

    public Object getRegisteredCallbackCookie (int index)

Return any cookie associated with a currently registered callback. Note that this is not the same as `getBroadcastCookie(int)` and should not be used interchangeably with it. This method returns the current cookie registered at the given index, not the current broadcast state. This means that it is not itself thread-safe: any call to `register(E)` or `unregister(E)` will change these indices, so you must do your own thread safety between these to protect from such changes.

Parameters
`index` | `int`: Index of which registration cookie to return, from 0 to `getRegisteredCallbackCount()` - 1.

Returns
`Object` | Returns whatever cookie object is associated with this index, or null if `kill()` has been called.

### getRegisteredCallbackCount

    public 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.

### getRegisteredCallbackItem

    public E getRegisteredCallbackItem (int index)

Return a currently registered callback. Note that this is not the same as `getBroadcastItem(int)` and should not be used interchangeably with it. This method returns the registered callback at the given index, not the current broadcast state. This means that it is not itself thread-safe: any call to `register(E)` or `unregister(E)` will change these indices, so you must do your own thread safety between these to protect from such changes.

Parameters
`index` | `int`: Index of which callback registration to return, from 0 to `getRegisteredCallbackCount()` - 1.

Returns
`E` | Returns whatever callback is associated with this index, or null if `kill()` has been called.

### kill

    public 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:

- `register(E)`

### onCallbackDied

    public 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, java.lang.Object)`.

See also:

- `register(E)`

### onCallbackDied

    public void onCallbackDied (E callback)

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

Parameters
`callback` | `E`

### register

    public 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 `IInterface#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:

- `unregister(E)`
- `kill()`
- `onCallbackDied(E)`

### register

    public boolean register (E callback)

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

Parameters
`callback` | `E`

Returns
`boolean` |

### unregister

    public boolean unregister (E callback)

Remove from the list a callback that was previously added with `register(E)`. This uses the `IInterface#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:

- `register(E)`

Full name *
Email address *
Company / developer name
One of your Play Store app URLs *
Which best describes your business:*
Apps
Games
Apps & Games
*
*