From e7489fde9ff1529cc0c7a984046918a47b97b40c Mon Sep 17 00:00:00 2001 From: Andrew Solovay Date: Wed, 22 Jul 2015 14:43:49 -0700 Subject: docs: Updating the permissions docs for Preview 3. Added section describing the new support library methods. Also updating lists of normal and dangerous permissions based on current AndroidManifest in mnc-dev, as well as any other changes brought to my attention. See first comment for doc stage location. Change-Id: I4eaf45d98846e2bf9456f5896da4ec3079f4ba18 --- docs/html/preview/features/runtime-permissions.jd | 148 +++++++++++++++++++--- 1 file changed, 129 insertions(+), 19 deletions(-) diff --git a/docs/html/preview/features/runtime-permissions.jd b/docs/html/preview/features/runtime-permissions.jd index 765a3d5..144a5fe 100644 --- a/docs/html/preview/features/runtime-permissions.jd +++ b/docs/html/preview/features/runtime-permissions.jd @@ -411,6 +411,14 @@ page.image=images/permissions_check.png {@link android.os.Build.VERSION#CODENAME CODENAME} is "MNC".

+

+ Alternatively, you can use the new methods introduced with revision 23 of the + v4 and v13 support libraries. The support library methods behave + appropriately whether or not the app is running on the M Developer Preview. + For more information, see Support library methods for + handling permissions. +

+

Check if the app has the needed permission

When the user tries to do something that requires a permission, the app @@ -469,10 +477,7 @@ page.image=images/permissions_check.png android.permission.WRITE_CONTACTS

  • - android.permission.READ_PROFILE -
    • -
  • - android.permission.WRITE_PROFILE + android.permission.GET_ACCOUNTS
    • @@ -540,11 +545,6 @@ page.image=images/permissions_check.png android.permission.BODY_SENSORS - @@ -615,13 +615,14 @@ page.image=images/permissions_check.png

    - If the user turned down the permission request in the - past and chose the Don't ask again option in the permission request system - dialog, this method returns false. The method also returns - false if the device policy prohibits the app from having that - permission. + If the user turned down the permission request in the past and chose the + Don't ask again option in the permission request system dialog, this + method returns false. The method also returns false + if the device policy prohibits the app from having that permission.

    + +

    Request permissions if necessary

    If the app doesn't already have the permission it needs, the app calls the @@ -656,6 +657,16 @@ if (checkSelfPermission(Manifest.permission.READ_CONTACTS) } +

    + Note: When your app calls the framework's + requestPermissions() method, the system shows a standard dialog + box to the user. Your app cannot configure or alter that dialog box. + If you need to provide any information or explanation to the user, you should + do that before you call requestPermissions(), as + described in Explain why the app needs + permissions. +

    +

    Handle the permissions request response

    @@ -875,7 +886,105 @@ $ adb pm revoke <package_name> <permission_name> app's normal operation.

    -

    Normal Permissions

    +

    Support library methods for handling permissions

    + +

    + Revision 23 of the v4 and v13 support libraries provide several new methods + for managing permissions. The support library methods work properly on any + device that can use those libraries. Thus, if you use the support library + methods, you do not need to check whether your app is running on a device + with the M Developer Preview. If an app is installed on a device running the + M Preview, the support library methods behave the same as their framework + equivalents. If the device is running an earlier version of Android, the + methods behave appropriately, as described below. +

    + +

    + The v4 support library provides the following permissions methods: +

    + +
    +
    + ContextCompat.checkSelfPermission() +
    + +
    + Returns true if the app has the specified permission, whether + or not the device is using the M Preview. +
    + +
    + ActivityCompat.requestPermissions() +
    + +
    + If the device is not running the M Preview, invokes the callback + method in ActivityCompat.OnRequestPermissionsResultCallback. + Passes {@link android.content.pm.PackageManager#PERMISSION_GRANTED + PERMISSION_GRANTED} if the app already has the specified permission, or + {@link android.content.pm.PackageManager#PERMISSION_DENIED + PERMISSION_DENIED} if it does not. +
    + +
    + ActivityCompat.shouldShowRequestPermissionRationale() +
    + +
    + If the device is not running the M Preview, always returns + false. +
    +
    + +

    + The v4 support library also contains the PermissionChecker + class, which provides several static utility methods for apps that use IPC to + provide services for other apps. For example, + PermissionChecker.checkCallingPermission() checks whether an IPC + made by a particular package has a specified permission. +

    + +

    + Note: If your app acts on behalf of third-party apps to call + platform methods that require runtime permissions on behalf of a third-party + app, you should use the appropriate PermissionChecker methods to + ensure that the other app is allowed to perform the operation. The platform + has a compatibility mode that allows users to revoke a legacy app's access to + permission-protected methods. If the user revokes access in compatibility + mode the app's permissions are not actually revoked; instead, access to the + APIs is restricted. The PermissionChecker methods verify app + permissions in both normal and legacy modes. +

    + +

    + The v13 support library provides the following permissions methods: +

    + +
    +
    + FragmentCompat.requestPermissions() +
    + +
    + If the device is not running the M Preview, invokes the callback + method in FragmentCompat.OnRequestPermissionsResultCallback. + Passes {@link android.content.pm.PackageManager#PERMISSION_GRANTED + PERMISSION_GRANTED} if the app already has the specified permission, or + {@link android.content.pm.PackageManager#PERMISSION_DENIED + PERMISSION_DENIED} if it does not. +
    + +
    + FragmentCompat.shouldShowRequestPermissionRationale() +
    + +
    + If the device is not running the M Preview, always returns + false. +
    +
    + +

    Normal permissions

    Many permissions are designated as {@link @@ -911,6 +1020,7 @@ $ adb pm revoke <package_name> <permission_name>

    -- cgit v1.1