Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge "Fix issue #64224738: Document return value of IBinder.transact()"

Browse Source
This commit is contained in:
Hans Boehm
2017-10-26 00:01:12 +00:00
committed by Gerrit Code Review
parent 65944e79b2 8de9566375
commit ceb336fc8a
2 changed files with 55 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
core/java/android/os/Binder.java
View File

@@ -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;
@@ -217,7 +219,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()));
}
@@ -260,7 +262,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 {
@@ -284,7 +286,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 {
@@ -376,7 +378,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;
}
@@ -384,7 +386,7 @@ public class Binder implements IBinder {
/**
* Default implementation returns an empty interface name.
*/
public String getInterfaceDescriptor() {
public @Nullable String getInterfaceDescriptor() {
return mDescriptor;
}
@@ -411,7 +413,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;
}
@@ -437,8 +439,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());
@@ -494,7 +508,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 {
@@ -530,7 +544,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") {
@@ -553,7 +567,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) {
}
/**
@@ -566,9 +581,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);
}
@@ -580,8 +596,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.");
@@ -593,7 +611,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);
@@ -610,13 +628,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;
}

29
core/java/android/os/IBinder.java
View File

@@ -16,6 +16,9 @@
package android.os;
import android.annotation.NonNull;
import android.annotation.Nullable;
import java.io.FileDescriptor;
/**
@@ -166,7 +169,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.
@@ -192,7 +195,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.
@@ -200,7 +203,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
@@ -210,7 +213,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;
@@ -224,9 +228,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.
@@ -241,8 +246,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;
/**
@@ -271,7 +280,7 @@ public interface IBinder {
*
* @see #unlinkToDeath
*/
public void linkToDeath(DeathRecipient recipient, int flags)
public void linkToDeath(@NonNull DeathRecipient recipient, int flags)
throws RemoteException;
/**
@@ -292,5 +301,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);
}