am b6af87ca: am e5bf7064: am 964a4121: Merge "[Improve docs for AccountManager] Currently, the docs for AccountManager are somewhat misleading and may cause developer errors. To avoid them, we are properly documenting it." into mnc-dev

* commit 'b6af87ca9009cc4891b6bc987103ef94184192e2':
  [Improve docs for AccountManager] Currently, the docs for AccountManager are somewhat misleading and may cause developer errors. To avoid them, we are properly documenting it.

core/java/android/accounts/AccountManager.java

@@ -321,6 +321,10 @@ public class AccountManager {
      * <p>This method requires the caller to have a signature match with the
      * authenticator that owns the specified account.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * AUTHENTICATE_ACCOUNTS permission is needed for those platforms. See docs for
+     * this function in API level 22.
+     *
      * @param account The account to query for a password. Must not be {@code null}.
      * @return The account's password, null if none or if the account doesn't exist
      */
@@ -345,6 +349,10 @@ public class AccountManager {
      * <p>This method requires the caller to have a signature match with the
      * authenticator that owns the specified account.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * AUTHENTICATE_ACCOUNTS permission is needed for those platforms. See docs
+     * for this function in API level 22.
+     *
      * @param account The account to query for user data
      * @return The user data, null if the account or key doesn't exist
      */
@@ -493,6 +501,10 @@ public class AccountManager {
      * {@link android.Manifest.permission#GET_ACCOUNTS} or share a uid with the
      * authenticator that owns the account type.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * GET_ACCOUNTS permission is needed for those platforms, irrespective of uid
+     * or signature match. See docs for this function in API level 22.
+     *
      * @param type The type of accounts to return, null to retrieve all accounts
      * @return An array of {@link Account}, one per matching account.  Empty
      *     (never null) if no accounts of the specified type have been added.
@@ -623,6 +635,11 @@ public class AccountManager {
      * @param type The type of accounts to return, must not be null
      * @param features An array of the account features to require,
      *     may be null or empty
+     *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * GET_ACCOUNTS permission is needed for those platforms, irrespective of uid
+     * or signature match. See docs for this function in API level 22.
+     *
      * @param callback Callback to invoke when the request completes,
      *     null for no callback
      * @param handler {@link Handler} identifying the callback thread,
@@ -668,6 +685,10 @@ public class AccountManager {
      * <p>This method requires the caller to have a signature match with the
      * authenticator that owns the specified account.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * AUTHENTICATE_ACCOUNTS permission is needed for those platforms. See docs
+     * for this function in API level 22.
+     *
      * @param account The {@link Account} to add
      * @param password The password to associate with the account, null for none
      * @param userdata String values to use for the account's userdata, null for
@@ -720,6 +741,10 @@ public class AccountManager {
      * <p>This method requires the caller to have a signature match with the
      * authenticator that manages the specified account.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * AUTHENTICATE_ACCOUNTS permission and same UID as account's authenticator
+     * is needed for those platforms. See docs for this function in API level 22.
+     *
      * @param account The {@link Account} to rename
      * @param newName String name to be associated with the account.
      * @param callback Callback to invoke when the request completes, null for
@@ -784,6 +809,10 @@ public class AccountManager {
      * <p>This method requires the caller to have a signature match with the
      * authenticator that manages the specified account.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * MANAGE_ACCOUNTS permission is needed for those platforms. See docs for
+     * this function in API level 22.
+     *
      * @param account The {@link Account} to remove
      * @param callback Callback to invoke when the request completes,
      *     null for no callback
@@ -826,6 +855,10 @@ public class AccountManager {
      * <p>This method requires the caller to have a signature match with the
      * authenticator that manages the specified account.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * MANAGE_ACCOUNTS permission is needed for those platforms. See docs for
+     * this function in API level 22.
+     *
      * @param account The {@link Account} to remove
      * @param activity The {@link Activity} context to use for launching a new
      *     authenticator-defined sub-Activity to prompt the user to delete an
@@ -919,6 +952,10 @@ public class AccountManager {
      * <p>This method requires the caller to have a signature match with the
      * authenticator that manages the specified account.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * AUTHENTICATE_ACCOUNTS permission and same UID as account's authenticator
+     * is needed for those platforms. See docs for this function in API level 22.
+     *
      * @param account The {@link Account} to delete.
      * @return True if the account was successfully deleted, false if the
      *         account did not exist, the account is null, or another error
@@ -943,6 +980,10 @@ public class AccountManager {
      *
      * <p>It is safe to call this method from the main thread.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * MANAGE_ACCOUNTS or USE_CREDENTIALS permission is needed for those
+     * platforms. See docs for this function in API level 22.
+     *
      * @param accountType The account type of the auth token to invalidate, must not be null
      * @param authToken The auth token to invalidate, may be null
      */
@@ -969,6 +1010,10 @@ public class AccountManager {
      * <p>This method requires the caller to have a signature match with the
      * authenticator that manages the specified account.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * AUTHENTICATE_ACCOUNTS permission and same UID as account's authenticator
+     * is needed for those platforms. See docs for this function in API level 22.
+     *
      * @param account The account for which an auth token is to be fetched. Cannot be {@code null}.
      * @param authTokenType The type of auth token to fetch. Cannot be {@code null}. 
      * @return The cached auth token for this account and type, or null if
@@ -998,6 +1043,10 @@ public class AccountManager {
      * <p>This method requires the caller to have a signature match with the
      * authenticator that manages the specified account.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * AUTHENTICATE_ACCOUNTS permission and same UID as account's authenticator
+     * is needed for those platforms. See docs for this function in API level 22.
+     *
      * @param account The account whose password is to be set. Cannot be
      *            {@code null}.
      * @param password The password to set, null to clear the password
@@ -1025,6 +1074,10 @@ public class AccountManager {
      *
      * <p>It is safe to call this method from the main thread.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * MANAGE_ACCOUNTS permission is needed for those platforms. See docs for
+     * this function in API level 22.
+     *
      * @param account The account whose password to clear
      */
     public void clearPassword(final Account account) {
@@ -1047,6 +1100,10 @@ public class AccountManager {
      * <p>This method requires the caller to have a signature match with the
      * authenticator that manages the specified account.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * AUTHENTICATE_ACCOUNTS permission and same UID as account's authenticator
+     * is needed for those platforms. See docs for this function in API level 22.
+     *
      * @param account Account whose user data is to be set. Must not be {@code null}.
      * @param key String user data key to set.  Must not be null
      * @param value String value to set, {@code null} to clear this user data key
@@ -1073,6 +1130,10 @@ public class AccountManager {
      * <p>This method requires the caller to have a signature match with the
      * authenticator that manages the specified account.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * AUTHENTICATE_ACCOUNTS permission and same UID as account's authenticator
+     * is needed for those platforms. See docs for this function in API level 22.
+     *
      * @param account The account to set an auth token for
      * @param authTokenType The type of the auth token, see {#getAuthToken}
      * @param authToken The auth token to add to the cache
@@ -1095,6 +1156,10 @@ public class AccountManager {
      * <p>This method may block while a network request completes, and must
      * never be made from the main thread.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * USE_CREDENTIALS permission is needed for those platforms. See docs for
+     * this function in API level 22.
+     *
      * @param account The account to fetch an auth token for
      * @param authTokenType The auth token type, see {@link #getAuthToken getAuthToken()}
      * @param notifyAuthFailure If true, display a notification and return null
@@ -1143,6 +1208,10 @@ public class AccountManager {
      * access different functionality -- for example, Google uses different auth
      * tokens to access Gmail and Google Calendar for the same account.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * USE_CREDENTIALS permission is needed for those platforms. See docs for 
+     * this function in API level 22.
+     *
      * <p>This method may be called from any thread, but the returned
      * {@link AccountManagerFuture} must not be used on the main thread.
      *
@@ -1306,6 +1375,10 @@ public class AccountManager {
      * <p>This method may be called from any thread, but the returned
      * {@link AccountManagerFuture} must not be used on the main thread.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * USE_CREDENTIALS permission is needed for those platforms. See docs for 
+     * this function in API level 22.
+     *
      * @param account The account to fetch an auth token for
      * @param authTokenType The auth token type, an authenticator-dependent
      *     string token, must not be null
@@ -1369,6 +1442,10 @@ public class AccountManager {
      *
      * <p>This method may be called from any thread, but the returned
      * {@link AccountManagerFuture} must not be used on the main thread.
+     * 
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * MANAGE_ACCOUNTS permission is needed for those platforms. See docs for
+     * this function in API level 22.
      *
      * @param accountType The type of account to add; must not be null
      * @param authTokenType The type of auth token (see {@link #getAuthToken})
@@ -1551,6 +1628,10 @@ public class AccountManager {
      * <p>This method may be called from any thread, but the returned
      * {@link AccountManagerFuture} must not be used on the main thread.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * MANAGE_ACCOUNTS permission is needed for those platforms. See docs
+     * for this function in API level 22.
+     *
      * @param account The account to confirm password knowledge for
      * @param options Authenticator-specific options for the request;
      *     if the {@link #KEY_PASSWORD} string field is present, the
@@ -1629,6 +1710,10 @@ public class AccountManager {
      * <p>This method may be called from any thread, but the returned
      * {@link AccountManagerFuture} must not be used on the main thread.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * MANAGE_ACCOUNTS permission is needed for those platforms. See docs for
+     * this function in API level 22.
+     *
      * @param account The account to update credentials for
      * @param authTokenType The credentials entered must allow an auth token
      *     of this type to be created (but no actual auth token is returned);
@@ -1689,6 +1774,10 @@ public class AccountManager {
      * <p>This method requires the caller to have the same signature as the
      * authenticator associated with the specified account type.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * MANAGE_ACCOUNTS permission is needed for those platforms. See docs
+     * for this function in API level 22.
+     *
      * @param accountType The account type associated with the authenticator
      *     to adjust
      * @param activity The {@link Activity} context to use for launching a new
@@ -2209,6 +2298,10 @@ public class AccountManager {
      * <p>This method may be called from any thread, but the returned
      * {@link AccountManagerFuture} must not be used on the main thread.
      *
+     * <p><b>NOTE:</b> If targeting your app to work on API level 22 and before,
+     * MANAGE_ACCOUNTS permission is needed for those platforms. See docs for
+     * this function in API level 22.
+     *
      * @param accountType The account type required
      *     (see {@link #getAccountsByType}), must not be null
      * @param authTokenType The desired auth token type