Merge "docs: Added Javadoc links for new M Preview permissions methods" into mnc-dev

docs/html/preview/features/runtime-permissions.jd

@@ -180,12 +180,13 @@ page.image=images/permissions_check.png
 <h3 id="perm-groups">Permission groups</h3>
 
 <p>
-  Related permissions are divided into <em>permission groups</em> to
+  Related permissions are divided into <em>permission groups</em> to allow
-  allow users to grant related permissions to an app in a single action.
+  users to grant related permissions to an app in a single action. The user
-  The user only has to grant permission once per app for each permission group.
+  only has to grant permission once per app for each permission group. If the
-  If the app subsequently requests a permission from the same permission
+  app subsequently requests a permission from the same permission group, the
-  group, the system automatically grants the permission without any action from
+  system automatically grants the permission without any action from the user.
-  the user. The system calls your app's <code>onRequestPermissionsResult()</code>
+  The system calls your app's {@link
+  android.app.Activity#onRequestPermissionsResult onRequestPermissionsResult()}
   method just as if the user had granted permission through the dialog box.
 </p>
 
@@ -376,7 +377,8 @@ page.image=images/permissions_check.png
 <p>
   If the app is running on a device with the M Developer Preview,
   <code>&lt;uses-permission-sdk-m&gt;</code> behaves the same as
-  <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code>.
+  <code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"
+      >&lt;uses-permission&gt;</a></code>.
   The system does not prompt the user to grant any permissions when they install
   the app, and the app requests permissions as they are needed.
 </p>
@@ -421,15 +423,16 @@ page.image=images/permissions_check.png
 
 <h4 id="check-for-permission">Check if the app has the needed permission</h4>
 
-<p>When the user tries to do something that requires a permission, the app
+<p>
+  When the user tries to do something that requires a permission, the app
   checks to see if it currently has permission to perform this operation. To do
-  this, the app calls
+  this, the app calls {@link android.content.Context#checkSelfPermission
-  <code>Context.checkSelfPermission(<i>permission_name</i>)</code>. The app
+  checkSelfPermission()}. The app should perform this check even if it knows
-  should perform this check even if it knows the user has already granted that
+  the user has already granted that permission, since the user can revoke an
-  permission,
+  app's permissions at any time. For example, if a user wants to use an app to
-  since the user can revoke an app's permissions at any time. For example, if a
+  take a picture, the app calls
-  user wants to use an app to take a picture, the app calls
+  <code>Context.checkSelfPermission(Manifest.permission.CAMERA)</code>.
-  <code>Context.checkSelfPermission(Manifest.permission.CAMERA)</code>.</p>
+</p>
 
 <p class="table-caption" id="permission-groups">
   <strong>Table 1.</strong> Permissions and permission groups.</p>
@@ -605,13 +608,12 @@ page.image=images/permissions_check.png
 
 <p>
   To help find the situations where you need to provide extra explanation, the
-  system provides the
+  system provides the {@link
-  <code>Activity.shouldShowRequestPermissionRationale(String)</code>
+  android.app.Activity#shouldShowRequestPermissionRationale
-  method. This
+  shouldShowRequestPermissionRationale()} method. This method returns
-  method returns <code>true</code> if the app has requested this permission
+  <code>true</code> if the app has requested this permission previously and the
-  previously and the user denied the request.
+  user denied the request. That indicates that you should probably explain to
-  That indicates that you should probably explain to the
+  the user why you need the permission.
-  user why you need the permission.
 </p>
 
 <p>
@@ -626,13 +628,13 @@ page.image=images/permissions_check.png
 <h4 id="request-permissions">Request permissions if necessary</h4>
 
 <p>If the app doesn't already have the permission it needs, the app calls the
-  <code>Activity.requestPermissions(String[], int)</code> method to
+  {@link android.app.Activity#requestPermissions requestPermissions()} method to
   request the appropriate permission or permissions. The app passes the
   permission or permissions it wants, and also an integer "request code".
   This method functions asynchronously: it returns right away, and after
   the user responds to the dialog box, the system calls the app's callback
   method with the results, passing the same "request code" that the app passed
-  to <code>requestPermissions()</code>.</p>
+  to {@link android.app.Activity#requestPermissions requestPermissions()}.</p>
 
   <p>The following code code checks if the app has permission to read the
     user's contacts, and requests the permission if necessary:</p>
@@ -658,26 +660,26 @@ if (checkSelfPermission(Manifest.permission.READ_CONTACTS)
 </pre>
 
 <p class="note">
-  <strong>Note:</strong> When your app calls the framework's
+  <strong>Note:</strong> When your app calls the framework's {@link
-  <code>requestPermissions()</code> method, the system shows a standard dialog
+  android.app.Activity#requestPermissions requestPermissions()} method, the
-  box to the user. Your app <em>cannot</em> configure or alter that dialog box.
+  system shows a standard dialog box to the user. Your app <em>cannot</em>
-  If you need to provide any information or explanation to the user, you should
+  configure or alter that dialog box. If you need to provide any information or
-  do that <em>before</em> you call <code>requestPermissions()</code>, as
+  explanation to the user, you should do that <em>before</em> you call {@link
-  described in <a href="#explain-need">Explain why the app needs
+  android.app.Activity#requestPermissions requestPermissions()}, as described
-  permissions</a>.
+  in <a href="#explain-need">Explain why the app needs permissions</a>.
 </p>
 
 <h4 id="handle-response">Handle the permissions request response</h4>
 
 <p>
   When an app requests permissions, the system presents a dialog box to the
-  user. When the user responds, the system invokes your app's
+  user. When the user responds, the system invokes your app's {@link
-  <code>Activity.onRequestPermissionsResult(int, String[], int[])</code>
+  android.app.Activity#onRequestPermissionsResult} passing it the user
-  passing it the user response. Your app needs to override that method. The
+  response. Your app needs to override that method. The callback is passed the
-  callback is passed the same request code you passed to
+  same request code you passed to {@link
-  <code>requestPermissions()</code>. For example, if an app requests
+  android.app.Activity#requestPermissions requestPermissions()}. For example,
-  <code>READ_CONTACTS</code> access it might have the following callback
+  if an app requests <code>READ_CONTACTS</code> access it might have the
-  method:
+  following callback method:
 </p>
 
 <pre>
@@ -714,11 +716,13 @@ public void onRequestPermissionsResult(int requestCode,
 <p>
   When the system asks the user to grant a permission, the user has the option
   of telling the system not to ask for that permission again. In that case,
-  when an app uses <code>requestPermissions()</code> to ask for that permission,
+  when an app uses {@link android.app.Activity#requestPermissions
-  the system immediately denies the request. In this case, the system calls
+  requestPermissions()} to ask for that permission, the system immediately
-  your <code>onRequestPermissionsResult()</code> the same way it would if the
+  denies the request. In this case, the system calls your {@link
-  user had explicitly rejected your request again. For this reason, your app
+  android.app.Activity#onRequestPermissionsResult onRequestPermissionsResult()}
-  cannot assume that any direct interaction with the user has taken place.
+  the same way it would if the user had explicitly rejected your request again.
+  For this reason, your app cannot assume that any direct interaction with the
+  user has taken place.
 </p>
 
 <h2 id="testing">Testing Runtime Permissions</h2>
@@ -858,11 +862,12 @@ $ adb pm revoke &lt;package_name&gt; &lt;permission_name&gt;
 </h3>
 
 <p>
-  The permissions dialog shown by the system when you call
+  The permissions dialog shown by the system when you call {@link
-  <code>requestPermissions()</code> says what permission your app wants, but
+  android.app.Activity#requestPermissions requestPermissions()} says what
-  doesn't say why. In some cases, the user may find that puzzling.
+  permission your app wants, but doesn't say why. In some cases, the user may
-  It's a good idea to explain to the user why your app wants the permissions
+  find that puzzling. It's a good idea to explain to the user why your app
-  before calling <code>requestPermissions()</code>.
+  wants the permissions before calling {@link
+  android.app.Activity#requestPermissions requestPermissions()}.
 </p>
 
 <p>
@@ -871,7 +876,7 @@ $ adb pm revoke &lt;package_name&gt; &lt;permission_name&gt;
   contain location information, and would be puzzled why their photography app
   wanted to know the location. So in this case, it's a good idea for the app to
   tell the user about this feature <em>before</em> calling
-  <code>requestPermissions()</code>.
+  {@link android.app.Activity#requestPermissions requestPermissions()}.
 </p>
 
 <p>
@@ -880,10 +885,11 @@ $ adb pm revoke &lt;package_name&gt; &lt;permission_name&gt;
   can explain what permissions are needed. For example, the photography app's
   tutorial can demonstrate its "share photos with your contacts" feature, then
   tell the user that they need to give permission for the app to see the user's
-  contacts. The app can then call <code>requestPermissions()</code> to ask the
+  contacts. The app can then call {@link
-  user for that access. Of course, not every user is going to follow the
+  android.app.Activity#requestPermissions requestPermissions()} to ask the user
-  tutorial, so you still need to check for and request permissions during the
+  for that access. Of course, not every user is going to follow the tutorial,
-  app's normal operation.
+  so you still need to check for and request permissions during the app's
+  normal operation.
 </p>
 
 <h3 id="support-lib">Support library methods for handling permissions</h3>
@@ -905,7 +911,8 @@ $ adb pm revoke &lt;package_name&gt; &lt;permission_name&gt;
 
 <dl>
   <dt>
-    <code>ContextCompat.checkSelfPermission()</code>
+    {@link android.support.v4.content.ContextCompat#checkSelfPermission
+    ContextCompat.checkSelfPermission()}
   </dt>
 
   <dd>
@@ -914,12 +921,14 @@ $ adb pm revoke &lt;package_name&gt; &lt;permission_name&gt;
   </dd>
 
   <dt>
-    <code>ActivityCompat.requestPermissions()</code>
+    {@link android.support.v4.app.ActivityCompat#requestPermissions
+    ActivityCompat.requestPermissions()}
   </dt>
 
   <dd>
     If the device is not running the M Preview, invokes the callback
-    method in <code>ActivityCompat.OnRequestPermissionsResultCallback</code>.
+    method in {@link
+    android.support.v4.app.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
@@ -927,7 +936,9 @@ $ adb pm revoke &lt;package_name&gt; &lt;permission_name&gt;
   </dd>
 
   <dt>
-    <code>ActivityCompat.shouldShowRequestPermissionRationale()</code>
+    {@link
+    android.support.v4.app.ActivityCompat#shouldShowRequestPermissionRationale
+    ActivityCompat.shouldShowRequestPermissionRationale()}
   </dt>
 
   <dd>
@@ -937,23 +948,27 @@ $ adb pm revoke &lt;package_name&gt; &lt;permission_name&gt;
 </dl>
 
 <p>
-  The v4 support library also contains the <code>PermissionChecker</code>
+  The v4 support library also contains the
+  {@link android.support.v4.content.PermissionChecker}
   class, which provides several static utility methods for apps that use IPC to
   provide services for other apps. For example,
-  <code>PermissionChecker.checkCallingPermission()</code> checks whether an IPC
+  {@link android.support.v4.content.PermissionChecker#checkCallingPermission
+  PermissionChecker.checkCallingPermission()}
+  checks whether an IPC
   made by a particular package has a specified permission.
 </p>
 
 <p class="note">
   <strong>Note:</strong> 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 <code>PermissionChecker</code> methods to
+  app, you should use the appropriate {@link
-  ensure that the other app is allowed to perform the operation. The platform
+  android.support.v4.content.PermissionChecker} methods to ensure that the
-  has a compatibility mode that allows users to revoke a legacy app's access to
+  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 <code>PermissionChecker</code> methods verify app
+  APIs is restricted. The {@link android.support.v4.content.PermissionChecker}
-  permissions in both normal and legacy modes.
+  methods verify app permissions in both normal and legacy modes.
 </p>
 
 <p>
@@ -962,7 +977,8 @@ $ adb pm revoke &lt;package_name&gt; &lt;permission_name&gt;
 
 <dl>
   <dt>
-    <code>FragmentCompat.requestPermissions()</code>
+    {@link android.support.v13.app.FragmentCompat#requestPermissions
+    FragmentCompat.requestPermissions()}
   </dt>
 
   <dd>
@@ -975,7 +991,9 @@ $ adb pm revoke &lt;package_name&gt; &lt;permission_name&gt;
   </dd>
 
   <dt>
-    <code>FragmentCompat.shouldShowRequestPermissionRationale()</code>
+    {@link
+    android.support.v13.app.FragmentCompat#shouldShowRequestPermissionRationale
+    FragmentCompat.shouldShowRequestPermissionRationale()}
   </dt>
 
   <dd>
@@ -1007,11 +1025,12 @@ $ adb pm revoke &lt;package_name&gt; &lt;permission_name&gt;
 </p>
 
 <p>
-  If your app declares that it needs normal permissions, the app does not need to
+  If your app declares that it needs normal permissions, the app does not need
-  call <code>Activity.checkSelfPermission()</code> or
+  to call {@link android.content.Context#checkSelfPermission
-  <code>Activity.requestPermissions()</code> for
+  checkSelfPermission()} or {@link android.app.Activity#requestPermissions
-  those permissions. Since you declared the permissions in the manifest, you
+  requestPermissions()} for those permissions. Since you declared the
-  can be sure your app was granted those permissions at install time.
+  permissions in the manifest, you can be sure your app was granted those
+  permissions at install time.
 </p>
 
 <p>Currently, the following permissions are classified as {@link