Build 1.0_r1(from source)

android.os
Class Binder

java.lang.Object
  extended by 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.

Build 1.0_r1(from source)

Please submit a feedback, bug or feature