am c5ff0020: Merge "Add API to hint whether to show on-board UI before a permission request." into mnc-dev

* commit 'c5ff0020a2467e0b7aed590d790b5a1b4b082f56':
  Add API to hint whether to show on-board UI before a permission request.

core/java/android/app/Activity.java

@@ -3746,6 +3746,7 @@ public class Activity extends ContextThemeWrapper
      *
      * @see #onRequestPermissionsResult(int, String[], int[])
      * @see #checkSelfPermission(String)
+     * @see #canShowRequestPermissionRationale(String)
      */
     public final void requestPermissions(@NonNull String[] permissions, int requestCode) {
         Intent intent = getPackageManager().buildRequestPermissionsIntent(permissions);
@@ -3769,6 +3770,30 @@ public class Activity extends ContextThemeWrapper
         /* callback - no nothing */
     }
 
+    /**
+     * Gets whether you should show UI with rationale for requesting a permission.
+     * You should do this only if you do not have the permission and the context in
+     * which the permission is requested does not clearly communicate to the user
+     * what would be the benefit from granting this permission.
+     * <p>
+     * For example, if you write a camera app, requesting the camera permission
+     * would be expected by the user and no rationale for why it is requested is
+     * needed. If however, the app needs location for tagging photos then a non-tech
+     * savvy user may wonder how location is related to taking photos. In this case
+     * you may choose to show UI with rationale of requesting this permission.
+     * </p>
+     *
+     * @param permission A permission your app wants to request.
+     * @return Whether you can show permission rationale UI.
+     *
+     * @see #checkSelfPermission(String)
+     * @see #requestPermissions(String[], int)
+     * @see #onRequestPermissionsResult(int, String[], int[])
+     */
+    public boolean shouldShowRequestPermissionRationale(String permission) {
+        return getPackageManager().shouldShowRequestPermissionRationale(permission);
+    }
+
     /**
      * Same as calling {@link #startActivityForResult(Intent, int, Bundle)}
      * with no options.

core/java/android/app/ApplicationPackageManager.java

@@ -485,6 +485,16 @@ final class ApplicationPackageManager extends PackageManager {
         }
     }
 
+    @Override
+    public boolean shouldShowRequestPermissionRationale(String permission) {
+        try {
+            return mPM.shouldShowRequestPermissionRationale(permission,
+                    mContext.getPackageName(), mContext.getUserId());
+        } catch (RemoteException e) {
+            throw new RuntimeException("Package manager has died", e);
+        }
+    }
+
     @Override
     public int checkSignatures(String pkg1, String pkg2) {
         try {

core/java/android/content/pm/IPackageManager.aidl

@@ -105,6 +105,9 @@ interface IPackageManager {
     void updatePermissionFlags(String permissionName, String packageName, int flagMask,
             int flagValues, int userId);
 
+    boolean shouldShowRequestPermissionRationale(String permissionName,
+            String packageName, int userId);
+
     boolean isProtectedBroadcast(String actionName);
 
     int checkSignatures(String pkg1, String pkg2);

core/java/android/content/pm/PackageManager.java

@@ -2538,6 +2538,19 @@ public abstract class PackageManager {
             String packageName, @PermissionFlags int flagMask, int flagValues,
             @NonNull UserHandle user);
 
+    /**
+     * Gets whether you should show UI with rationale for requesting a permission.
+     * You should do this only if you do not have the permission and the context in
+     * which the permission is requested does not clearly communicate to the user
+     * what would be the benefit from grating this permission.
+     *
+     * @param permission A permission your app wants to request.
+     * @return Whether you can show permission rationale UI.
+     *
+     * @hide
+     */
+    public abstract boolean shouldShowRequestPermissionRationale(String permission);
+
     /**
      * Returns an {@link android.content.Intent} suitable for passing to
      * {@link android.app.Activity#startActivityForResult(android.content.Intent, int)}