public class Binder extends Object implements IBinder
IBinder
.
This class is an implementation of IBinder that provides
standard 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.
This class is just a basic IPC primitive; it has no impact on an application's
lifecycle, and is valid only as long as the process that created it continues to run.
To use this correctly, you must be doing so within the context of a top-level
application component (a Service
, Activity
,
or ContentProvider
) that lets the system know your process
should remain running.
You must keep in mind the situations in which your process
could go away, and thus require that you later re-create a new Binder and re-attach
it when the process starts again. For example, if you are using this within an
Activity
, your activity's process may be killed any time the
activity is not started; if the activity is later re-created you will need to
create a new Binder and hand it back to the correct place again; you need to be
aware that your process may be started for another reason (for example to receive
a broadcast) that will not involve re-creating the activity and thus run its code
to create a new Binder.
IBinder
IBinder.DeathRecipient
Modifier and Type | Field and Description |
---|---|
static boolean |
LOG_RUNTIME_EXCEPTION |
DUMP_TRANSACTION, FIRST_CALL_TRANSACTION, FLAG_ONEWAY, INTERFACE_TRANSACTION, LAST_CALL_TRANSACTION, LIKE_TRANSACTION, MAX_IPC_SIZE, PING_TRANSACTION, SHELL_COMMAND_TRANSACTION, SYSPROPS_TRANSACTION, TWEET_TRANSACTION
Constructor and Description |
---|
Binder()
Default constructor initializes the object.
|
Modifier and Type | Method and Description |
---|---|
void |
attachInterface(IInterface owner,
String descriptor)
Convenience method for associating a specific interface with the Binder.
|
static void |
blockUntilThreadAvailable()
Call blocks until the number of executing binder threads is less
than the maximum number of binder threads allowed for this process.
|
static long |
clearCallingIdentity()
Reset the identity of the incoming IPC on the current thread.
|
static void |
disableTracing()
Disable Binder IPC tracing.
|
protected void |
dump(FileDescriptor fd,
PrintWriter fout,
String[] args)
Print the object's state into the given stream.
|
void |
dump(FileDescriptor fd,
String[] args)
Implemented to call the more convenient version
dump(FileDescriptor, PrintWriter, String[]) . |
void |
dumpAsync(FileDescriptor fd,
String[] args)
Like
dump(FileDescriptor, String[]) , but ensures the target
executes asynchronously. |
static void |
enableTracing()
Enable Binder IPC tracing.
|
protected void |
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
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 Linux uid assigned to the process that sent you the
current transaction that is being processed.
|
static UserHandle |
getCallingUserHandle()
Return the UserHandle assigned to the process that sent you the
current transaction that is being processed.
|
String |
getInterfaceDescriptor()
Default implementation returns an empty interface name.
|
static int |
getThreadStrictModePolicy()
Gets the current native thread-local StrictMode policy mask.
|
static TransactionTracker |
getTransactionTracker()
Get the binder transaction tracker for this process.
|
boolean |
isBinderAlive()
Check to see if the process that the binder is in is still alive.
|
static boolean |
isProxy(IInterface iface)
Returns true if the specified interface is a proxy.
|
static boolean |
isTracingEnabled()
Check if binder transaction tracing is enabled.
|
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.
|
void |
onShellCommand(FileDescriptor in,
FileDescriptor out,
FileDescriptor err,
String[] args,
ResultReceiver resultReceiver)
|
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 on the current thread
back to a previously identity that was returned by
clearCallingIdentity() . |
static void |
setDumpDisabled(String msg)
Control disabling of dump calls in this process.
|
static void |
setThreadStrictModePolicy(int policyMask)
Sets the native thread-local StrictMode policy mask.
|
void |
shellCommand(FileDescriptor in,
FileDescriptor out,
FileDescriptor err,
String[] args,
ResultReceiver resultReceiver)
Execute a shell command on this object.
|
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.
|
public static void enableTracing()
public static void disableTracing()
public static boolean isTracingEnabled()
public static TransactionTracker getTransactionTracker()
public static final int getCallingPid()
public static final int getCallingUid()
public static final UserHandle getCallingUserHandle()
getCallingUid()
in that a
particular user will have multiple distinct apps running under it each
with their own uid. If the current thread is not currently executing an
incoming transaction, then its own UserHandle is returned.public static final long clearCallingIdentity()
restoreCallingIdentity(long)
.getCallingPid()
,
getCallingUid()
,
restoreCallingIdentity(long)
public static final void restoreCallingIdentity(long token)
clearCallingIdentity()
.token
- The opaque token that was previously returned by
clearCallingIdentity()
.clearCallingIdentity()
public static final void setThreadStrictModePolicy(int policyMask)
The StrictMode settings are kept in two places: a Java-level threadlocal for libcore/Dalvik, and a native threadlocal (set here) for propagation via Binder calls. This is a little unfortunate, but necessary to break otherwise more unfortunate dependencies either of Dalvik on Android, or Android native-only code on Dalvik.
StrictMode
public static final int getThreadStrictModePolicy()
setThreadStrictModePolicy(int)
public static final void flushPendingCommands()
public static final void joinThreadPool()
public static final boolean isProxy(IInterface iface)
public static final void blockUntilThreadAvailable()
public void attachInterface(IInterface owner, String descriptor)
public String getInterfaceDescriptor()
getInterfaceDescriptor
in interface IBinder
public boolean pingBinder()
pingBinder
in interface IBinder
public boolean isBinderAlive()
isBinderAlive
in interface IBinder
public IInterface queryLocalInterface(String descriptor)
queryLocalInterface
in interface IBinder
public static void setDumpDisabled(String msg)
msg
- The message to show instead of the dump; if null, dumps are
re-enabled.protected boolean onTransact(int code, Parcel data, Parcel reply, int flags) throws RemoteException
If you want to call this, call transact().
RemoteException
public void dump(FileDescriptor fd, String[] args)
dump(FileDescriptor, PrintWriter, String[])
.public void dumpAsync(FileDescriptor fd, String[] args)
dump(FileDescriptor, String[])
, but ensures the target
executes asynchronously.protected void dump(FileDescriptor fd, PrintWriter fout, String[] args)
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.public void shellCommand(FileDescriptor in, FileDescriptor out, FileDescriptor err, String[] args, ResultReceiver resultReceiver) throws RemoteException
IBinder
shellCommand
in interface IBinder
in
- The raw file descriptor that an input data stream can be read from.out
- The raw file descriptor that normal command messages should be written to.err
- The raw file descriptor that command error messages should be written to.args
- Command-line arguments.resultReceiver
- Called when the command has finished executing, with the result code.RemoteException
public void onShellCommand(FileDescriptor in, FileDescriptor out, FileDescriptor err, String[] args, ResultReceiver resultReceiver) throws RemoteException
shellCommand(java.io.FileDescriptor, java.io.FileDescriptor, java.io.FileDescriptor, java.lang.String[], android.os.ResultReceiver)
. The default implementation simply prints
an error message. Override and replace with your own.
Note: no permission checking is done before calling this method; you must
apply any security checks as appropriate for the command being executed.
Consider using ShellCommand
to help in the implementation.
RemoteException
public final boolean transact(int code, Parcel data, Parcel reply, int flags) throws RemoteException
transact
in interface IBinder
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. Must 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.RemoteException
public void linkToDeath(IBinder.DeathRecipient recipient, int flags)
linkToDeath
in interface IBinder
IBinder.unlinkToDeath(android.os.IBinder.DeathRecipient, int)
public boolean unlinkToDeath(IBinder.DeathRecipient recipient, int flags)
unlinkToDeath
in interface IBinder
true
if the recipient is successfully
unlinked, assuring you that its
DeathRecipient.binderDied()
method
will not be called; false
if the target IBinder has already
died, meaning the method has been (or soon will be) called.protected void finalize() throws Throwable
Object
finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the JavaTM virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.