android.os
public
interface
android.os.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:
- The transact() method will throw a
RemoteException exception if you try to call it on an IBinder
whose process no longer exists.
- The pingBinder() method can be called, and will return false
if the remote process no longer exists.
- The linkToDeath() method can be used to register
a IBinder.DeathRecipient with the IBinder, which will be called when its
containing process goes away.
Nested Classes
Known Indirect Subclasses
Binder,
IGpsStatusListener.Stub,
IInstrumentationWatcher.Stub,
IIntentReceiver.Stub,
ILocationListener.Stub,
IMediaScannerListener.Stub,
IMessenger.Stub,
IMountService.Stub,
IOnKeyguardExitResult.Stub,
IPackageDataObserver.Stub,
IPackageDeleteObserver.Stub,
IPackageInstallObserver.Stub,
IPackageStatsObserver.Stub,
IParentalControlCallback.Stub,
IServiceConnection.Stub,
ISyncAdapter.Stub,
ISyncContext.Stub,
IThumbnailReceiver.Stub,
ITransientNotification.Stub,
IWallpaperServiceCallback.Stub,
IWindow.Stub
Summary
Constants
|
|
|
Value |
|
int |
DUMP_TRANSACTION |
IBinder protocol transaction code: dump internal state. |
1598311760 |
0x5f444d50 |
int |
FIRST_CALL_TRANSACTION |
The first transaction code available for user commands. |
1 |
0x00000001 |
int |
FLAG_ONEWAY |
Flag to transact(int, Parcel, Parcel, int): this is a one-way call, meaning that the
caller returns immediately, without waiting for a result from the
callee. |
1 |
0x00000001 |
int |
INTERFACE_TRANSACTION |
IBinder protocol transaction code: interrogate the recipient side
of the transaction for its canonical interface descriptor. |
1598968902 |
0x5f4e5446 |
int |
LAST_CALL_TRANSACTION |
The last transaction code available for user commands. |
16777215 |
0x00ffffff |
int |
PING_TRANSACTION |
IBinder protocol transaction code: pingBinder(). |
1599098439 |
0x5f504e47 |
Public Methods
Details
Constants
public
static
final
int
DUMP_TRANSACTION
IBinder protocol transaction code: dump internal state.
Constant Value:
1598311760
(0x5f444d50)
public
static
final
int
FIRST_CALL_TRANSACTION
The first transaction code available for user commands.
Constant Value:
1
(0x00000001)
public
static
final
int
FLAG_ONEWAY
Flag to
transact(int, Parcel, Parcel, int): this is a one-way call, meaning that the
caller returns immediately, without waiting for a result from the
callee.
Constant Value:
1
(0x00000001)
public
static
final
int
INTERFACE_TRANSACTION
IBinder protocol transaction code: interrogate the recipient side
of the transaction for its canonical interface descriptor.
Constant Value:
1598968902
(0x5f4e5446)
public
static
final
int
LAST_CALL_TRANSACTION
The last transaction code available for user commands.
Constant Value:
16777215
(0x00ffffff)
public
static
final
int
PING_TRANSACTION
IBinder protocol transaction code: pingBinder().
Constant Value:
1599098439
(0x5f504e47)
Public Methods
public
String
getInterfaceDescriptor()
Get the canonical name of the interface supported by this binder.
public
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.
public
void
linkToDeath(IBinder.DeathRecipient recipient, int flags)
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.
public
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.
public
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.
public
boolean
transact(int code, Parcel data, Parcel reply, int flags)
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.
|
public
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
| 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.
|