2 * Copyright (C) 2006 The Android Open Source Project
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 import android.util.Log;
20 import android.util.Slog;
21 import com.android.internal.util.FastPrintWriter;
23 import java.io.FileDescriptor;
24 import java.io.FileOutputStream;
25 import java.io.IOException;
26 import java.io.PrintWriter;
27 import java.lang.ref.WeakReference;
28 import java.lang.reflect.Modifier;
31 * Base class for a remotable object, the core part of a lightweight
32 * remote procedure call mechanism defined by {@link IBinder}.
33 * This class is an implementation of IBinder that provides
34 * standard local implementation of such an object.
36 * <p>Most developers will not implement this class directly, instead using the
37 * <a href="{@docRoot}guide/components/aidl.html">aidl</a> tool to describe the desired
38 * interface, having it generate the appropriate Binder subclass. You can,
39 * however, derive directly from Binder to implement your own custom RPC
40 * protocol or simply instantiate a raw Binder object directly to use as a
41 * token that can be shared across processes.
43 * <p>This class is just a basic IPC primitive; it has no impact on an application's
44 * lifecycle, and is valid only as long as the process that created it continues to run.
45 * To use this correctly, you must be doing so within the context of a top-level
46 * application component (a {@link android.app.Service}, {@link android.app.Activity},
47 * or {@link android.content.ContentProvider}) that lets the system know your process
48 * should remain running.</p>
50 * <p>You must keep in mind the situations in which your process
51 * could go away, and thus require that you later re-create a new Binder and re-attach
52 * it when the process starts again. For example, if you are using this within an
53 * {@link android.app.Activity}, your activity's process may be killed any time the
54 * activity is not started; if the activity is later re-created you will need to
55 * create a new Binder and hand it back to the correct place again; you need to be
56 * aware that your process may be started for another reason (for example to receive
57 * a broadcast) that will not involve re-creating the activity and thus run its code
58 * to create a new Binder.</p>
62 public class Binder implements IBinder {
64 * Set this flag to true to detect anonymous, local or member classes
65 * that extend this Binder class and that are not static. These kind
66 * of classes can potentially create leaks.
68 private static final boolean FIND_POTENTIAL_LEAKS = false;
69 private static final boolean CHECK_PARCEL_SIZE = false;
70 static final String TAG = "Binder";
73 * Control whether dump() calls are allowed.
75 private static String sDumpDisabled = null;
77 /* mObject is used by native code, do not remove or rename */
79 private IInterface mOwner;
80 private String mDescriptor;
83 * Return the ID of the process that sent you the current transaction
84 * that is being processed. This pid can be used with higher-level
85 * system services to determine its identity and check permissions.
86 * If the current thread is not currently executing an incoming transaction,
87 * then its own pid is returned.
89 public static final native int getCallingPid();
92 * Return the Linux uid assigned to the process that sent you the
93 * current transaction that is being processed. This uid can be used with
94 * higher-level system services to determine its identity and check
95 * permissions. If the current thread is not currently executing an
96 * incoming transaction, then its own uid is returned.
98 public static final native int getCallingUid();
101 * Return the UserHandle assigned to the process that sent you the
102 * current transaction that is being processed. This is the user
103 * of the caller. It is distinct from {@link #getCallingUid()} in that a
104 * particular user will have multiple distinct apps running under it each
105 * with their own uid. If the current thread is not currently executing an
106 * incoming transaction, then its own UserHandle is returned.
108 public static final UserHandle getCallingUserHandle() {
109 return new UserHandle(UserHandle.getUserId(getCallingUid()));
113 * Reset the identity of the incoming IPC on the current thread. This can
114 * be useful if, while handling an incoming call, you will be calling
115 * on interfaces of other objects that may be local to your process and
116 * need to do permission checks on the calls coming into them (so they
117 * will check the permission of your own local process, and not whatever
118 * process originally called you).
120 * @return Returns an opaque token that can be used to restore the
121 * original calling identity by passing it to
122 * {@link #restoreCallingIdentity(long)}.
124 * @see #getCallingPid()
125 * @see #getCallingUid()
126 * @see #restoreCallingIdentity(long)
128 public static final native long clearCallingIdentity();
131 * Restore the identity of the incoming IPC on the current thread
132 * back to a previously identity that was returned by {@link
133 * #clearCallingIdentity}.
135 * @param token The opaque token that was previously returned by
136 * {@link #clearCallingIdentity}.
138 * @see #clearCallingIdentity
140 public static final native void restoreCallingIdentity(long token);
143 * Sets the native thread-local StrictMode policy mask.
145 * <p>The StrictMode settings are kept in two places: a Java-level
146 * threadlocal for libcore/Dalvik, and a native threadlocal (set
147 * here) for propagation via Binder calls. This is a little
148 * unfortunate, but necessary to break otherwise more unfortunate
149 * dependencies either of Dalvik on Android, or Android
150 * native-only code on Dalvik.
155 public static final native void setThreadStrictModePolicy(int policyMask);
158 * Gets the current native thread-local StrictMode policy mask.
160 * @see #setThreadStrictModePolicy
163 public static final native int getThreadStrictModePolicy();
166 * Flush any Binder commands pending in the current thread to the kernel
167 * driver. This can be
168 * useful to call before performing an operation that may block for a long
169 * time, to ensure that any pending object references have been released
170 * in order to prevent the process from holding on to objects longer than
173 public static final native void flushPendingCommands();
176 * Add the calling thread to the IPC thread pool. This function does
177 * not return until the current process is exiting.
179 public static final native void joinThreadPool();
182 * Returns true if the specified interface is a proxy.
185 public static final boolean isProxy(IInterface iface) {
186 return iface.asBinder() != iface;
190 * Call blocks until the number of executing binder threads is less
191 * than the maximum number of binder threads allowed for this process.
194 public static final native void blockUntilThreadAvailable();
197 * Default constructor initializes the object.
202 if (FIND_POTENTIAL_LEAKS) {
203 final Class<? extends Binder> klass = getClass();
204 if ((klass.isAnonymousClass() || klass.isMemberClass() || klass.isLocalClass()) &&
205 (klass.getModifiers() & Modifier.STATIC) == 0) {
206 Log.w(TAG, "The following Binder class should be static or leaks might occur: " +
207 klass.getCanonicalName());
213 * Convenience method for associating a specific interface with the Binder.
214 * After calling, queryLocalInterface() will be implemented for you
215 * to return the given owner IInterface when the corresponding
216 * descriptor is requested.
218 public void attachInterface(IInterface owner, String descriptor) {
220 mDescriptor = descriptor;
224 * Default implementation returns an empty interface name.
226 public String getInterfaceDescriptor() {
231 * Default implementation always returns true -- if you got here,
232 * the object is alive.
234 public boolean pingBinder() {
241 * Note that if you're calling on a local binder, this always returns true
242 * because your process is alive if you're calling it.
244 public boolean isBinderAlive() {
249 * Use information supplied to attachInterface() to return the
250 * associated IInterface if it matches the requested
253 public IInterface queryLocalInterface(String descriptor) {
254 if (mDescriptor.equals(descriptor)) {
261 * Control disabling of dump calls in this process. This is used by the system
262 * process watchdog to disable incoming dump calls while it has detecting the system
263 * is hung and is reporting that back to the activity controller. This is to
264 * prevent the controller from getting hung up on bug reports at this point.
267 * @param msg The message to show instead of the dump; if null, dumps are
270 public static void setDumpDisabled(String msg) {
271 synchronized (Binder.class) {
277 * Default implementation is a stub that returns false. You will want
278 * to override this to do the appropriate unmarshalling of transactions.
280 * <p>If you want to call this, call transact().
282 protected boolean onTransact(int code, Parcel data, Parcel reply,
283 int flags) throws RemoteException {
284 if (code == INTERFACE_TRANSACTION) {
285 reply.writeString(getInterfaceDescriptor());
287 } else if (code == DUMP_TRANSACTION) {
288 ParcelFileDescriptor fd = data.readFileDescriptor();
289 String[] args = data.readStringArray();
292 dump(fd.getFileDescriptor(), args);
296 } catch (IOException e) {
297 // swallowed, not propagated back to the caller
301 // Write the StrictMode header.
303 reply.writeNoException();
305 StrictMode.clearGatheredViolations();
313 * Implemented to call the more convenient version
314 * {@link #dump(FileDescriptor, PrintWriter, String[])}.
316 public void dump(FileDescriptor fd, String[] args) {
317 FileOutputStream fout = new FileOutputStream(fd);
318 PrintWriter pw = new FastPrintWriter(fout);
320 final String disabled;
321 synchronized (Binder.class) {
322 disabled = sDumpDisabled;
324 if (disabled == null) {
327 } catch (SecurityException e) {
328 pw.println("Security exception: " + e.getMessage());
330 } catch (Throwable e) {
331 // Unlike usual calls, in this case if an exception gets thrown
332 // back to us we want to print it back in to the dump data, since
333 // that is where the caller expects all interesting information to
336 pw.println("Exception occurred while dumping:");
337 e.printStackTrace(pw);
340 pw.println(sDumpDisabled);
348 * Like {@link #dump(FileDescriptor, String[])}, but ensures the target
349 * executes asynchronously.
351 public void dumpAsync(final FileDescriptor fd, final String[] args) {
352 final FileOutputStream fout = new FileOutputStream(fd);
353 final PrintWriter pw = new FastPrintWriter(fout);
354 Thread thr = new Thread("Binder.dumpAsync") {
367 * Print the object's state into the given stream.
369 * @param fd The raw file descriptor that the dump is being sent to.
370 * @param fout The file to which you should dump your state. This will be
371 * closed for you after you return.
372 * @param args additional arguments to the dump request.
374 protected void dump(FileDescriptor fd, PrintWriter fout, String[] args) {
378 * Default implementation rewinds the parcels and calls onTransact. On
379 * the remote side, transact calls into the binder to do the IPC.
381 public final boolean transact(int code, Parcel data, Parcel reply,
382 int flags) throws RemoteException {
383 if (false) Log.v("Binder", "Transact: " + code + " to " + this);
385 data.setDataPosition(0);
387 boolean r = onTransact(code, data, reply, flags);
389 reply.setDataPosition(0);
395 * Local implementation is a no-op.
397 public void linkToDeath(DeathRecipient recipient, int flags) {
401 * Local implementation is a no-op.
403 public boolean unlinkToDeath(DeathRecipient recipient, int flags) {
407 protected void finalize() throws Throwable {
415 static void checkParcel(IBinder obj, int code, Parcel parcel, String msg) {
416 if (CHECK_PARCEL_SIZE && parcel.dataSize() >= 800*1024) {
417 // Trying to send > 800k, this is way too much
418 StringBuilder sb = new StringBuilder();
422 sb.append(" calling ");
425 sb.append(parcel.dataSize());
426 sb.append(" (data: ");
427 parcel.setDataPosition(0);
428 sb.append(parcel.readInt());
430 sb.append(parcel.readInt());
432 sb.append(parcel.readInt());
434 Slog.wtfStack(TAG, sb.toString());
438 private native final void init();
439 private native final void destroy();
441 // Entry point from android_util_Binder.cpp's onTransact
442 private boolean execTransact(int code, long dataObj, long replyObj,
444 Parcel data = Parcel.obtain(dataObj);
445 Parcel reply = Parcel.obtain(replyObj);
446 // theoretically, we should call transact, which will call onTransact,
447 // but all that does is rewind it, and we just got these from an IPC,
448 // so we'll just call it directly.
450 // Log any exceptions as warnings, don't silently suppress them.
451 // If the call was FLAG_ONEWAY then these exceptions disappear into the ether.
453 res = onTransact(code, data, reply, flags);
454 } catch (RemoteException e) {
455 if ((flags & FLAG_ONEWAY) != 0) {
456 Log.w(TAG, "Binder call failed.", e);
458 reply.setDataPosition(0);
459 reply.writeException(e);
462 } catch (RuntimeException e) {
463 if ((flags & FLAG_ONEWAY) != 0) {
464 Log.w(TAG, "Caught a RuntimeException from the binder stub implementation.", e);
466 reply.setDataPosition(0);
467 reply.writeException(e);
470 } catch (OutOfMemoryError e) {
471 // Unconditionally log this, since this is generally unrecoverable.
472 Log.e(TAG, "Caught an OutOfMemoryError from the binder stub implementation.", e);
473 RuntimeException re = new RuntimeException("Out of memory", e);
474 reply.setDataPosition(0);
475 reply.writeException(re);
478 checkParcel(this, code, reply, "Unreasonably large binder reply buffer");
482 // Just in case -- we are done with the IPC, so there should be no more strict
483 // mode violations that have gathered for this thread. Either they have been
484 // parceled and are now in transport off to the caller, or we are returning back
485 // to the main transaction loop to wait for another incoming transaction. Either
486 // way, strict mode begone!
487 StrictMode.clearGatheredViolations();
493 final class BinderProxy implements IBinder {
494 public native boolean pingBinder();
495 public native boolean isBinderAlive();
497 public IInterface queryLocalInterface(String descriptor) {
501 public boolean transact(int code, Parcel data, Parcel reply, int flags) throws RemoteException {
502 Binder.checkParcel(this, code, data, "Unreasonably large binder buffer");
503 return transactNative(code, data, reply, flags);
506 public native String getInterfaceDescriptor() throws RemoteException;
507 public native boolean transactNative(int code, Parcel data, Parcel reply,
508 int flags) throws RemoteException;
509 public native void linkToDeath(DeathRecipient recipient, int flags)
510 throws RemoteException;
511 public native boolean unlinkToDeath(DeathRecipient recipient, int flags);
513 public void dump(FileDescriptor fd, String[] args) throws RemoteException {
514 Parcel data = Parcel.obtain();
515 Parcel reply = Parcel.obtain();
516 data.writeFileDescriptor(fd);
517 data.writeStringArray(args);
519 transact(DUMP_TRANSACTION, data, reply, 0);
520 reply.readException();
527 public void dumpAsync(FileDescriptor fd, String[] args) throws RemoteException {
528 Parcel data = Parcel.obtain();
529 Parcel reply = Parcel.obtain();
530 data.writeFileDescriptor(fd);
531 data.writeStringArray(args);
533 transact(DUMP_TRANSACTION, data, reply, FLAG_ONEWAY);
541 mSelf = new WeakReference(this);
545 protected void finalize() throws Throwable {
553 private native final void destroy();
555 private static final void sendDeathNotice(DeathRecipient recipient) {
556 if (false) Log.v("JavaBinder", "sendDeathNotice to " + recipient);
558 recipient.binderDied();
560 catch (RuntimeException exc) {
561 Log.w("BinderNative", "Uncaught exception from death notification",
566 final private WeakReference mSelf;
567 private long mObject;