File	Doc	Category	Size	Date	Package
RemoteCallbackList.java	API Doc	Android 5.1 API	12275	Thu Mar 12 22:22:10 GMT 2015	android.os

RemoteCallbackList

• java.lang.Object

Fields Summary
android.util.ArrayMap	mCallbacks
private Object[]	mActiveBroadcast
private int	mBroadcastCount
private boolean	mKilled

Constructors Summary

Methods Summary
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 {@link #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 {@link Handler}) or do your own synchronization. You must call {@link #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(); return Returns the number of callbacks in the broadcast, to be used with {@link #getBroadcastItem} to determine the range of indices you can supply. see #getBroadcastItem see #finishBroadcast synchronized (mCallbacks) { if (mBroadcastCount > 0) { throw new IllegalStateException( "beginBroadcast() called while already in a broadcast"); } final int N = mBroadcastCount = mCallbacks.size(); if (N <= 0) { return 0; } Object[] active = mActiveBroadcast; if (active == null || active.length < N) { mActiveBroadcast = active = new Object[N]; } for (int i=0; i<N; i++) { active[i] = mCallbacks.valueAt(i); } return N; }
public void	finishBroadcast() Clean up the state of a broadcast previously initiated by calling {@link #beginBroadcast}. This must always be called when you are done with a broadcast. see #beginBroadcast if (mBroadcastCount < 0) { throw new IllegalStateException( "finishBroadcast() called outside of a broadcast"); } Object[] active = mActiveBroadcast; if (active != null) { final int N = mBroadcastCount; for (int i=0; i<N; i++) { active[i] = null; } } mBroadcastCount = -1;
public java.lang.Object	getBroadcastCookie(int index) Retrieve the cookie associated with the item returned by {@link #getBroadcastItem(int)}. see #getBroadcastItem return ((Callback)mActiveBroadcast[index]).mCookie;
public E	getBroadcastItem(int index) Retrieve an item in the active broadcast that was previously started with {@link #beginBroadcast}. This can only be called after the broadcast is started, and its data is no longer valid after calling {@link #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 {@link 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. param index Which of the registered callbacks you would like to retrieve. Ranges from 0 to 1-{@link #beginBroadcast}. return Returns the callback interface that you can call. This will always be non-null. see #beginBroadcast return ((Callback)mActiveBroadcast[index]).mCallback;
public int	getRegisteredCallbackCount() Returns the number of registered callbacks. Note that the number of registered callbacks may differ from the value returned by {@link #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. return The size. synchronized (mCallbacks) { if (mKilled) { return 0; } return mCallbacks.size(); }
public void	kill() Disable this callback list. All registered callbacks are unregistered, and the list is disabled so that future calls to {@link #register} will fail. This should be used when a Service is stopping, to prevent clients from registering callbacks after it is stopped. see #register synchronized (mCallbacks) { for (int cbi=mCallbacks.size()-1; cbi>=0; cbi--) { Callback cb = mCallbacks.valueAt(cbi); cb.mCallback.asBinder().unlinkToDeath(cb, 0); } mCallbacks.clear(); mKilled = true; }
public void	onCallbackDied(E callback) Old version of {@link #onCallbackDied(E, Object)} that does not provide a cookie.
public void	onCallbackDied(E callback, java.lang.Object cookie) Called when the process hosting a callback in the list has gone away. The default implementation calls {@link #onCallbackDied(E)} for backwards compatibility. param 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. param cookie The cookie object original provided to {@link #register(E, Object)}. see #register onCallbackDied(callback);
public boolean	register(E callback) Simple version of {@link RemoteCallbackList#register(E, Object)} that does not take a cookie object. return register(callback, null);
public boolean	register(E callback, java.lang.Object cookie) Add a new callback to the list. This callback will remain in the list until a corresponding call to {@link #unregister} or its hosting process goes away. If the callback was already registered (determined by checking to see if the {@link IInterface#asBinder callback.asBinder()} object is already in the list), then it will be left as-is. Registrations are not counted; a single call to {@link #unregister} will remove a callback after any number calls to register it. param 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. param cookie Optional additional data to be associated with this callback. return Returns true if the callback was successfully added to the list. Returns false if it was not added, either because {@link #kill} had previously been called or the callback's process has gone away. see #unregister see #kill see #onCallbackDied synchronized (mCallbacks) { if (mKilled) { return false; } IBinder binder = callback.asBinder(); try { Callback cb = new Callback(callback, cookie); binder.linkToDeath(cb, 0); mCallbacks.put(binder, cb); return true; } catch (RemoteException e) { return false; } }
public boolean	unregister(E callback) Remove from the list a callback that was previously added with {@link #register}. This uses the {@link IInterface#asBinder 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 {@link #register} for it. param 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. return Returns true if the callback was found and unregistered. Returns false if the given callback was not found on the list. see #register synchronized (mCallbacks) { Callback cb = mCallbacks.remove(callback.asBinder()); if (cb != null) { cb.mCallback.asBinder().unlinkToDeath(cb, 0); return true; } return false; }