android.os
Class Binder

java.lang.Object
  android.os.Binder

All Implemented Interfaces:

IBinder

Direct Known Subclasses:

ActivityManagerNative, ApplicationThreadNative, BulkCursorNative, ContentProviderNative, ContentServiceNative, 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, ServiceManagerNative

public class Binder
extends Object
implements IBinder

Base class for a remotable object, the core part of a lightweight remote procedure call mechanism defined by IBinder. This class is an implementation of IBinder that provides the standard support creating a local implementation of such an object.

Most developers will not implement this class directly, instead using the aidl tool to describe the desired interface, having it generate the appropriate Binder subclass. You can, however, derive directly from Binder to implement your own custom RPC protocol or simply instantiate a raw Binder object directly to use as a token that can be shared across processes.

See Also:

IBinder

Nested Class Summary

Nested classes/interfaces inherited from interface android.os.IBinder

IBinder.DeathRecipient

Field Summary

Fields inherited from interface android.os.IBinder

DUMP_TRANSACTION, FIRST_CALL_TRANSACTION, FLAG_ONEWAY, INTERFACE_TRANSACTION, LAST_CALL_TRANSACTION, PING_TRANSACTION

Constructor Summary

Binder()
Default constructor initializes the object.

Method Summary

void	attachInterface(IInterface owner, String descriptor) Convenience method for associating a specific interface with the Binder.
static long	clearCallingIdentity() Reset the identity of the incoming IPC to the local process.
protected void	dump(FileDescriptor fd, PrintWriter fout, String[] args) Print the object's state into the given stream.
protected void	finalize() Called by the virtual machine when there are no longer any (non-weak) references to the receiver.
static void	flushPendingCommands() Flush any Binder commands pending in the current thread to the kernel driver.
static int	getCallingPid() Return the ID of the process that sent you the current transaction that is being processed.
static int	getCallingUid() Return the ID of the user assigned to the process that sent you the current transaction that is being processed.
String	getInterfaceDescriptor() Default implementation returns an empty interface name.
boolean	isBinderAlive() Check to see if the process that the binder is in is still alive.
static void	joinThreadPool() Add the calling thread to the IPC thread pool.
void	linkToDeath(IBinder.DeathRecipient recipient, int flags) Local implementation is a no-op.
protected boolean	onTransact(int code, Parcel data, Parcel reply, int flags) Default implementation is a stub that returns false.
boolean	pingBinder() Default implementation always returns true -- if you got here, the object is alive.
IInterface	queryLocalInterface(String descriptor) Use information supplied to attachInterface() to return the associated IInterface if it matches the requested descriptor.
static void	restoreCallingIdentity(long token) Restore the identity of the incoming IPC back to a previously identity that was returned by clearCallingIdentity().
boolean	transact(int code, Parcel data, Parcel reply, int flags) Default implementation rewinds the parcels and calls onTransact.
boolean	unlinkToDeath(IBinder.DeathRecipient recipient, int flags) Local implementation is a no-op.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Binder

public Binder()

Default constructor initializes the object.

Method Detail

getCallingPid

public static final int getCallingPid()

Return the ID of the process that sent you the current transaction that is being processed. This pid can be used with higher-level system services to determine its identity and check permissions. If the current thread is not currently executing an incoming transaction, then its own pid is returned.

getCallingUid

public static final int getCallingUid()

Return the ID of the user assigned to the process that sent you the current transaction that is being processed. This uid can be used with higher-level system services to determine its identity and check permissions. If the current thread is not currently executing an incoming transaction, then its own uid is returned.

clearCallingIdentity

public static final long clearCallingIdentity()

Reset the identity of the incoming IPC to the local process. This can be useful if, while handling an incoming call, you will be calling on interfaces of other objects that may be local to your process and need to do permission checks on the calls coming into them (so they will check the permission of your own local process, and not whatever process originally called you).

Returns:

Returns an opaque token that can be used to restore the original calling identity by passing it to restoreCallingIdentity(long).

See Also:

getCallingPid(), getCallingUid(), restoreCallingIdentity(long)

restoreCallingIdentity

public static final void restoreCallingIdentity(long token)

Restore the identity of the incoming IPC back to a previously identity that was returned by clearCallingIdentity().

Parameters:

token - The opaque token that was previously returned by clearCallingIdentity().

See Also:

clearCallingIdentity()

flushPendingCommands

public static final void flushPendingCommands()

Flush any Binder commands pending in the current thread to the kernel driver. This can be useful to call before performing an operation that may block for a long time, to ensure that any pending object references have been released in order to prevent the process from holding on to objects longer than it needs to.

joinThreadPool

public static final void joinThreadPool()

Add the calling thread to the IPC thread pool. This function does not return until the current process is exiting.

attachInterface

public void attachInterface(IInterface owner,
                            String descriptor)

Convenience method for associating a specific interface with the Binder. After calling, queryLocalInterface() will be implemented for you to return the given owner IInterface when the corresponding descriptor is requested.

getInterfaceDescriptor

public String getInterfaceDescriptor()

Default implementation returns an empty interface name.

Specified by:

getInterfaceDescriptor in interface IBinder

pingBinder

public boolean pingBinder()

Default implementation always returns true -- if you got here, the object is alive.

Specified by:

pingBinder in interface IBinder

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

public boolean isBinderAlive()

Check to see if the process that the binder is in is still alive. Note that if you're calling on a local binder, this always returns true because your process is alive if you're calling it.

Specified by:

isBinderAlive in interface IBinder

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

public IInterface queryLocalInterface(String descriptor)

Use information supplied to attachInterface() to return the associated IInterface if it matches the requested descriptor.

Specified by:

queryLocalInterface in interface IBinder

onTransact

protected boolean onTransact(int code,
                             Parcel data,
                             Parcel reply,
                             int flags)
                      throws RemoteException

Default implementation is a stub that returns false. You will want to override this to do the appropriate unmarshalling of transactions.

If you want to call this, call transact().

Throws:

RemoteException

dump

protected void dump(FileDescriptor fd,
                    PrintWriter fout,
                    String[] args)

Print the object's state into the given stream.

Parameters:

fd - The raw file descriptor that the dump is being sent to.

fout - The file to which you should dump your state. This will be closed for you after you return.

args - additional arguments to the dump request.

transact

public final boolean transact(int code,
                              Parcel data,
                              Parcel reply,
                              int flags)
                       throws RemoteException

Default implementation rewinds the parcels and calls onTransact. On the remote side, transact calls into the binder to do the IPC.

Specified by:

transact in interface IBinder

Parameters:

code - The action to perform. This should be a number between IBinder.FIRST_CALL_TRANSACTION and IBinder.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 IBinder.FLAG_ONEWAY for a one-way RPC.

Throws:

RemoteException

linkToDeath

public void linkToDeath(IBinder.DeathRecipient recipient,
                        int flags)

Local implementation is a no-op.

Specified by:

linkToDeath in interface IBinder

See Also:

IBinder.unlinkToDeath(android.os.IBinder.DeathRecipient, int)

unlinkToDeath

public boolean unlinkToDeath(IBinder.DeathRecipient recipient,
                             int flags)

Local implementation is a no-op.

Specified by:

unlinkToDeath in interface IBinder

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.

finalize

protected void finalize()
                 throws Throwable

Description copied from class: Object

Called by the virtual machine when there are no longer any (non-weak) references to the receiver. Subclasses can use this facility to guarantee that any associated resources are cleaned up before the receiver is garbage collected. Uncaught exceptions which are thrown during the running of the method cause it to terminate immediately, but are otherwise ignored.

Note: The virtual machine assumes that the implementation in class Object is empty.

Overrides:

finalize in class Object

Throws:

Throwable - The virtual machine ignores any exceptions which are thrown during finalization.