Interface IBinder
-
- All Known Subinterfaces:
IMessenger
public interface IBinderBase 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 fromBinder.The key IBinder API is
transact()matched byBinder.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 totransact()does not return until the target has returned fromBinder.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 aRemoteExceptionexception 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 aIBinder.DeathRecipientwith the IBinder, which will be called when its containing process goes away.
- See Also:
Binder
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static interfaceIBinder.DeathRecipientInterface for receiving a callback when the process hosting an IBinder has gone away.
-
Field Summary
Fields Modifier and Type Field Description static intDUMP_TRANSACTIONIBinder protocol transaction code: dump internal state.static intFIRST_CALL_TRANSACTIONThe first transaction code available for user commands.static intFLAG_ONEWAYFlag to#transact: this is a one-way call, meaning that the caller returns immediately, without waiting for a result from the callee.static intINTERFACE_TRANSACTIONIBinder protocol transaction code: interrogate the recipient side of the transaction for its canonical interface descriptor.static intLAST_CALL_TRANSACTIONThe last transaction code available for user commands.static intLIKE_TRANSACTIONIBinder protocol transaction code: tell an app asynchronously that the caller likes it.static intMAX_IPC_SIZELimit that should be placed on IPC sizes to keep them safely under the transaction buffer limit.static intPING_TRANSACTIONIBinder protocol transaction code: pingBinder().static intSYSPROPS_TRANSACTIONstatic intTWEET_TRANSACTIONIBinder protocol transaction code: send a tweet to the target object.
-
-
-
Field Detail
-
FIRST_CALL_TRANSACTION
static final int FIRST_CALL_TRANSACTION
The first transaction code available for user commands.- See Also:
- Constant Field Values
-
LAST_CALL_TRANSACTION
static final int LAST_CALL_TRANSACTION
The last transaction code available for user commands.- See Also:
- Constant Field Values
-
PING_TRANSACTION
static final int PING_TRANSACTION
IBinder protocol transaction code: pingBinder().- See Also:
- Constant Field Values
-
DUMP_TRANSACTION
static final int DUMP_TRANSACTION
IBinder protocol transaction code: dump internal state.- See Also:
- Constant Field Values
-
INTERFACE_TRANSACTION
static final int INTERFACE_TRANSACTION
IBinder protocol transaction code: interrogate the recipient side of the transaction for its canonical interface descriptor.- See Also:
- Constant Field Values
-
TWEET_TRANSACTION
static final int TWEET_TRANSACTION
IBinder protocol transaction code: send a tweet to the target object. The data in the parcel is intended to be delivered to a shared messaging service associated with the object; it can be anything, as long as it is not more than 130 UTF-8 characters to conservatively fit within common messaging services. As part ofBuild.VERSION_CODES#HONEYCOMB_MR2, all Binder objects are expected to support this protocol for fully integrated tweeting across the platform. To support older code, the default implementation logs the tweet to the main log as a simple emulation of broadcasting it publicly over the Internet.Also, upon completing the dispatch, the object must make a cup of tea, return it to the caller, and exclaim "jolly good message old boy!".
- See Also:
- Constant Field Values
-
LIKE_TRANSACTION
static final int LIKE_TRANSACTION
IBinder protocol transaction code: tell an app asynchronously that the caller likes it. The app is responsible for incrementing and maintaining its own like counter, and may display this value to the user to indicate the quality of the app. This is an optional command that applications do not need to handle, so the default implementation is to do nothing.There is no response returned and nothing about the system will be functionally affected by it, but it will improve the app's self-esteem.
- See Also:
- Constant Field Values
-
SYSPROPS_TRANSACTION
static final int SYSPROPS_TRANSACTION
- See Also:
- Constant Field Values
-
FLAG_ONEWAY
static final int FLAG_ONEWAY
Flag to#transact: this is a one-way call, meaning that the caller returns immediately, without waiting for a result from the callee. Applies only if the caller and callee are in different processes.- See Also:
- Constant Field Values
-
MAX_IPC_SIZE
static final int MAX_IPC_SIZE
Limit that should be placed on IPC sizes to keep them safely under the transaction buffer limit.- See Also:
- Constant Field Values
-
-