/* * Copyright (C) 2006 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.os; import java.io.FileDescriptor; /** * 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 {@link Binder}. * *

The key IBinder API is {@link #transact transact()} matched by * {@link 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 {@link #transact transact()} does not * return until the target has returned from * {@link 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 {@link 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: *

* * @see Binder */ public interface IBinder { /** * The first transaction code available for user commands. */ int FIRST_CALL_TRANSACTION = 0x00000001; /** * The last transaction code available for user commands. */ int LAST_CALL_TRANSACTION = 0x00ffffff; /** * IBinder protocol transaction code: pingBinder(). */ int PING_TRANSACTION = ('_'<<24)|('P'<<16)|('N'<<8)|'G'; /** * IBinder protocol transaction code: dump internal state. */ int DUMP_TRANSACTION = ('_'<<24)|('D'<<16)|('M'<<8)|'P'; /** * IBinder protocol transaction code: interrogate the recipient side * of the transaction for its canonical interface descriptor. */ int INTERFACE_TRANSACTION = ('_'<<24)|('N'<<16)|('T'<<8)|'F'; /** * 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 of * {@link Build.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!". */ int TWEET_TRANSACTION = ('_'<<24)|('T'<<16)|('W'<<8)|'T'; /** * 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. */ int LIKE_TRANSACTION = ('_'<<24)|('L'<<16)|('I'<<8)|'K'; /** @hide */ int SYSPROPS_TRANSACTION = ('_'<<24)|('S'<<16)|('P'<<8)|'R'; /** * Flag to {@link #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. */ int FLAG_ONEWAY = 0x00000001; /** * Limit that should be placed on IPC sizes to keep them safely under the * transaction buffer limit. * @hide */ public static final int MAX_IPC_SIZE = 64 * 1024; /** * Get the canonical name of the interface supported by this binder. */ public String getInterfaceDescriptor() throws RemoteException; /** * Check to see if the object still exists. * * @return 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 boolean pingBinder(); /** * Check to see if the process that the binder is in is still alive. * * @return false if the process is not alive. Note that if it returns * true, the process may have died while the call is returning. */ public boolean isBinderAlive(); /** * 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 IInterface queryLocalInterface(String descriptor); /** * Print the object's state into the given stream. * * @param fd The raw file descriptor that the dump is being sent to. * @param args additional arguments to the dump request. */ public void dump(FileDescriptor fd, String[] args) throws RemoteException; /** * Like {@link #dump(FileDescriptor, String[])} but always executes * asynchronously. If the object is local, a new thread is created * to perform the dump. * * @param fd The raw file descriptor that the dump is being sent to. * @param args additional arguments to the dump request. */ public void dumpAsync(FileDescriptor fd, String[] args) throws RemoteException; /** * Perform a generic operation with the object. * * @param code The action to perform. This should * be a number between {@link #FIRST_CALL_TRANSACTION} and * {@link #LAST_CALL_TRANSACTION}. * @param 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. * @param reply Marshalled data to be received from the target. May be * null if you are not interested in the return value. * @param flags Additional operation flags. Either 0 for a normal * RPC, or {@link #FLAG_ONEWAY} for a one-way RPC. */ public boolean transact(int code, Parcel data, Parcel reply, int flags) throws RemoteException; /** * Interface for receiving a callback when the process hosting an IBinder * has gone away. * * @see #linkToDeath */ public interface DeathRecipient { public void binderDied(); } /** * 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 {@link DeathRecipient}'s * {@link DeathRecipient#binderDied 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. * * @throws RemoteException if the target IBinder's * process has already died. * * @see #unlinkToDeath */ public void linkToDeath(DeathRecipient recipient, int flags) throws RemoteException; /** * Remove a previously registered death notification. * The recipient will no longer be called if this object * dies. * * @return {@code true} if the recipient is successfully * unlinked, assuring you that its * {@link DeathRecipient#binderDied DeathRecipient.binderDied()} method * will not be called; {@code false} if the target IBinder has already * died, meaning the method has been (or soon will be) called. * * @throws java.util.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. */ public boolean unlinkToDeath(DeathRecipient recipient, int flags); }