Build 1.0_r1(from source)

android.os
Interface IBinder

All Known Implementing Classes:
ActivityManagerNative, ActivityThread.PackageInfo.ReceiverDispatcher.InnerReceiver, ApplicationThreadNative, AudioService, Binder, BinderProxy, BluetoothDeviceService, BulkCursorNative, ContentProvider.Transport, ContentProviderNative, ContentService, ContentServiceNative, CursorToBulkCursorAdaptor, FallbackCheckinService, IAccountsService.Stub, IActivityPendingResult.Stub, IActivityWatcher.Stub, IAlarmManager.Stub, IApplicationToken.Stub, IAudioService.Stub, IBatteryStats.Stub, IBluetoothDevice.Stub, IBluetoothDeviceCallback.Stub, IBluetoothHeadset.Stub, IBluetoothHeadsetCallback.Stub, ICheckinService.Stub, IClipboard.Stub, IConnectivityManager.Stub, IContentObserver.Stub, IGearsDialogService.Stub, IGpsStatusListener.Stub, IHardwareService.Stub, IInstrumentationWatcher.Stub, IIntentReceiver.Stub, IIntentSender.Stub, ILocationListener.Stub, ILocationManager.Stub, IMediaScannerListener.Stub, IMediaScannerService.Stub, IMessenger.Stub, IMountService.Stub, INetStatService.Stub, INotificationManager.Stub, IOnKeyguardExitResult.Stub, IPackageDataObserver.Stub, IPackageDeleteObserver.Stub, IPackageInstallObserver.Stub, IPackageManager.Stub, IPackageStatsObserver.Stub, IParentalControlCallback.Stub, IPermissionController.Stub, IPhoneStateListener.Stub, IPhoneSubInfo.Stub, IPowerManager.Stub, IRotationWatcher.Stub, ISearchManager.Stub, ISensorService.Stub, IServiceConnection.Stub, ISimPhoneBook.Stub, ISms.Stub, IStatusBar.Stub, ISyncAdapter.Stub, ISyncContext.Stub, ITelephony.Stub, ITelephonyRegistry.Stub, IThumbnailReceiver.Stub, ITransientNotification.Stub, IWallpaperService.Stub, IWallpaperServiceCallback.Stub, IWifiManager.Stub, IWindow.Stub, IWindowManager.Stub, IWindowSession.Stub, SearchManagerService, SensorManager, ServiceManagerNative, SyncAdapter.Transport, SyncManager.ActiveSyncContext, ViewRoot.W

public interface IBinder

Base interface for a remotable object, the core part of a lightweight remote procedure call mechanism designed for high performance when performing in-process and cross-process calls. This interface describes the abstract protocol for interacting with a remotable object. Do not implement this interface directly, instead extend from Binder.

The key IBinder API is transact() matched by Binder.onTransact(). These methods allow you to send a call to an IBinder object and receive a call coming in to a Binder object, respectively. This transaction API is synchronous, such that a call to transact() does not return until the target has returned from Binder.onTransact(); this is the expected behavior when calling an object that exists in the local process, and the underlying inter-process communication (IPC) mechanism ensures that these same semantics apply when going across processes.

The data sent through transact() is a Parcel, a generic buffer of data that also maintains some meta-data about its contents. The meta data is used to manage IBinder object references in the buffer, so that those references can be maintained as the buffer moves across processes. This mechanism ensures that when an IBinder is written into a Parcel and sent to another process, if that other process sends a reference to that same IBinder back to the original process, then the original process will receive the same IBinder object back. These semantics allow IBinder/Binder objects to be used as a unique identity (to serve as a token or for other purposes) that can be managed across processes.

The system maintains a pool of transaction threads in each process that it runs in. These threads are used to dispatch all IPCs coming in from other processes. For example, when an IPC is made from process A to process B, the calling thread in A blocks in transact() as it sends the transaction to process B. The next available pool thread in B receives the incoming transaction, calls Binder.onTransact() on the target object, and replies with the result Parcel. Upon receiving its result, the thread in process A returns to allow its execution to continue. In effect, other processes appear to use as additional threads that you did not create executing in your own process.

The Binder system also supports recursion across processes. For example if process A performs a transaction to process B, and process B while handling that transaction calls transact() on an IBinder that is implemented in A, then the thread in A that is currently waiting for the original transaction to finish will take care of calling Binder.onTransact() on the object being called by B. This ensures that the recursion semantics when calling remote binder object are the same as when calling local objects.

When working with remote objects, you often want to find out when they are no longer valid. There are three ways this can be determined:

See Also:
Binder

Nested Class Summary
static interface IBinder.DeathRecipient
          Interface for receiving a callback when the process hosting an IBinder has gone away.
 
Field Summary
static int DUMP_TRANSACTION
          IBinder protocol transaction code: dump internal state.
static int FIRST_CALL_TRANSACTION
          The first transaction code available for user commands.
static int FLAG_ONEWAY
          Flag to transact(int, android.os.Parcel, android.os.Parcel, int): this is a one-way call, meaning that the caller returns immediately, without waiting for a result from the callee.
static int INTERFACE_TRANSACTION
          IBinder protocol transaction code: interrogate the recipient side of the transaction for its canonical interface descriptor.
static int LAST_CALL_TRANSACTION
          The last transaction code available for user commands.
static int PING_TRANSACTION
          IBinder protocol transaction code: pingBinder().
 
Method Summary
 String getInterfaceDescriptor()
          Get the canonical name of the interface supported by this binder.
 boolean isBinderAlive()
          Check to see if the process that the binder is in is still alive.
 void linkToDeath(IBinder.DeathRecipient recipient, int flags)
          Register the recipient for a notification if this binder goes away.
 boolean pingBinder()
          Check to see if the object still exists.
 IInterface queryLocalInterface(String descriptor)
          Attempt to retrieve a local implementation of an interface for this Binder object.
 boolean transact(int code, Parcel data, Parcel reply, int flags)
          Perform a generic operation with the object.
 boolean unlinkToDeath(IBinder.DeathRecipient recipient, int flags)
          Remove a previously registered death notification.
 

Field Detail

FIRST_CALL_TRANSACTION

static final int FIRST_CALL_TRANSACTION
The first transaction code available for user commands.

See Also:
Constant Field Values

LAST_CALL_TRANSACTION

static final int LAST_CALL_TRANSACTION
The last transaction code available for user commands.

See Also:
Constant Field Values

PING_TRANSACTION

static final int PING_TRANSACTION
IBinder protocol transaction code: pingBinder().

See Also:
Constant Field Values

DUMP_TRANSACTION

static final int DUMP_TRANSACTION
IBinder protocol transaction code: dump internal state.

See Also:
Constant Field Values

INTERFACE_TRANSACTION

static final int INTERFACE_TRANSACTION
IBinder protocol transaction code: interrogate the recipient side of the transaction for its canonical interface descriptor.

See Also:
Constant Field Values

FLAG_ONEWAY

static final int FLAG_ONEWAY
Flag to transact(int, android.os.Parcel, android.os.Parcel, int): this is a one-way call, meaning that the caller returns immediately, without waiting for a result from the callee.

See Also:
Constant Field Values
Method Detail

getInterfaceDescriptor

String getInterfaceDescriptor()
                              throws RemoteException
Get the canonical name of the interface supported by this binder.

Throws:
RemoteException

pingBinder

boolean pingBinder()
Check to see if the object still exists.

Returns:
Returns false if the hosting process is gone, otherwise the result (always by default true) returned by the pingBinder() implementation on the other side.

isBinderAlive

boolean isBinderAlive()
Check to see if the process that the binder is in is still alive.

Returns:
false if the process is not alive. Note that if it returns true, the process may have died while the call is returning.

queryLocalInterface

IInterface queryLocalInterface(String descriptor)
Attempt to retrieve a local implementation of an interface for this Binder object. If null is returned, you will need to instantiate a proxy class to marshall calls through the transact() method.


transact

boolean transact(int code,
                 Parcel data,
                 Parcel reply,
                 int flags)
                 throws RemoteException
Perform a generic operation with the object.

Parameters:
code - The action to perform. This should be a number between FIRST_CALL_TRANSACTION and LAST_CALL_TRANSACTION.
data - Marshalled data to send to the target. Most not be null. If you are not sending any data, you must create an empty Parcel that is given here.
reply - Marshalled data to be received from the target. May be null if you are not interested in the return value.
flags - Additional operation flags. Either 0 for a normal RPC, or FLAG_ONEWAY for a one-way RPC.
Throws:
RemoteException

linkToDeath

void linkToDeath(IBinder.DeathRecipient recipient,
                 int flags)
                 throws RemoteException
Register the recipient for a notification if this binder goes away. If this binder object unexpectedly goes away (typically because its hosting process has been killed), then the given IBinder.DeathRecipient's DeathRecipient.binderDied() method will be called.

You will only receive death notifications for remote binders, as local binders by definition can't die without you dying as well.

Throws:
Throws - RemoteException if the target IBinder's process has already died.
RemoteException
See Also:
unlinkToDeath(android.os.IBinder.DeathRecipient, int)

unlinkToDeath

boolean unlinkToDeath(IBinder.DeathRecipient recipient,
                      int flags)
Remove a previously registered death notification. The recipient will no longer be called if this object dies.

Returns:
Returns true if the recipient is successfully unlinked, assuring you that its DeathRecipient.binderDied() method will not be called. Returns false if the target IBinder has already died, meaning the method has been (or soon will be) called.
Throws:
Throws - NoSuchElementException if the given recipient has not been registered with the IBinder, and the IBinder is still alive. Note that if the recipient was never registered, but the IBinder has already died, then this exception will not be thrown, and you will receive a false return value instead.

Build 1.0_r1(from source)

Please submit a feedback, bug or feature