Android
android.os
public class

android.os.Binder

java.lang.Object
android.os.Binder 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.

Known Direct Subclasses

See Also

Summary

Constants inherited from interface android.os.IBinder

Public Constructors

            Binder()
Default constructor initializes the object.

Public Methods

          void  attachInterface(IInterface owner, String descriptor)
Convenience method for associating a specific interface with the Binder.
    final  static    long  clearCallingIdentity()
Reset the identity of the incoming IPC to the local process.
    final  static    void  flushPendingCommands()
Flush any Binder commands pending in the current thread to the kernel driver.
    final  static    int  getCallingPid()
Return the ID of the process that sent you the current transaction that is being processed.
    final  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. Note that if you're calling on a local binder, this always returns true because your process is alive if you're calling it.
    final  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.
          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.
    final  static    void  restoreCallingIdentity(long token)
Restore the identity of the incoming IPC back to a previously identity that was returned by clearCallingIdentity().
    final      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.

Protected Methods

          void  dump(FileDescriptor fd, PrintWriter fout, String[] args)
Print the object's state into the given stream.
          void  finalize()
Called by the virtual machine when there are no longer any (non-weak) references to the receiver.
          boolean  onTransact(int code, Parcel data, Parcel reply, int flags)
Default implementation is a stub that returns false.
Methods inherited from class java.lang.Object
Methods inherited from interface android.os.IBinder

Details

Public Constructors

public Binder()

Default constructor initializes the object.

Public Methods

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.

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

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.

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.

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.

public String getInterfaceDescriptor()

Default implementation returns an empty interface name.

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.

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.

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

Local implementation is a no-op.

public boolean pingBinder()

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

public IInterface queryLocalInterface(String descriptor)

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

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().

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

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

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

Local implementation is a no-op.

Protected Methods

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.

protected void finalize()

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.

Throws

Throwable

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

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().

Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:48