RemoteCallbackList

beginBroadcast

open fun beginBroadcast(): Int

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

finishBroadcast

open fun finishBroadcast(): Unit

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

getBroadcastCookie

open fun getBroadcastCookie(index: Int): Any!

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

getBroadcastItem

open fun getBroadcastItem(index: Int): E

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.

getRegisteredCallbackCookie

open fun getRegisteredCallbackCookie(index: Int): Any!

Return any cookie associated with a currently registered callback. Note that this is not the same as getBroadcastCookie 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 or unregister will change these indices, so you must do your own thread safety between these to protect from such changes.

getRegisteredCallbackCount

open fun getRegisteredCallbackCount(): Int

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.

getRegisteredCallbackItem

open fun getRegisteredCallbackItem(index: Int): E

Return a currently registered callback. Note that this is not the same as getBroadcastItem 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 or unregister will change these indices, so you must do your own thread safety between these to protect from such changes.

kill

open fun kill(): Unit

Disable this callback list. All registered callbacks are unregistered, and the list is disabled so that future calls to #register will fail. This should be used when a Service is stopping, to prevent clients from registering callbacks after it is stopped.

onCallbackDied

open fun onCallbackDied(callback: E): Unit

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

onCallbackDied

open fun onCallbackDied(
    callback: E, 
    cookie: Any!
): Unit

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

register

open fun register(callback: E): Boolean

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

register

open fun register(
    callback: E, 
    cookie: Any!
): Boolean

Add a new callback to the list. This callback will remain in the list until a corresponding call to unregister 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 will remove a callback after any number calls to register it.

unregister

open fun unregister(callback: E): Boolean

Remove from the list a callback that was previously added with #register. 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 for it.