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

1 files changed, 19 insertions, 10 deletions

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);
 }