IBinder Interface

Reference

Definition

Namespace:: Android.OS

Assembly:: Mono.Android.dll

Important

Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

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.

[Android.Runtime.Register("android/os/IBinder", "", "Android.OS.IBinderInvoker")]
public interface IBinder : Android.Runtime.IJavaObject, IDisposable, Java.Interop.IJavaPeerable

[<Android.Runtime.Register("android/os/IBinder", "", "Android.OS.IBinderInvoker")>]
type IBinder = interface
    interface IJavaObject
    interface IDisposable
    interface IJavaPeerable

Derived: Android.OS.Binder

Attributes: RegisterAttribute

Implements: IJavaObject IJavaPeerable IDisposable

Remarks

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 transact() matched by Binder#onTransact 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 transact() does not return until the target has returned from Binder#onTransact 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: <ul> <li> The #transact transact() method will throw a RemoteException exception if you try to call it on an IBinder whose process no longer exists. <li> The #pingBinder() method can be called, and will return false if the remote process no longer exists. <li> The #linkToDeath linkToDeath() method can be used to register a DeathRecipient with the IBinder, which will be called when its containing process goes away. </ul>

Java documentation for android.os.IBinder.

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

Fields

DumpTransaction	IBinder protocol transaction code: dump internal state.
FirstCallTransaction	The first transaction code available for user commands.
InterfaceTransaction	IBinder protocol transaction code: interrogate the recipient side of the transaction for its canonical interface descriptor.
LastCallTransaction	The last transaction code available for user commands.
LikeTransaction	IBinder protocol transaction code: tell an app asynchronously that the caller likes it.
PingTransaction	IBinder protocol transaction code: pingBinder().
TweetTransaction	IBinder protocol transaction code: send a tweet to the target object.

Properties

Handle	Gets the JNI value of the underlying Android object. (Inherited from IJavaObject)
InterfaceDescriptor	Get the canonical name of the interface supported by this binder.
IsBinderAlive	Check to see if the process that the binder is in is still alive.
JniIdentityHashCode	Returns the value of `java.lang.System.identityHashCode()` for the wrapped instance. (Inherited from IJavaPeerable)
JniManagedPeerState	State of the managed peer. (Inherited from IJavaPeerable)
JniPeerMembers	Member access and invocation support. (Inherited from IJavaPeerable)
PeerReference	Returns a JniObjectReference of the wrapped Java object instance. (Inherited from IJavaPeerable)
SuggestedMaxIpcSizeBytes	Limit that should be placed on IPC sizes, in bytes, to keep them safely under the transaction buffer limit.

Methods

Disposed()	Called when the instance has been disposed. (Inherited from IJavaPeerable)
DisposeUnlessReferenced()	If there are no outstanding references to this instance, then calls `Dispose()`; otherwise, does nothing. (Inherited from IJavaPeerable)
Dump(FileDescriptor, String[])	Print the object's state into the given stream.
DumpAsync(FileDescriptor, String[])	Like `#dump(FileDescriptor, String[])` but always executes asynchronously.
Finalized()	Called when the instance has been finalized. (Inherited from IJavaPeerable)
LinkToDeath(IBinderDeathRecipient, Int32)	Register the recipient for a notification if this binder goes away.
PingBinder()	Check to see if the object still exists.
QueryLocalInterface(String)	Attempt to retrieve a local implementation of an interface for this Binder object.
SetJniIdentityHashCode(Int32)	Set the value returned by `JniIdentityHashCode`. (Inherited from IJavaPeerable)
SetJniManagedPeerState(JniManagedPeerStates)	(Inherited from IJavaPeerable)
SetPeerReference(JniObjectReference)	Set the value returned by `PeerReference`. (Inherited from IJavaPeerable)
Transact(Int32, Parcel, Parcel, TransactionFlags)	Perform a generic operation with the object.
UnlinkToDeath(IBinderDeathRecipient, Int32)	Remove a previously registered death notification.
UnregisterFromRuntime()	Unregister this instance so that the runtime will not return it from future Java.Interop.JniRuntime+JniValueManager.PeekValue invocations. (Inherited from IJavaPeerable)

Extension Methods

JavaCast<TResult>(IJavaObject)	Performs an Android runtime-checked type conversion.
JavaCast<TResult>(IJavaObject)
GetJniTypeName(IJavaPeerable)

Applies to

Share via