1/*
2 * Copyright (C) 2006 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.os;
18
19import java.io.FileDescriptor;
20
21/**
22 * Base interface for a remotable object, the core part of a lightweight
23 * remote procedure call mechanism designed for high performance when
24 * performing in-process and cross-process calls.  This
25 * interface describes the abstract protocol for interacting with a
26 * remotable object.  Do not implement this interface directly, instead
27 * extend from {@link Binder}.
28 *
29 * <p>The key IBinder API is {@link #transact transact()} matched by
30 * {@link Binder#onTransact Binder.onTransact()}.  These
31 * methods allow you to send a call to an IBinder object and receive a
32 * call coming in to a Binder object, respectively.  This transaction API
33 * is synchronous, such that a call to {@link #transact transact()} does not
34 * return until the target has returned from
35 * {@link Binder#onTransact Binder.onTransact()}; this is the
36 * expected behavior when calling an object that exists in the local
37 * process, and the underlying inter-process communication (IPC) mechanism
38 * ensures that these same semantics apply when going across processes.
39 *
40 * <p>The data sent through transact() is a {@link Parcel}, a generic buffer
41 * of data that also maintains some meta-data about its contents.  The meta
42 * data is used to manage IBinder object references in the buffer, so that those
43 * references can be maintained as the buffer moves across processes.  This
44 * mechanism ensures that when an IBinder is written into a Parcel and sent to
45 * another process, if that other process sends a reference to that same IBinder
46 * back to the original process, then the original process will receive the
47 * same IBinder object back.  These semantics allow IBinder/Binder objects to
48 * be used as a unique identity (to serve as a token or for other purposes)
49 * that can be managed across processes.
50 *
51 * <p>The system maintains a pool of transaction threads in each process that
52 * it runs in.  These threads are used to dispatch all
53 * IPCs coming in from other processes.  For example, when an IPC is made from
54 * process A to process B, the calling thread in A blocks in transact() as
55 * it sends the transaction to process B.  The next available pool thread in
56 * B receives the incoming transaction, calls Binder.onTransact() on the target
57 * object, and replies with the result Parcel.  Upon receiving its result, the
58 * thread in process A returns to allow its execution to continue.  In effect,
59 * other processes appear to use as additional threads that you did not create
60 * executing in your own process.
61 *
62 * <p>The Binder system also supports recursion across processes.  For example
63 * if process A performs a transaction to process B, and process B while
64 * handling that transaction calls transact() on an IBinder that is implemented
65 * in A, then the thread in A that is currently waiting for the original
66 * transaction to finish will take care of calling Binder.onTransact() on the
67 * object being called by B.  This ensures that the recursion semantics when
68 * calling remote binder object are the same as when calling local objects.
69 *
70 * <p>When working with remote objects, you often want to find out when they
71 * are no longer valid.  There are three ways this can be determined:
72 * <ul>
73 * <li> The {@link #transact transact()} method will throw a
74 * {@link RemoteException} exception if you try to call it on an IBinder
75 * whose process no longer exists.
76 * <li> The {@link #pingBinder()} method can be called, and will return false
77 * if the remote process no longer exists.
78 * <li> The {@link #linkToDeath linkToDeath()} method can be used to register
79 * a {@link DeathRecipient} with the IBinder, which will be called when its
80 * containing process goes away.
81 * </ul>
82 *
83 * @see Binder
84 */
85public interface IBinder {
86    /**
87     * The first transaction code available for user commands.
88     */
89    int FIRST_CALL_TRANSACTION  = 0x00000001;
90    /**
91     * The last transaction code available for user commands.
92     */
93    int LAST_CALL_TRANSACTION   = 0x00ffffff;
94
95    /**
96     * IBinder protocol transaction code: pingBinder().
97     */
98    int PING_TRANSACTION        = ('_'<<24)|('P'<<16)|('N'<<8)|'G';
99
100    /**
101     * IBinder protocol transaction code: dump internal state.
102     */
103    int DUMP_TRANSACTION        = ('_'<<24)|('D'<<16)|('M'<<8)|'P';
104
105    /**
106     * IBinder protocol transaction code: interrogate the recipient side
107     * of the transaction for its canonical interface descriptor.
108     */
109    int INTERFACE_TRANSACTION   = ('_'<<24)|('N'<<16)|('T'<<8)|'F';
110
111    /**
112     * IBinder protocol transaction code: send a tweet to the target
113     * object.  The data in the parcel is intended to be delivered to
114     * a shared messaging service associated with the object; it can be
115     * anything, as long as it is not more than 130 UTF-8 characters to
116     * conservatively fit within common messaging services.  As part of
117     * {@link Build.VERSION_CODES#HONEYCOMB_MR2}, all Binder objects are
118     * expected to support this protocol for fully integrated tweeting
119     * across the platform.  To support older code, the default implementation
120     * logs the tweet to the main log as a simple emulation of broadcasting
121     * it publicly over the Internet.
122     *
123     * <p>Also, upon completing the dispatch, the object must make a cup
124     * of tea, return it to the caller, and exclaim "jolly good message
125     * old boy!".
126     */
127    int TWEET_TRANSACTION   = ('_'<<24)|('T'<<16)|('W'<<8)|'T';
128
129    /**
130     * IBinder protocol transaction code: tell an app asynchronously that the
131     * caller likes it.  The app is responsible for incrementing and maintaining
132     * its own like counter, and may display this value to the user to indicate the
133     * quality of the app.  This is an optional command that applications do not
134     * need to handle, so the default implementation is to do nothing.
135     *
136     * <p>There is no response returned and nothing about the
137     * system will be functionally affected by it, but it will improve the
138     * app's self-esteem.
139     */
140    int LIKE_TRANSACTION   = ('_'<<24)|('L'<<16)|('I'<<8)|'K';
141
142    /** @hide */
143    int SYSPROPS_TRANSACTION = ('_'<<24)|('S'<<16)|('P'<<8)|'R';
144
145    /**
146     * Flag to {@link #transact}: this is a one-way call, meaning that the
147     * caller returns immediately, without waiting for a result from the
148     * callee. Applies only if the caller and callee are in different
149     * processes.
150     */
151    int FLAG_ONEWAY             = 0x00000001;
152
153    /**
154     * Get the canonical name of the interface supported by this binder.
155     */
156    public String getInterfaceDescriptor() throws RemoteException;
157
158    /**
159     * Check to see if the object still exists.
160     *
161     * @return Returns false if the
162     * hosting process is gone, otherwise the result (always by default
163     * true) returned by the pingBinder() implementation on the other
164     * side.
165     */
166    public boolean pingBinder();
167
168    /**
169     * Check to see if the process that the binder is in is still alive.
170     *
171     * @return false if the process is not alive.  Note that if it returns
172     * true, the process may have died while the call is returning.
173     */
174    public boolean isBinderAlive();
175
176    /**
177     * Attempt to retrieve a local implementation of an interface
178     * for this Binder object.  If null is returned, you will need
179     * to instantiate a proxy class to marshall calls through
180     * the transact() method.
181     */
182    public IInterface queryLocalInterface(String descriptor);
183
184    /**
185     * Print the object's state into the given stream.
186     *
187     * @param fd The raw file descriptor that the dump is being sent to.
188     * @param args additional arguments to the dump request.
189     */
190    public void dump(FileDescriptor fd, String[] args) throws RemoteException;
191
192    /**
193     * Like {@link #dump(FileDescriptor, String[])} but always executes
194     * asynchronously.  If the object is local, a new thread is created
195     * to perform the dump.
196     *
197     * @param fd The raw file descriptor that the dump is being sent to.
198     * @param args additional arguments to the dump request.
199     */
200    public void dumpAsync(FileDescriptor fd, String[] args) throws RemoteException;
201
202    /**
203     * Perform a generic operation with the object.
204     *
205     * @param code The action to perform.  This should
206     * be a number between {@link #FIRST_CALL_TRANSACTION} and
207     * {@link #LAST_CALL_TRANSACTION}.
208     * @param data Marshalled data to send to the target.  Must not be null.
209     * If you are not sending any data, you must create an empty Parcel
210     * that is given here.
211     * @param reply Marshalled data to be received from the target.  May be
212     * null if you are not interested in the return value.
213     * @param flags Additional operation flags.  Either 0 for a normal
214     * RPC, or {@link #FLAG_ONEWAY} for a one-way RPC.
215     */
216    public boolean transact(int code, Parcel data, Parcel reply, int flags)
217        throws RemoteException;
218
219    /**
220     * Interface for receiving a callback when the process hosting an IBinder
221     * has gone away.
222     *
223     * @see #linkToDeath
224     */
225    public interface DeathRecipient {
226        public void binderDied();
227    }
228
229    /**
230     * Register the recipient for a notification if this binder
231     * goes away.  If this binder object unexpectedly goes away
232     * (typically because its hosting process has been killed),
233     * then the given {@link DeathRecipient}'s
234     * {@link DeathRecipient#binderDied DeathRecipient.binderDied()} method
235     * will be called.
236     *
237     * <p>You will only receive death notifications for remote binders,
238     * as local binders by definition can't die without you dying as well.
239     *
240     * @throws RemoteException if the target IBinder's
241     * process has already died.
242     *
243     * @see #unlinkToDeath
244     */
245    public void linkToDeath(DeathRecipient recipient, int flags)
246            throws RemoteException;
247
248    /**
249     * Remove a previously registered death notification.
250     * The recipient will no longer be called if this object
251     * dies.
252     *
253     * @return {@code true} if the <var>recipient</var> is successfully
254     * unlinked, assuring you that its
255     * {@link DeathRecipient#binderDied DeathRecipient.binderDied()} method
256     * will not be called;  {@code false} if the target IBinder has already
257     * died, meaning the method has been (or soon will be) called.
258     *
259     * @throws java.util.NoSuchElementException if the given
260     * <var>recipient</var> has not been registered with the IBinder, and
261     * the IBinder is still alive.  Note that if the <var>recipient</var>
262     * was never registered, but the IBinder has already died, then this
263     * exception will <em>not</em> be thrown, and you will receive a false
264     * return value instead.
265     */
266    public boolean unlinkToDeath(DeathRecipient recipient, int flags);
267}
268