diff --git a/binder/src/main/java/io/grpc/binder/AndroidComponentAddress.java b/binder/src/main/java/io/grpc/binder/AndroidComponentAddress.java index c4c17bb2ce..5617a141f9 100644 --- a/binder/src/main/java/io/grpc/binder/AndroidComponentAddress.java +++ b/binder/src/main/java/io/grpc/binder/AndroidComponentAddress.java @@ -250,7 +250,22 @@ public final class AndroidComponentAddress extends SocketAddress { return this; } - /** See {@link AndroidComponentAddress#getTargetUser()}. */ + /** + * Specifies the Android user in which the built Address' bind Intent will be evaluated. + * + *

Connecting to a server in a different Android user is uncommon and requires the client app + * have runtime visibility of @SystemApi's and hold certain @SystemApi permissions. + * The device must also be running Android SDK version 30 or higher. + * + *

See https://developer.android.com/guide/app-compatibility/restrictions-non-sdk-interfaces + * for details on which apps can call the underlying @SystemApi's needed to make this type + * of connection. + * + *

One of the "android.permission.INTERACT_ACROSS_XXX" permissions is required. The exact one + * depends on the calling user's relationship to the target user, whether client and server are + * in the same or different apps, and the version of Android in use. See {@link + * Context#bindServiceAsUser}, the essential underlying Android API, for details. + */ @ExperimentalApi("https://github.com/grpc/grpc-java/issues/10173") public Builder setTargetUser(@Nullable UserHandle targetUser) { this.targetUser = targetUser; diff --git a/binder/src/main/java/io/grpc/binder/ApiConstants.java b/binder/src/main/java/io/grpc/binder/ApiConstants.java index 292c580c2b..05950a9eae 100644 --- a/binder/src/main/java/io/grpc/binder/ApiConstants.java +++ b/binder/src/main/java/io/grpc/binder/ApiConstants.java @@ -35,12 +35,15 @@ public final class ApiConstants { /** * Specifies the Android user in which target URIs should be resolved. * - *

{@link UserHandle} can't reasonably be encoded in a target URI string. Instead, all - * {@link io.grpc.NameResolverProvider}s producing {@link AndroidComponentAddress}es should let - * clients address servers in another Android user using this argument. + *

{@link UserHandle} can't reasonably be encoded in a target URI string. Instead, all {@link + * io.grpc.NameResolverProvider}s producing {@link AndroidComponentAddress}es should let clients + * address servers in another Android user using this argument. * - *

See also {@link AndroidComponentAddress#getTargetUser()}. + *

Connecting to a server in a different Android user is uncommon and can only be done by a + * "system app" client with special permissions. See {@link + * AndroidComponentAddress.Builder#setTargetUser(UserHandle)} for details. */ + @ExperimentalApi("https://github.com/grpc/grpc-java/issues/10173") public static final NameResolver.Args.Key TARGET_ANDROID_USER = NameResolver.Args.Key.create("target-android-user"); } diff --git a/binder/src/main/java/io/grpc/binder/BinderChannelBuilder.java b/binder/src/main/java/io/grpc/binder/BinderChannelBuilder.java index 0b8f0bb4b3..f996ee7cdb 100644 --- a/binder/src/main/java/io/grpc/binder/BinderChannelBuilder.java +++ b/binder/src/main/java/io/grpc/binder/BinderChannelBuilder.java @@ -242,9 +242,9 @@ public final class BinderChannelBuilder extends ForwardingChannelBuilderTargeting a Service in a different Android user is uncommon and requires special permissions - * normally reserved for system apps. See {@link android.content.Context#bindServiceAsUser} for - * details. + *

Connecting to a server in a different Android user is uncommon and can only be done by a + * "system app" client with special permissions. See {@link + * AndroidComponentAddress.Builder#setTargetUser(UserHandle)} for details. * * @deprecated This method's name is misleading because it implies an impersonated client identity * when it's actually specifying part of the server's location. It's also no longer necessary