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