Merge "Fix issue #64224738: Document return value of IBinder.transact()" into oc-mr1-dev

2 files changed, 55 insertions, 28 deletions

diff --git a/core/java/android/os/Binder.java b/core/java/android/os/Binder.java
index 5331304aa1b3..f45efdab361e 100644
--- a/core/java/android/os/Binder.java
+++ b/core/java/android/os/Binder.java
@@ -16,6 +16,8 @@
 
 package android.os;
 
+import android.annotation.NonNull;
+import android.annotation.Nullable;
 import android.util.ExceptionUtils;
 import android.util.Log;
 import android.util.Slog;
@@ -218,7 +220,7 @@ public class Binder implements IBinder {
      * with their own uid.  If the current thread is not currently executing an
      * incoming transaction, then its own UserHandle is returned.
      */
-    public static final UserHandle getCallingUserHandle() {
+    public static final @NonNull UserHandle getCallingUserHandle() {
         return UserHandle.of(UserHandle.getUserId(getCallingUid()));
     }
 
@@ -261,7 +263,7 @@ public class Binder implements IBinder {
      *
      * @hide
      */
-    public static final void withCleanCallingIdentity(ThrowingRunnable action) {
+    public static final void withCleanCallingIdentity(@NonNull ThrowingRunnable action) {
         long callingIdentity = clearCallingIdentity();
         Throwable throwableToPropagate = null;
         try {
@@ -285,7 +287,7 @@ public class Binder implements IBinder {
      *
      * @hide
      */
-    public static final <T> T withCleanCallingIdentity(ThrowingSupplier<T> action) {
+    public static final <T> T withCleanCallingIdentity(@NonNull ThrowingSupplier<T> action) {
         long callingIdentity = clearCallingIdentity();
         Throwable throwableToPropagate = null;
         try {
@@ -377,7 +379,7 @@ public class Binder implements IBinder {
      * to return the given owner IInterface when the corresponding
      * descriptor is requested.
      */
-    public void attachInterface(IInterface owner, String descriptor) {
+    public void attachInterface(@Nullable IInterface owner, @Nullable String descriptor) {
         mOwner = owner;
         mDescriptor = descriptor;
     }
@@ -385,7 +387,7 @@ public class Binder implements IBinder {
     /**
      * Default implementation returns an empty interface name.
      */
-    public String getInterfaceDescriptor() {
+    public @Nullable String getInterfaceDescriptor() {
         return mDescriptor;
     }
 
@@ -412,7 +414,7 @@ public class Binder implements IBinder {
      * associated IInterface if it matches the requested
      * descriptor.
      */
-    public IInterface queryLocalInterface(String descriptor) {
+    public @Nullable IInterface queryLocalInterface(@NonNull String descriptor) {
         if (mDescriptor.equals(descriptor)) {
             return mOwner;
         }
@@ -438,8 +440,20 @@ public class Binder implements IBinder {
      * to override this to do the appropriate unmarshalling of transactions.
      *
      * <p>If you want to call this, call transact().
+     *
+     * @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.
+     * @param flags Additional operation flags.  Either 0 for a normal
+     * RPC, or {@link #FLAG_ONEWAY} for a one-way RPC.
+     *
+     * @return Return true on a successful call; returning false is generally used to
+     * indicate that you did not understand the transaction code.
      */
-    protected boolean onTransact(int code, Parcel data, Parcel reply,
+    protected boolean onTransact(int code, @NonNull Parcel data, @Nullable Parcel reply,
             int flags) throws RemoteException {
         if (code == INTERFACE_TRANSACTION) {
             reply.writeString(getInterfaceDescriptor());
@@ -495,7 +509,7 @@ public class Binder implements IBinder {
      * Implemented to call the more convenient version
      * {@link #dump(FileDescriptor, PrintWriter, String[])}.
      */
-    public void dump(FileDescriptor fd, String[] args) {
+    public void dump(@NonNull FileDescriptor fd, @Nullable String[] args) {
         FileOutputStream fout = new FileOutputStream(fd);
         PrintWriter pw = new FastPrintWriter(fout);
         try {
@@ -531,7 +545,7 @@ public class Binder implements IBinder {
      * Like {@link #dump(FileDescriptor, String[])}, but ensures the target
      * executes asynchronously.
      */
-    public void dumpAsync(final FileDescriptor fd, final String[] args) {
+    public void dumpAsync(@NonNull final FileDescriptor fd, @Nullable final String[] args) {
         final FileOutputStream fout = new FileOutputStream(fd);
         final PrintWriter pw = new FastPrintWriter(fout);
         Thread thr = new Thread("Binder.dumpAsync") {
@@ -554,7 +568,8 @@ public class Binder implements IBinder {
      * closed for you after you return.
      * @param args additional arguments to the dump request.
      */
-    protected void dump(FileDescriptor fd, PrintWriter fout, String[] args) {
+    protected void dump(@NonNull FileDescriptor fd, @NonNull PrintWriter fout,
+            @Nullable String[] args) {
     }
 
     /**
@@ -567,9 +582,10 @@ public class Binder implements IBinder {
      * @throws RemoteException
      * @hide
      */
-    public void shellCommand(FileDescriptor in, FileDescriptor out, FileDescriptor err,
-            String[] args, ShellCallback callback,
-            ResultReceiver resultReceiver) throws RemoteException {
+    public void shellCommand(@Nullable FileDescriptor in, @Nullable FileDescriptor out,
+            @Nullable FileDescriptor err,
+            @NonNull String[] args, @Nullable ShellCallback callback,
+            @NonNull ResultReceiver resultReceiver) throws RemoteException {
         onShellCommand(in, out, err, args, callback, resultReceiver);
     }
 
@@ -581,8 +597,10 @@ public class Binder implements IBinder {
      * Consider using {@link ShellCommand} to help in the implementation.</p>
      * @hide
      */
-    public void onShellCommand(FileDescriptor in, FileDescriptor out, FileDescriptor err,
-            String[] args, ShellCallback callback, ResultReceiver resultReceiver) throws RemoteException {
+    public void onShellCommand(@Nullable FileDescriptor in, @Nullable FileDescriptor out,
+            @Nullable FileDescriptor err,
+            @NonNull String[] args, @Nullable ShellCallback callback,
+            @NonNull ResultReceiver resultReceiver) throws RemoteException {
         FileOutputStream fout = new FileOutputStream(err != null ? err : out);
         PrintWriter pw = new FastPrintWriter(fout);
         pw.println("No shell command implementation.");
@@ -594,7 +612,7 @@ public class Binder implements IBinder {
      * Default implementation rewinds the parcels and calls onTransact.  On
      * the remote side, transact calls into the binder to do the IPC.
      */
-    public final boolean transact(int code, Parcel data, Parcel reply,
+    public final boolean transact(int code, @NonNull Parcel data, @Nullable Parcel reply,
             int flags) throws RemoteException {
         if (false) Log.v("Binder", "Transact: " + code + " to " + this);
 
@@ -611,13 +629,13 @@ public class Binder implements IBinder {
     /**
      * Local implementation is a no-op.
      */
-    public void linkToDeath(DeathRecipient recipient, int flags) {
+    public void linkToDeath(@NonNull DeathRecipient recipient, int flags) {
     }
 
     /**
      * Local implementation is a no-op.
      */
-    public boolean unlinkToDeath(DeathRecipient recipient, int flags) {
+    public boolean unlinkToDeath(@NonNull DeathRecipient recipient, int flags) {
         return true;
     }
     
diff --git a/core/java/android/os/IBinder.java b/core/java/android/os/IBinder.java
index d5216e73ba66..e74b0bb9e3f0 100644
--- a/core/java/android/os/IBinder.java
+++ b/core/java/android/os/IBinder.java
@@ -16,6 +16,9 @@
 
 package android.os;
 
+import android.annotation.NonNull;
+import android.annotation.Nullable;
+
 import java.io.FileDescriptor;
 
 /**
@@ -174,7 +177,7 @@ public interface IBinder {
     /**
      * Get the canonical name of the interface supported by this binder.
      */
-    public String getInterfaceDescriptor() throws RemoteException;
+    public @Nullable String getInterfaceDescriptor() throws RemoteException;
 
     /**
      * Check to see if the object still exists.
@@ -200,7 +203,7 @@ public interface IBinder {
      * to instantiate a proxy class to marshall calls through
      * the transact() method.
      */
-    public IInterface queryLocalInterface(String descriptor);
+    public @Nullable IInterface queryLocalInterface(@NonNull String descriptor);
 
     /**
      * Print the object's state into the given stream.
@@ -208,7 +211,7 @@ public interface IBinder {
      * @param fd The raw file descriptor that the dump is being sent to.
      * @param args additional arguments to the dump request.
      */
-    public void dump(FileDescriptor fd, String[] args) throws RemoteException;
+    public void dump(@NonNull FileDescriptor fd, @Nullable String[] args) throws RemoteException;
 
     /**
      * Like {@link #dump(FileDescriptor, String[])} but always executes
@@ -218,7 +221,8 @@ public interface IBinder {
      * @param fd The raw file descriptor that the dump is being sent to.
      * @param args additional arguments to the dump request.
      */
-    public void dumpAsync(FileDescriptor fd, String[] args) throws RemoteException;
+    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;
@@ -232,9 +236,10 @@ public interface IBinder {
      * @param resultReceiver Called when the command has finished executing, with the result code.
      * @hide
      */
-    public void shellCommand(FileDescriptor in, FileDescriptor out, FileDescriptor err,
-            String[] args, ShellCallback shellCallback,
-            ResultReceiver resultReceiver) throws RemoteException;
+    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.
@@ -249,8 +254,12 @@ public interface IBinder {
      * 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, Parcel data, Parcel reply, int flags)
+    public boolean transact(int code, @NonNull Parcel data, @Nullable Parcel reply, int flags)
         throws RemoteException;
 
     /**
@@ -279,7 +288,7 @@ public interface IBinder {
      * 
      * @see #unlinkToDeath
      */
-    public void linkToDeath(DeathRecipient recipient, int flags)
+    public void linkToDeath(@NonNull DeathRecipient recipient, int flags)
             throws RemoteException;
 
     /**
@@ -300,5 +309,5 @@ public interface IBinder {
      * exception will <em>not</em> be thrown, and you will receive a false
      * return value instead.
      */
-    public boolean unlinkToDeath(DeathRecipient recipient, int flags);
+    public boolean unlinkToDeath(@NonNull DeathRecipient recipient, int flags);
 }