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;
22 import libcore.io.IoUtils;
24 import java.io.FileDescriptor;
25 import java.io.FileOutputStream;
26 import java.io.IOException;
27 import java.io.PrintWriter;
28 import java.lang.ref.WeakReference;
29 import java.lang.reflect.Modifier;
32 * Base class for a remotable object, the core part of a lightweight
33 * remote procedure call mechanism defined by {@link IBinder}.
34 * This class is an implementation of IBinder that provides
35 * standard local implementation of such an object.
37 * <p>Most developers will not implement this class directly, instead using the
38 * <a href="{@docRoot}guide/components/aidl.html">aidl</a> tool to describe the desired
39 * interface, having it generate the appropriate Binder subclass. You can,
40 * however, derive directly from Binder to implement your own custom RPC
41 * protocol or simply instantiate a raw Binder object directly to use as a
42 * token that can be shared across processes.
44 * <p>This class is just a basic IPC primitive; it has no impact on an application's
45 * lifecycle, and is valid only as long as the process that created it continues to run.
46 * To use this correctly, you must be doing so within the context of a top-level
47 * application component (a {@link android.app.Service}, {@link android.app.Activity},
48 * or {@link android.content.ContentProvider}) that lets the system know your process
49 * should remain running.</p>
51 * <p>You must keep in mind the situations in which your process
52 * could go away, and thus require that you later re-create a new Binder and re-attach
53 * it when the process starts again. For example, if you are using this within an
54 * {@link android.app.Activity}, your activity's process may be killed any time the
55 * activity is not started; if the activity is later re-created you will need to
56 * create a new Binder and hand it back to the correct place again; you need to be
57 * aware that your process may be started for another reason (for example to receive
58 * a broadcast) that will not involve re-creating the activity and thus run its code
59 * to create a new Binder.</p>
63 public class Binder implements IBinder {
65 * Set this flag to true to detect anonymous, local or member classes
66 * that extend this Binder class and that are not static. These kind
67 * of classes can potentially create leaks.
69 private static final boolean FIND_POTENTIAL_LEAKS = false;
70 private static final boolean CHECK_PARCEL_SIZE = false;
71 static final String TAG = "Binder";
74 public static boolean LOG_RUNTIME_EXCEPTION = false; // DO NOT SUBMIT WITH TRUE
77 * Control whether dump() calls are allowed.
79 private static String sDumpDisabled = null;
82 * Global transaction tracker instance for this process.
84 private static TransactionTracker sTransactionTracker = null;
86 // Transaction tracking code.
89 * Flag indicating whether we should be tracing transact calls.
92 private static boolean sTracingEnabled = false;
95 * Enable Binder IPC tracing.
99 public static void enableTracing() {
100 sTracingEnabled = true;
104 * Disable Binder IPC tracing.
108 public static void disableTracing() {
109 sTracingEnabled = false;
113 * Check if binder transaction tracing is enabled.
117 public static boolean isTracingEnabled() {
118 return sTracingEnabled;
122 * Get the binder transaction tracker for this process.
126 public synchronized static TransactionTracker getTransactionTracker() {
127 if (sTransactionTracker == null)
128 sTransactionTracker = new TransactionTracker();
129 return sTransactionTracker;
132 /* mObject is used by native code, do not remove or rename */
133 private long mObject;
134 private IInterface mOwner;
135 private String mDescriptor;
138 * Return the ID of the process that sent you the current transaction
139 * that is being processed. This pid can be used with higher-level
140 * system services to determine its identity and check permissions.
141 * If the current thread is not currently executing an incoming transaction,
142 * then its own pid is returned.
144 public static final native int getCallingPid();
147 * Return the Linux uid assigned to the process that sent you the
148 * current transaction that is being processed. This uid can be used with
149 * higher-level system services to determine its identity and check
150 * permissions. If the current thread is not currently executing an
151 * incoming transaction, then its own uid is returned.
153 public static final native int getCallingUid();
156 * Return the UserHandle assigned to the process that sent you the
157 * current transaction that is being processed. This is the user
158 * of the caller. It is distinct from {@link #getCallingUid()} in that a
159 * particular user will have multiple distinct apps running under it each
160 * with their own uid. If the current thread is not currently executing an
161 * incoming transaction, then its own UserHandle is returned.
163 public static final UserHandle getCallingUserHandle() {
164 return UserHandle.of(UserHandle.getUserId(getCallingUid()));
168 * Reset the identity of the incoming IPC on the current thread. This can
169 * be useful if, while handling an incoming call, you will be calling
170 * on interfaces of other objects that may be local to your process and
171 * need to do permission checks on the calls coming into them (so they
172 * will check the permission of your own local process, and not whatever
173 * process originally called you).
175 * @return Returns an opaque token that can be used to restore the
176 * original calling identity by passing it to
177 * {@link #restoreCallingIdentity(long)}.
179 * @see #getCallingPid()
180 * @see #getCallingUid()
181 * @see #restoreCallingIdentity(long)
183 public static final native long clearCallingIdentity();
186 * Restore the identity of the incoming IPC on the current thread
187 * back to a previously identity that was returned by {@link
188 * #clearCallingIdentity}.
190 * @param token The opaque token that was previously returned by
191 * {@link #clearCallingIdentity}.
193 * @see #clearCallingIdentity
195 public static final native void restoreCallingIdentity(long token);
198 * Sets the native thread-local StrictMode policy mask.
200 * <p>The StrictMode settings are kept in two places: a Java-level
201 * threadlocal for libcore/Dalvik, and a native threadlocal (set
202 * here) for propagation via Binder calls. This is a little
203 * unfortunate, but necessary to break otherwise more unfortunate
204 * dependencies either of Dalvik on Android, or Android
205 * native-only code on Dalvik.
210 public static final native void setThreadStrictModePolicy(int policyMask);
213 * Gets the current native thread-local StrictMode policy mask.
215 * @see #setThreadStrictModePolicy
218 public static final native int getThreadStrictModePolicy();
221 * Flush any Binder commands pending in the current thread to the kernel
222 * driver. This can be
223 * useful to call before performing an operation that may block for a long
224 * time, to ensure that any pending object references have been released
225 * in order to prevent the process from holding on to objects longer than
228 public static final native void flushPendingCommands();
231 * Add the calling thread to the IPC thread pool. This function does
232 * not return until the current process is exiting.
234 public static final native void joinThreadPool();
237 * Returns true if the specified interface is a proxy.
240 public static final boolean isProxy(IInterface iface) {
241 return iface.asBinder() != iface;
245 * Call blocks until the number of executing binder threads is less
246 * than the maximum number of binder threads allowed for this process.
249 public static final native void blockUntilThreadAvailable();
252 * Default constructor initializes the object.
257 if (FIND_POTENTIAL_LEAKS) {
258 final Class<? extends Binder> klass = getClass();
259 if ((klass.isAnonymousClass() || klass.isMemberClass() || klass.isLocalClass()) &&
260 (klass.getModifiers() & Modifier.STATIC) == 0) {
261 Log.w(TAG, "The following Binder class should be static or leaks might occur: " +
262 klass.getCanonicalName());
268 * Convenience method for associating a specific interface with the Binder.
269 * After calling, queryLocalInterface() will be implemented for you
270 * to return the given owner IInterface when the corresponding
271 * descriptor is requested.
273 public void attachInterface(IInterface owner, String descriptor) {
275 mDescriptor = descriptor;
279 * Default implementation returns an empty interface name.
281 public String getInterfaceDescriptor() {
286 * Default implementation always returns true -- if you got here,
287 * the object is alive.
289 public boolean pingBinder() {
296 * Note that if you're calling on a local binder, this always returns true
297 * because your process is alive if you're calling it.
299 public boolean isBinderAlive() {
304 * Use information supplied to attachInterface() to return the
305 * associated IInterface if it matches the requested
308 public IInterface queryLocalInterface(String descriptor) {
309 if (mDescriptor.equals(descriptor)) {
316 * Control disabling of dump calls in this process. This is used by the system
317 * process watchdog to disable incoming dump calls while it has detecting the system
318 * is hung and is reporting that back to the activity controller. This is to
319 * prevent the controller from getting hung up on bug reports at this point.
322 * @param msg The message to show instead of the dump; if null, dumps are
325 public static void setDumpDisabled(String msg) {
326 synchronized (Binder.class) {
332 * Default implementation is a stub that returns false. You will want
333 * to override this to do the appropriate unmarshalling of transactions.
335 * <p>If you want to call this, call transact().
337 protected boolean onTransact(int code, Parcel data, Parcel reply,
338 int flags) throws RemoteException {
339 if (code == INTERFACE_TRANSACTION) {
340 reply.writeString(getInterfaceDescriptor());
342 } else if (code == DUMP_TRANSACTION) {
343 ParcelFileDescriptor fd = data.readFileDescriptor();
344 String[] args = data.readStringArray();
347 dump(fd.getFileDescriptor(), args);
349 IoUtils.closeQuietly(fd);
352 // Write the StrictMode header.
354 reply.writeNoException();
356 StrictMode.clearGatheredViolations();
359 } else if (code == SHELL_COMMAND_TRANSACTION) {
360 ParcelFileDescriptor in = data.readFileDescriptor();
361 ParcelFileDescriptor out = data.readFileDescriptor();
362 ParcelFileDescriptor err = data.readFileDescriptor();
363 String[] args = data.readStringArray();
364 ResultReceiver resultReceiver = ResultReceiver.CREATOR.createFromParcel(data);
367 shellCommand(in != null ? in.getFileDescriptor() : null,
368 out.getFileDescriptor(),
369 err != null ? err.getFileDescriptor() : out.getFileDescriptor(),
370 args, resultReceiver);
373 IoUtils.closeQuietly(in);
374 IoUtils.closeQuietly(out);
375 IoUtils.closeQuietly(err);
376 // Write the StrictMode header.
378 reply.writeNoException();
380 StrictMode.clearGatheredViolations();
389 * Implemented to call the more convenient version
390 * {@link #dump(FileDescriptor, PrintWriter, String[])}.
392 public void dump(FileDescriptor fd, String[] args) {
393 FileOutputStream fout = new FileOutputStream(fd);
394 PrintWriter pw = new FastPrintWriter(fout);
396 doDump(fd, pw, args);
402 void doDump(FileDescriptor fd, PrintWriter pw, String[] args) {
403 final String disabled;
404 synchronized (Binder.class) {
405 disabled = sDumpDisabled;
407 if (disabled == null) {
410 } catch (SecurityException e) {
411 pw.println("Security exception: " + e.getMessage());
413 } catch (Throwable e) {
414 // Unlike usual calls, in this case if an exception gets thrown
415 // back to us we want to print it back in to the dump data, since
416 // that is where the caller expects all interesting information to
419 pw.println("Exception occurred while dumping:");
420 e.printStackTrace(pw);
423 pw.println(sDumpDisabled);
428 * Like {@link #dump(FileDescriptor, String[])}, but ensures the target
429 * executes asynchronously.
431 public void dumpAsync(final FileDescriptor fd, final String[] args) {
432 final FileOutputStream fout = new FileOutputStream(fd);
433 final PrintWriter pw = new FastPrintWriter(fout);
434 Thread thr = new Thread("Binder.dumpAsync") {
447 * Print the object's state into the given stream.
449 * @param fd The raw file descriptor that the dump is being sent to.
450 * @param fout The file to which you should dump your state. This will be
451 * closed for you after you return.
452 * @param args additional arguments to the dump request.
454 protected void dump(FileDescriptor fd, PrintWriter fout, String[] args) {
458 * @param in The raw file descriptor that an input data stream can be read from.
459 * @param out The raw file descriptor that normal command messages should be written to.
460 * @param err The raw file descriptor that command error messages should be written to.
461 * @param args Command-line arguments.
462 * @param resultReceiver Called when the command has finished executing, with the result code.
463 * @throws RemoteException
466 public void shellCommand(FileDescriptor in, FileDescriptor out, FileDescriptor err,
467 String[] args, ResultReceiver resultReceiver) throws RemoteException {
468 onShellCommand(in, out, err, args, resultReceiver);
472 * Handle a call to {@link #shellCommand}. The default implementation simply prints
473 * an error message. Override and replace with your own.
474 * <p class="caution">Note: no permission checking is done before calling this method; you must
475 * apply any security checks as appropriate for the command being executed.
476 * Consider using {@link ShellCommand} to help in the implementation.</p>
479 public void onShellCommand(FileDescriptor in, FileDescriptor out, FileDescriptor err,
480 String[] args, ResultReceiver resultReceiver) throws RemoteException {
481 FileOutputStream fout = new FileOutputStream(err != null ? err : out);
482 PrintWriter pw = new FastPrintWriter(fout);
483 pw.println("No shell command implementation.");
485 resultReceiver.send(0, null);
489 * Default implementation rewinds the parcels and calls onTransact. On
490 * the remote side, transact calls into the binder to do the IPC.
492 public final boolean transact(int code, Parcel data, Parcel reply,
493 int flags) throws RemoteException {
494 if (false) Log.v("Binder", "Transact: " + code + " to " + this);
497 data.setDataPosition(0);
499 boolean r = onTransact(code, data, reply, flags);
501 reply.setDataPosition(0);
507 * Local implementation is a no-op.
509 public void linkToDeath(DeathRecipient recipient, int flags) {
513 * Local implementation is a no-op.
515 public boolean unlinkToDeath(DeathRecipient recipient, int flags) {
519 protected void finalize() throws Throwable {
527 static void checkParcel(IBinder obj, int code, Parcel parcel, String msg) {
528 if (CHECK_PARCEL_SIZE && parcel.dataSize() >= 800*1024) {
529 // Trying to send > 800k, this is way too much
530 StringBuilder sb = new StringBuilder();
534 sb.append(" calling ");
537 sb.append(parcel.dataSize());
538 sb.append(" (data: ");
539 parcel.setDataPosition(0);
540 sb.append(parcel.readInt());
542 sb.append(parcel.readInt());
544 sb.append(parcel.readInt());
546 Slog.wtfStack(TAG, sb.toString());
550 private native final void init();
551 private native final void destroy();
553 // Entry point from android_util_Binder.cpp's onTransact
554 private boolean execTransact(int code, long dataObj, long replyObj,
556 Parcel data = Parcel.obtain(dataObj);
557 Parcel reply = Parcel.obtain(replyObj);
558 // theoretically, we should call transact, which will call onTransact,
559 // but all that does is rewind it, and we just got these from an IPC,
560 // so we'll just call it directly.
562 // Log any exceptions as warnings, don't silently suppress them.
563 // If the call was FLAG_ONEWAY then these exceptions disappear into the ether.
565 res = onTransact(code, data, reply, flags);
566 } catch (RemoteException|RuntimeException e) {
567 if (LOG_RUNTIME_EXCEPTION) {
568 Log.w(TAG, "Caught a RuntimeException from the binder stub implementation.", e);
570 if ((flags & FLAG_ONEWAY) != 0) {
571 if (e instanceof RemoteException) {
572 Log.w(TAG, "Binder call failed.", e);
574 Log.w(TAG, "Caught a RuntimeException from the binder stub implementation.", e);
577 reply.setDataPosition(0);
578 reply.writeException(e);
581 } catch (OutOfMemoryError e) {
582 // Unconditionally log this, since this is generally unrecoverable.
583 Log.e(TAG, "Caught an OutOfMemoryError from the binder stub implementation.", e);
584 RuntimeException re = new RuntimeException("Out of memory", e);
585 reply.setDataPosition(0);
586 reply.writeException(re);
589 checkParcel(this, code, reply, "Unreasonably large binder reply buffer");
593 // Just in case -- we are done with the IPC, so there should be no more strict
594 // mode violations that have gathered for this thread. Either they have been
595 // parceled and are now in transport off to the caller, or we are returning back
596 // to the main transaction loop to wait for another incoming transaction. Either
597 // way, strict mode begone!
598 StrictMode.clearGatheredViolations();
604 final class BinderProxy implements IBinder {
605 public native boolean pingBinder();
606 public native boolean isBinderAlive();
608 public IInterface queryLocalInterface(String descriptor) {
612 public boolean transact(int code, Parcel data, Parcel reply, int flags) throws RemoteException {
613 Binder.checkParcel(this, code, data, "Unreasonably large binder buffer");
614 if (Binder.isTracingEnabled()) { Binder.getTransactionTracker().addTrace(); }
615 return transactNative(code, data, reply, flags);
618 public native String getInterfaceDescriptor() throws RemoteException;
619 public native boolean transactNative(int code, Parcel data, Parcel reply,
620 int flags) throws RemoteException;
621 public native void linkToDeath(DeathRecipient recipient, int flags)
622 throws RemoteException;
623 public native boolean unlinkToDeath(DeathRecipient recipient, int flags);
625 public void dump(FileDescriptor fd, String[] args) throws RemoteException {
626 Parcel data = Parcel.obtain();
627 Parcel reply = Parcel.obtain();
628 data.writeFileDescriptor(fd);
629 data.writeStringArray(args);
631 transact(DUMP_TRANSACTION, data, reply, 0);
632 reply.readException();
639 public void dumpAsync(FileDescriptor fd, String[] args) throws RemoteException {
640 Parcel data = Parcel.obtain();
641 Parcel reply = Parcel.obtain();
642 data.writeFileDescriptor(fd);
643 data.writeStringArray(args);
645 transact(DUMP_TRANSACTION, data, reply, FLAG_ONEWAY);
652 public void shellCommand(FileDescriptor in, FileDescriptor out, FileDescriptor err,
653 String[] args, ResultReceiver resultReceiver) throws RemoteException {
654 Parcel data = Parcel.obtain();
655 Parcel reply = Parcel.obtain();
656 data.writeFileDescriptor(in);
657 data.writeFileDescriptor(out);
658 data.writeFileDescriptor(err);
659 data.writeStringArray(args);
660 resultReceiver.writeToParcel(data, 0);
662 transact(SHELL_COMMAND_TRANSACTION, data, reply, 0);
663 reply.readException();
671 mSelf = new WeakReference(this);
675 protected void finalize() throws Throwable {
683 private native final void destroy();
685 private static final void sendDeathNotice(DeathRecipient recipient) {
686 if (false) Log.v("JavaBinder", "sendDeathNotice to " + recipient);
688 recipient.binderDied();
690 catch (RuntimeException exc) {
691 Log.w("BinderNative", "Uncaught exception from death notification",
696 final private WeakReference mSelf;
697 private long mObject;