Merge "Binder: correction of javadoc formatting" am: a83307fb am: 0784bb43

 * To use this correctly, you must be doing so within the context of a top-level

 * application component (a {@link android.app.Service}, {@link android.app.Activity},

 * or {@link android.content.ContentProvider}) that lets the system know your process

 * should remain running.</p>

 * should remain running.

 *

 * <p>You must keep in mind the situations in which your process

 * could go away, and thus require that you later re-create a new Binder and re-attach

 * create a new Binder and hand it back to the correct place again; you need to be

 * aware that your process may be started for another reason (for example to receive

 * a broadcast) that will not involve re-creating the activity and thus run its code

 * to create a new Binder.</p>

 * to create a new Binder.

 *

 * @see IBinder

 */

    /**

     * Value to represents that a calling work source is not set.

     *

     * This constatnt needs to be kept in sync with IPCThreadState::kUnsetWorkSource.

     * <p>This constant needs to be kept in sync with IPCThreadState::kUnsetWorkSource.

     *

     * @hide

     */

    public static final int UNSET_WORKSOURCE = -1;

    /**

     * Control whether dump() calls are allowed.

     * Control whether {@link #dump(FileDescriptor, PrintWriter, String[]) dump()}

     * calls are allowed.

     */

    private static volatile String sDumpDisabled = null;

        sObserver = observer;

    }

    /** {@hide} */

    /** @hide */

    static volatile boolean sWarnOnBlocking = false;

    /**

    /**

     * Allow blocking calls on the given interface, overriding the requested

     * value of {@link #setWarnOnBlocking(boolean)}.

     * <p>

     * This should only be rarely called when you are <em>absolutely sure</em>

     *

     * <p>This should only be rarely called when you are <em>absolutely sure</em>

     * the remote interface is a built-in system component that can never be

     * upgraded. In particular, this <em>must never</em> be called for

     * interfaces hosted by package that could be upgraded or replaced,

            ThreadLocal.withInitial(() -> sWarnOnBlocking);

    /**

     * Allow blocking calls for the current thread.  See {@link #allowBlocking}.

     * Allow blocking calls for the current thread.

     *

     * @see {@link #allowBlocking}.

     *

     * @hide

     */

    }

    /**

     * Reset the current thread to the default blocking behavior.  See {@link #defaultBlocking}.

     * Reset the current thread to the default blocking behavior.

     *

     * @see {@link #defaultBlocking}.

     *

     * @hide

     */

    /**

     * Return the ID of the process that sent you the current transaction

     * that is being processed.  This pid can be used with higher-level

     * that is being processed. This PID can be used with higher-level

     * system services to determine its identity and check permissions.

     * If the current thread is not currently executing an incoming transaction,

     * then its own pid is returned.

     * then its own PID is returned.

     *

     * Warning: oneway transactions do not receive PID.

     */

    public static final native int getCallingPid();

    /**

     * Return the Linux uid assigned to the process that sent you the

     * current transaction that is being processed.  This uid can be used with

     * Return the Linux UID assigned to the process that sent you the

     * current transaction that is being processed. This UID can be used with

     * higher-level system services to determine its identity and check

     * permissions. If the current thread is not currently executing an

     * incoming transaction, then its own uid is returned.

     * incoming transaction, then its own UID is returned.

     */

    @CriticalNative

    public static final native int getCallingUid();

    public static final native boolean isDirectlyHandlingTransaction();

    /**

     * Return the Linux uid assigned to the process that sent the transaction

     * Return the Linux UID assigned to the process that sent the transaction

     * currently being processed.

     *

     * @throws IllegalStateException if the current thread is not currently

     * current transaction that is being processed. This is the user

     * of the caller. It is distinct from {@link #getCallingUid()} in that a

     * particular user will have multiple distinct apps running under it each

     * with their own uid.  If the current thread is not currently executing an

     * with their own UID. If the current thread is not currently executing an

     * incoming transaction, then its own UserHandle is returned.

     *

     * @see UserHandle

     */

    public static final @NonNull UserHandle getCallingUserHandle() {

        return UserHandle.of(UserHandle.getUserId(getCallingUid()));

    /**

     * Convenience method for running the provided action enclosed in

     * {@link #clearCallingIdentity}/{@link #restoreCallingIdentity}

     * {@link #clearCallingIdentity}/{@link #restoreCallingIdentity}.

     *

     * Any exception thrown by the given action will be caught and rethrown after the call to

     * {@link #restoreCallingIdentity}

     * <p>Any exception thrown by the given action will be caught and

     * rethrown after the call to {@link #restoreCallingIdentity}.

     *

     * @hide

     */

    /**

     * Convenience method for running the provided action enclosed in

     * {@link #clearCallingIdentity}/{@link #restoreCallingIdentity} returning the result

     * {@link #clearCallingIdentity}/{@link #restoreCallingIdentity} returning the result.

     *

     * Any exception thrown by the given action will be caught and rethrown after the call to

     * {@link #restoreCallingIdentity}

     * <p>Any exception thrown by the given action will be caught and rethrown after

     * the call to {@link #restoreCallingIdentity}.

     *

     * @hide

     */

     * native-only code on Dalvik.

     *

     * @see StrictMode

     *

     * @hide

     */

    @CriticalNative

     * Gets the current native thread-local StrictMode policy mask.

     *

     * @see #setThreadStrictModePolicy

     *

     * @hide

     */

    @CriticalNative

     * reasons, we only support one UID. This UID represents the original user responsible for the

     * binder calls.

     *

     * <p>{@link Binder#restoreCallingWorkSource(long)} must always be called after setting the

     * <p>{@link #restoreCallingWorkSource(long)} must always be called after setting the

     * worksource.

     *

     * <p>A typical use case would be

     *

     * @param workSource The original UID responsible for the binder call.

     * @return token to restore original work source.

     **/

     */

    @CriticalNative

    public static final native long setCallingWorkSourceUid(int workSource);

    /**

     * Returns the work source set by the caller.

     *

     * Unlike {@link Binder#getCallingUid()}, this result of this method cannot be trusted. The

     * <p>Unlike {@link #getCallingUid()}, this result of this method cannot be trusted. The

     * caller can set the value to whatever they want. Only use this value if you trust the calling

     * uid.

     * UID.

     *

     * @return The original UID responsible for the binder transaction.

     */

     * <p>The work source will be propagated for future outgoing binder transactions

     * executed on this thread.

     *

     * <p>{@link Binder#restoreCallingWorkSource(long)} must always be called after clearing the

     * <p>{@link #restoreCallingWorkSource(long)} must always be called after clearing the

     * worksource.

     *

     * <p>A typical use case would be

     * </pre>

     *

     * @return token to restore original work source.

     **/

     */

    @CriticalNative

    public static final native long clearCallingWorkSource();

    /**

     * Restores the work source on this thread using a token returned by

     * {@link #setCallingWorkSourceUid(int) or {@link clearCallingWorkSource()}.

     * {@link #setCallingWorkSourceUid(int)} or {@link #clearCallingWorkSource()}.

     *

     * <p>A typical use case would be

     * <pre>

     *   Binder.restoreCallingWorkSource(token);

     * }

     * </pre>

     **/

     */

    @CriticalNative

    public static final native void restoreCallingWorkSource(long token);

     * Use a VINTF-stability binder w/o VINTF requirements. Should be called

     * on a binder before it is sent out of process.

     *

     * This must be called before the object is sent to another process.

     * <p>This must be called before the object is sent to another process.

     *

     * @hide

     */

    /**

     * Returns true if the specified interface is a proxy.

     *

     * @hide

     */

    public static final boolean isProxy(IInterface iface) {

    /**

     * Call blocks until the number of executing binder threads is less

     * than the maximum number of binder threads allowed for this process.

     *

     * @hide

     */

    public static final native void blockUntilThreadAvailable();

    /**

     * Default constructor just initializes the object.

     *

     * If you're creating a Binder token (a Binder object without an attached interface),

     * <p>If you're creating a Binder token (a Binder object without an attached interface),

     * you should use {@link #Binder(String)} instead.

     */

    public Binder() {

    /**

     * Constructor for creating a raw Binder object (token) along with a descriptor.

     *

     * The descriptor of binder objects usually specifies the interface they are implementing.

     * <p>The descriptor of binder objects usually specifies the interface they are implementing.

     * In case of binder tokens, no interface is implemented, and the descriptor can be used

     * as a sort of tag to help identify the binder token. This will help identify remote

     * references to these objects more easily when debugging.

    /**

     * Convenience method for associating a specific interface with the Binder.

     * After calling, queryLocalInterface() will be implemented for you

     * to return the given owner IInterface when the corresponding

     * descriptor is requested.

     * After calling, {@link #queryLocalInterface(String) queryLocalInterface()}

     * will be implemented for you to return the given owner IInterface when

     * the corresponding descriptor is requested.

     */

    public void attachInterface(@Nullable IInterface owner, @Nullable String descriptor) {

        mOwner = owner;

    }

    /**

     * Use information supplied to attachInterface() to return the

     * associated IInterface if it matches the requested

     * Use information supplied to {@link #attachInterface attachInterface()}

     * to return the associated {@link IInterface} if it matches the requested

     * descriptor.

     */

    public @Nullable IInterface queryLocalInterface(@NonNull String descriptor) {

     * process watchdog to disable incoming dump calls while it has detecting the system

     * is hung and is reporting that back to the activity controller. This is to

     * prevent the controller from getting hung up on bug reports at this point.

     * @hide

     *

     * @param msg The message to show instead of the dump; if null, dumps are

     * re-enabled.

     *

     * @hide

     */

    public static void setDumpDisabled(String msg) {

        sDumpDisabled = msg;

    /**

     * Listener to be notified about each proxy-side binder call.

     *

     * See {@link setProxyTransactListener}.

     * @see {@link #setProxyTransactListener}.

     *

     * @hide

     */

    @SystemApi

        /**

         * Called before onTransact.

         *

         * @return an object that will be passed back to #onTransactEnded (or null).

         * @return an object that will be passed back to {@link #onTransactEnded} (or null).,

         *

         * @hide

         */

        @Nullable

        /**

         * Called before onTransact.

         *

         * @return an object that will be passed back to #onTransactEnded (or null).

         * @return an object that will be passed back to {@link #onTransactEnded} (or null).

         */

        @Nullable

        Object onTransactStarted(@NonNull IBinder binder, int transactionCode);

        /**

         * Called after onTranact (even when an exception is thrown).

         * Called after onTransact (even when an exception is thrown).

         *

         * @param session The object return by #onTransactStarted.

         * @param session The object return by {@link #onTransactStarted}.

         */

        void onTransactEnded(@Nullable Object session);

    }

     * <li>By default, this listener will propagate the worksource if the outgoing call happens on

     * the same thread as the incoming binder call.

     * <li>Custom attribution can be done by calling {@link ThreadLocalWorkSource#setUid(int)}.

     *

     * @hide

     */

    public static class PropagateWorkSourceTransactListener implements ProxyTransactListener {

        @Override

        public Object onTransactStarted(IBinder binder, int transactionCode) {

           // Note that {@link Binder#getCallingUid()} is already set to the UID of the current

            // Note that {@link #getCallingUid()} is already set to the UID of the current

            // process when this method is called.

            //

           // We use ThreadLocalWorkSource instead. It also allows feature owners to set

           // {@link ThreadLocalWorkSource#set(int) manually to attribute resources to a UID.

            // We use {@link ThreadLocalWorkSource} instead. It also allows feature owners to set

            // {@link ThreadLocalWorkSource#set(int)} manually to attribute resources to a UID.

            int uid = ThreadLocalWorkSource.getUid();

            if (uid != ThreadLocalWorkSource.UID_NONE) {

                return Binder.setCallingWorkSourceUid(uid);

     * <li>The listener is called on the critical path of the binder transaction so be careful about

     * performance.

     * <li>Never execute another binder transaction inside the listener.

     *

     * @hide

     */

    @SystemApi

     * <p>Implementations that are returning a result should generally use

     * {@link Parcel#writeNoException() Parcel.writeNoException} and

     * {@link Parcel#writeException(Exception) Parcel.writeException} to propagate

     * exceptions back to the caller.</p>

     * exceptions back to the caller.

     *

     * @param code The action to perform.  This should

     * be a number between {@link #FIRST_CALL_TRANSACTION} and

     * {@link #LAST_CALL_TRANSACTION}.

     * @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 being received from the caller.

     * @param reply If the caller is expecting a result back, it should be marshalled

     * in to here.

     * Resolves a transaction code to a human readable name.

     *

     * <p>Default implementation is a stub that returns null.

     *

     * <p>AIDL generated code will return the original method name.

     *

     * @param transactionCode The code to resolve.

     * @return A human readable name.

     *

     * @hide

     */

    public @Nullable String getTransactionName(int transactionCode) {

     * @param callback Callback through which to interact with the invoking shell.

     * @param resultReceiver Called when the command has finished executing, with the result code.

     * @throws RemoteException

     *

     * @hide

     */

    public void shellCommand(@Nullable FileDescriptor in, @Nullable FileDescriptor out,

     *

     * <p class="caution">Note: no permission checking is done before calling this method; you must

     * apply any security checks as appropriate for the command being executed.

     * Consider using {@link ShellCommand} to help in the implementation.</p>

     * Consider using {@link ShellCommand} to help in the implementation.

     *

     * @hide

     */

    public void onShellCommand(@Nullable FileDescriptor in, @Nullable FileDescriptor out,

     * System services can implement this method to implement ADB shell commands.

     *

     * <p>A system binder service can implement it to handle shell commands on ADB. For example,

     * the Job Scheduler service implements it to handle <code>adb shell cmd jobscheduler</code>.

     * the Job Scheduler service implements it to handle {@code adb shell cmd jobscheduler}.

     *

     * <p>Commands are only executable by ADB shell; i.e. only {@link Process#SHELL_UID} and

     * {@link Process#ROOT_UID} can call them.

     * @param err standard error

     * @param args arguments passed to the command. Can be empty. The first argument is typically

     * a subcommand, such as {@code run} for {@code adb shell cmd jobscheduler run}.

     * @return the status code returned from the <code>cmd</code> command.

     * @return the status code returned from the {@code cmd} command.

     *

     * @hide

     */

    static void checkParcel(IBinder obj, int code, Parcel parcel, String msg) {

        if (CHECK_PARCEL_SIZE && parcel.dataSize() >= 800*1024) {

            // Trying to send > 800k, this is way too much

            // Trying to send > 800k, this is way too much.

            StringBuilder sb = new StringBuilder();

            sb.append(msg);

            sb.append(": on ");

    private static native long getNativeBBinderHolder();

    /**

     * By default, we use the calling uid since we can always trust it.

     * By default, we use the calling UID since we can always trust it.

     */

    private static volatile BinderInternal.WorkSourceProvider sWorkSourceProvider =

            (x) -> Binder.getCallingUid();

     * <li>The callback is called on the critical path of the binder transaction so be careful about

     * performance.

     * <li>Never execute another binder transaction inside the callback.

     *

     * @hide

     */

    public static void setWorkSourceProvider(BinderInternal.WorkSourceProvider workSourceProvider) {

        sWorkSourceProvider = workSourceProvider;

    }

    // Entry point from android_util_Binder.cpp's onTransact

    // Entry point from android_util_Binder.cpp's onTransact.

    @UnsupportedAppUsage

    private boolean execTransact(int code, long dataObj, long replyObj,

            int flags) {

        // At that point, the parcel request headers haven't been parsed so we do not know what

        // WorkSource the caller has set. Use calling uid as the default.

        // {@link WorkSource} the caller has set. Use calling UID as the default.

        final int callingUid = Binder.getCallingUid();

        final long origWorkSource = ThreadLocalWorkSource.setUid(callingUid);

        try {

                observer != null ? observer.callStarted(this, code, UNSET_WORKSOURCE) : null;

        Parcel data = Parcel.obtain(dataObj);

        Parcel reply = Parcel.obtain(replyObj);

        // theoretically, we should call transact, which will call onTransact,

        // Theoretically, we should call transact, which will call onTransact,

        // but all that does is rewind it, and we just got these from an IPC,

        // so we'll just call it directly.

        boolean res;

        // Log any exceptions as warnings, don't silently suppress them.

        // If the call was FLAG_ONEWAY then these exceptions disappear into the ether.

        // If the call was {@link IBinder#FLAG_ONEWAY} then these exceptions

        // disappear into the ether.

        final boolean tracingEnabled = Binder.isTracingEnabled();

        try {

            final BinderCallHeavyHitterWatcher heavyHitterWatcher = sHeavyHitterWatcher;

            if (heavyHitterWatcher != null) {

                // Notify the heavy hitter watcher, if it's enabled

                // Notify the heavy hitter watcher, if it's enabled.

                heavyHitterWatcher.onTransaction(callingUid, getClass(), code);

            }

            if (tracingEnabled) {

                    Log.w(TAG, "Caught a RuntimeException from the binder stub implementation.", e);

                }

            } else {

                // Clear the parcel before writing the exception

                // Clear the parcel before writing the exception.

                reply.setDataSize(0);

                reply.setDataPosition(0);

                reply.writeException(e);

            }

            if (observer != null) {

                // The parcel RPC headers have been called during onTransact so we can now access

                // the worksource uid from the parcel.

                // the worksource UID from the parcel.

                final int workSourceUid = sWorkSourceProvider.resolveWorkSourceUid(

                        data.readCallingWorkSourceUid());

                observer.callEnded(callSession, data.dataSize(), reply.dataSize(), workSourceUid);