RemoteCallbackList

FROZEN_CALLEE_POLICY_DROP

 public static final int FROZEN_CALLEE_POLICY_DROP

When the callback recipient's process is frozen, callbacks are suppressed as if they never happened. This could be useful in the case where the recipient wishes to react to callbacks only when they occur while the recipient is not frozen. For example, certain network events are only worth responding to if the response can be immediate. Another example is recipients having another way of getting the latest state once it's unfrozen. Therefore there is no need to save callbacks that happened while the recipient was frozen.

Constant Value: 3 (0x00000003)

FROZEN_CALLEE_POLICY_ENQUEUE_ALL

 public static final int FROZEN_CALLEE_POLICY_ENQUEUE_ALL

When the callback recipient's process is frozen, callbacks are enqueued so they're invoked after the recipient is unfrozen. This is commonly used when the recipient wants to receive all callbacks without losing any history, e.g. the recipient maintains a running count of events that occurred. Queued callbacks are invoked in the order they were originally broadcasted.

Constant Value: 1 (0x00000001)

FROZEN_CALLEE_POLICY_ENQUEUE_MOST_RECENT

 public static final int FROZEN_CALLEE_POLICY_ENQUEUE_MOST_RECENT

When the callback recipient's process is frozen, only the most recent callback is enqueued, which is later invoked after the recipient is unfrozen. This can be used when only the most recent state matters, for instance when clients are listening to screen brightness changes.

Constant Value: 2 (0x00000002)

FROZEN_CALLEE_POLICY_UNSET

 public static final int FROZEN_CALLEE_POLICY_UNSET

Callbacks are invoked immediately regardless of the frozen state of the target process. Not recommended. Only exists for backward-compatibility. This represents the behavior up to SDK 35. Starting with SDK 36, clients should set a policy to govern callback invocations when recipients are frozen.

Constant Value: 0 (0x00000000)

RemoteCallbackList

 public RemoteCallbackList ()

Creates a RemoteCallbackList with FROZEN_CALLEE_POLICY_UNSET. This is equivalent to

 new RemoteCallbackList.Build(RemoteCallbackList.FROZEN_CALLEE_POLICY_UNSET).build() 

beginBroadcast

 public int beginBroadcast ()

Use broadcast(java.util.function.Consumer) instead to ensure proper handling of frozen processes. Prepare to start making calls to the currently registered interfaces. This creates a copy of the interface 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 = interfaces.beginBroadcast(); while (i > 0) { i--; try { interfaces.getBroadcastItem(i).somethingHappened(); } catch (RemoteException e) { // The RemoteCallbackList will take care of removing // the dead object for us. } } interfaces.finishBroadcast();

broadcast

 public void broadcast (Consumer<E> callback)

Performs callback on each registered interface. This is equivalent to #beginBroadcast, followed by iterating over the items using #getBroadcastItem and then @finishBroadcast, except that this method supports frozen callee policies.

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.

getBroadcastCookie

 public Object getBroadcastCookie (int index)

Retrieve the cookie associated with the item returned by 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 interfaces to go away before you call it, so you will need to catch RemoteException when calling on to the returned object. The interface 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.

getExecutor

 public Executor getExecutor ()

Returns the executor used when invoking callbacks asynchronously.

getFrozenCalleePolicy

 public int getFrozenCalleePolicy ()

Returns the frozen callee policy.

getMaxQueueSize

 public int getMaxQueueSize ()

Returns the max queue size.

getRegisteredCallbackCookie

 public Object getRegisteredCallbackCookie (int index)

Return any cookie associated with a currently registered interface. 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.

getRegisteredCallbackCount

 public int getRegisteredCallbackCount ()

Returns the number of registered interfaces. Note that the number of registered interfaces may differ from the value returned by beginBroadcast() since the former returns the number of interfaces registered at the time of the call and the second the number of interfaces 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

 public E getRegisteredCallbackItem (int index)

Return a currently registered interface. Note that this is not the same as getBroadcastItem(int) and should not be used interchangeably with it. This method returns the registered interface 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.

kill

 public void kill ()

Disable this interface list. All registered interfaces 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 interfaces after it is stopped.

onCallbackDied

 public void onCallbackDied (E callbackInterface, Object cookie)

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

onCallbackDied

 public void onCallbackDied (E callbackInterface)

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

register

 public boolean register (E callbackInterface, Object cookie)

Add a new interface to the list. This interface will remain in the list until a corresponding call to unregister(E) or its hosting process goes away. If the interface was already registered (determined by checking to see if the callbackInterface.asBinder() object is already in the list), then it will be replaced with the new interface. Registrations are not counted; a single call to unregister(E) will remove an interface after any number calls to register it.

register

 public boolean register (E callbackInterface)

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

unregister

 public boolean unregister (E callbackInterface)

Remove from the list an interface that was previously added with register(E). This uses the callbackInterface.asBinder() object to correctly find the previous registration. Registrations are not counted; a single unregister call will remove an interface after any number calls to register(E) for it.