content: /*
   * Copyright (C) 2006 The Android Open Source Project
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  
  package android.os;
  
  import android.annotation.NonNull;
  import android.annotation.Nullable;
  import android.annotation.UnsupportedAppUsage;
  
  import java.io.FileDescriptor;
  
  /**
   * Base interface for a remotable object, the core part of a lightweight
   * remote procedure call mechanism designed for high performance when
   * performing in-process and cross-process calls.  This
   * interface describes the abstract protocol for interacting with a
   * remotable object.  Do not implement this interface directly, instead
   * extend from {@link Binder}.
   * 
   * <p>The key IBinder API is {@link #transact transact()} matched by
   * {@link Binder#onTransact Binder.onTransact()}.  These
   * methods allow you to send a call to an IBinder object and receive a
   * call coming in to a Binder object, respectively.  This transaction API
   * is synchronous, such that a call to {@link #transact transact()} does not
   * return until the target has returned from
   * {@link Binder#onTransact Binder.onTransact()}; this is the
   * expected behavior when calling an object that exists in the local
   * process, and the underlying inter-process communication (IPC) mechanism
   * ensures that these same semantics apply when going across processes.
   * 
   * <p>The data sent through transact() is a {@link Parcel}, a generic buffer
   * of data that also maintains some meta-data about its contents.  The meta
   * data is used to manage IBinder object references in the buffer, so that those
   * references can be maintained as the buffer moves across processes.  This
   * mechanism ensures that when an IBinder is written into a Parcel and sent to
   * another process, if that other process sends a reference to that same IBinder
   * back to the original process, then the original process will receive the
   * same IBinder object back.  These semantics allow IBinder/Binder objects to
   * be used as a unique identity (to serve as a token or for other purposes)
   * that can be managed across processes.
   * 
   * <p>The system maintains a pool of transaction threads in each process that
   * it runs in.  These threads are used to dispatch all
   * IPCs coming in from other processes.  For example, when an IPC is made from
   * process A to process B, the calling thread in A blocks in transact() as
   * it sends the transaction to process B.  The next available pool thread in
   * B receives the incoming transaction, calls Binder.onTransact() on the target
   * object, and replies with the result Parcel.  Upon receiving its result, the
   * thread in process A returns to allow its execution to continue.  In effect,
   * other processes appear to use as additional threads that you did not create
   * executing in your own process.
   * 
   * <p>The Binder system also supports recursion across processes.  For example
   * if process A performs a transaction to process B, and process B while
   * handling that transaction calls transact() on an IBinder that is implemented
   * in A, then the thread in A that is currently waiting for the original
   * transaction to finish will take care of calling Binder.onTransact() on the
   * object being called by B.  This ensures that the recursion semantics when
   * calling remote binder object are the same as when calling local objects.
   * 
   * <p>When working with remote objects, you often want to find out when they
   * are no longer valid.  There are three ways this can be determined:
   * <ul>
   * <li> The {@link #transact transact()} method will throw a
   * {@link RemoteException} exception if you try to call it on an IBinder
   * whose process no longer exists.
   * <li> The {@link #pingBinder()} method can be called, and will return false
   * if the remote process no longer exists.
   * <li> The {@link #linkToDeath linkToDeath()} method can be used to register
   * a {@link DeathRecipient} with the IBinder, which will be called when its
   * containing process goes away.
   * </ul>
   * 
   * @see Binder
   */
  public interface IBinder {
      /**
       * The first transaction code available for user commands.
       */
      int FIRST_CALL_TRANSACTION  = 0x00000001;
      /**
       * The last transaction code available for user commands.
       */
      int LAST_CALL_TRANSACTION   = 0x00ffffff;
      
      /**
       * IBinder protocol transaction code: pingBinder().
       */
      int PING_TRANSACTION        = ('_'<<24)|('P'<<16)|('N'<<8)|'G';
      
      /**
       * IBinder protocol transaction code: dump internal state.
       */
      int DUMP_TRANSACTION        = ('_'<<24)|('D'<<16)|('M'<<8)|'P';
      
      /**
       * IBinder protocol transaction code: execute a shell command.
       * @hide
       */
      int SHELL_COMMAND_TRANSACTION = ('_'<<24)|('C'<<16)|('M'<<8)|'D';
  
      /**
       * IBinder protocol transaction code: interrogate the recipient side
       * of the transaction for its canonical interface descriptor.
       */
      int INTERFACE_TRANSACTION   = ('_'<<24)|('N'<<16)|('T'<<8)|'F';
  
      /**
       * IBinder protocol transaction code: send a tweet to the target
       * object.  The data in the parcel is intended to be delivered to
       * a shared messaging service associated with the object; it can be
       * anything, as long as it is not more than 130 UTF-8 characters to
       * conservatively fit within common messaging services.  As part of
       * {@link Build.VERSION_CODES#HONEYCOMB_MR2}, all Binder objects are
       * expected to support this protocol for fully integrated tweeting
       * across the platform.  To support older code, the default implementation
       * logs the tweet to the main log as a simple emulation of broadcasting
       * it publicly over the Internet.
       * 
       * <p>Also, upon completing the dispatch, the object must make a cup
       * of tea, return it to the caller, and exclaim "jolly good message
       * old boy!".
       */
      int TWEET_TRANSACTION   = ('_'<<24)|('T'<<16)|('W'<<8)|'T';
  
      /**
       * IBinder protocol transaction code: tell an app asynchronously that the
       * caller likes it.  The app is responsible for incrementing and maintaining
       * its own like counter, and may display this value to the user to indicate the
       * quality of the app.  This is an optional command that applications do not
       * need to handle, so the default implementation is to do nothing.
       * 
       * <p>There is no response returned and nothing about the
       * system will be functionally affected by it, but it will improve the
       * app's self-esteem.
       */
      int LIKE_TRANSACTION   = ('_'<<24)|('L'<<16)|('I'<<8)|'K';
  
      /** @hide */
      @UnsupportedAppUsage
      int SYSPROPS_TRANSACTION = ('_'<<24)|('S'<<16)|('P'<<8)|'R';
  
      /**
       * Flag to {@link #transact}: this is a one-way call, meaning that the
       * caller returns immediately, without waiting for a result from the
       * callee. Applies only if the caller and callee are in different
       * processes.
       *
       * <p>The system provides special ordering semantics for multiple oneway calls
       * being made to the same IBinder object: these calls will be dispatched in the
       * other process one at a time, with the same order as the original calls.  These
       * are still dispatched by the IPC thread pool, so may execute on different threads,
       * but the next one will not be dispatched until the previous one completes.  This
       * ordering is not guaranteed for calls on different IBinder objects or when mixing
       * oneway and non-oneway calls on the same IBinder object.</p>
       */
      int FLAG_ONEWAY             = 0x00000001;
  
      /**
       * Limit that should be placed on IPC sizes to keep them safely under the
       * transaction buffer limit.
       * @hide
       */
      public static final int MAX_IPC_SIZE = 64 * 1024;
  
      /**
       * Get the canonical name of the interface supported by this binder.
       */
      public @Nullable String getInterfaceDescriptor() throws RemoteException;
  
      /**
       * Check to see if the object still exists.
       * 
       * @return Returns false if the
       * hosting process is gone, otherwise the result (always by default
       * true) returned by the pingBinder() implementation on the other
       * side.
       */
      public boolean pingBinder();
  
      /**
       * Check to see if the process that the binder is in is still alive.
       *
       * @return false if the process is not alive.  Note that if it returns
       * true, the process may have died while the call is returning.
       */
      public boolean isBinderAlive();
      
      /**
       * Attempt to retrieve a local implementation of an interface
       * for this Binder object.  If null is returned, you will need
       * to instantiate a proxy class to marshall calls through
       * the transact() method.
       */
      public @Nullable IInterface queryLocalInterface(@NonNull String descriptor);
  
      /**
       * Print the object's state into the given stream.
       * 
       * @param fd The raw file descriptor that the dump is being sent to.
       * @param args additional arguments to the dump request.
       */
      public void dump(@NonNull FileDescriptor fd, @Nullable String[] args) throws RemoteException;
  
      /**
       * Like {@link #dump(FileDescriptor, String[])} but always executes
       * asynchronously.  If the object is local, a new thread is created
       * to perform the dump.
       *
       * @param fd The raw file descriptor that the dump is being sent to.
       * @param args additional arguments to the dump request.
       */
      public void dumpAsync(@NonNull FileDescriptor fd, @Nullable String[] args)
              throws RemoteException;
  
      /**
       * Execute a shell command on this object.  This may be performed asynchrously from the caller;
       * the implementation must always call resultReceiver when finished.
       *
       * @param in The raw file descriptor that an input data stream can be read from.
       * @param out The raw file descriptor that normal command messages should be written to.
       * @param err The raw file descriptor that command error messages should be written to.
       * @param args Command-line arguments.
       * @param shellCallback Optional callback to the caller's shell to perform operations in it.
       * @param resultReceiver Called when the command has finished executing, with the result code.
       * @hide
       */
      public void shellCommand(@Nullable FileDescriptor in, @Nullable FileDescriptor out,
              @Nullable FileDescriptor err,
              @NonNull String[] args, @Nullable ShellCallback shellCallback,
              @NonNull ResultReceiver resultReceiver) throws RemoteException;
  
      /**
       * Perform a generic operation with the object.
       * 
       * @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 to send to the target.  Must not be null.
       * If you are not sending any data, you must create an empty Parcel
       * that is given here.
       * @param reply Marshalled data to be received from the target.  May be
       * null if you are not interested in the return value.
       * @param flags Additional operation flags.  Either 0 for a normal
       * RPC, or {@link #FLAG_ONEWAY} for a one-way RPC.
       *
       * @return Returns the result from {@link Binder#onTransact}.  A successful call
       * generally returns true; false generally means the transaction code was not
       * understood.
       */
      public boolean transact(int code, @NonNull Parcel data, @Nullable Parcel reply, int flags)
          throws RemoteException;
  
      /**
       * Interface for receiving a callback when the process hosting an IBinder
       * has gone away.
       * 
       * @see #linkToDeath
       */
      public interface DeathRecipient {
          public void binderDied();
      }
  
      /**
       * Register the recipient for a notification if this binder
       * goes away.  If this binder object unexpectedly goes away
       * (typically because its hosting process has been killed),
       * then the given {@link DeathRecipient}'s
       * {@link DeathRecipient#binderDied DeathRecipient.binderDied()} method
       * will be called.
       * 
       * <p>You will only receive death notifications for remote binders,
       * as local binders by definition can't die without you dying as well.
       * 
       * @throws RemoteException if the target IBinder's
       * process has already died.
       * 
       * @see #unlinkToDeath
       */
      public void linkToDeath(@NonNull DeathRecipient recipient, int flags)
              throws RemoteException;
  
      /**
       * Remove a previously registered death notification.
       * The recipient will no longer be called if this object
       * dies.
       * 
       * @return {@code true} if the <var>recipient</var> is successfully
       * unlinked, assuring you that its
       * {@link DeathRecipient#binderDied DeathRecipient.binderDied()} method
       * will not be called;  {@code false} if the target IBinder has already
       * died, meaning the method has been (or soon will be) called.
       * 
       * @throws java.util.NoSuchElementException if the given
       * <var>recipient</var> has not been registered with the IBinder, and
       * the IBinder is still alive.  Note that if the <var>recipient</var>
       * was never registered, but the IBinder has already died, then this
       * exception will <em>not</em> be thrown, and you will receive a false
       * return value instead.
       */
      public boolean unlinkToDeath(@NonNull DeathRecipient recipient, int flags);
  }
  