Merge "COMMENT ONLY change to fix some formatting glitches and (more...

/**

 * This class provides access to a centralized registry of the user's

 * online accounts.  With this service, users only need to enter their

 * credentials (username and password) once for any account, granting

 * applications access to online resources with "one-click" approval.

 * online accounts.  The user enters credentials (username and password) once

 * per account, granting applications access to online resources with

 * "one-click" approval.

 *

 * <p>Different online services have different ways of handling accounts and

 * authentication, so the account manager uses pluggable <em>authenticator</em>

 * modules for different <em>account types</em>.  The authenticators (which

 * may be written by third parties) handle the actual details of validating

 * account credentials and storing account information.  For example, Google,

 * Facebook, and Microsoft Exchange each have their own authenticator.

 * modules for different <em>account types</em>.  Authenticators (which may be

 * written by third parties) handle the actual details of validating account

 * credentials and storing account information.  For example, Google, Facebook,

 * and Microsoft Exchange each have their own authenticator.

 *

 * <p>Many servers support some notion of an <em>authentication token</em>,

 * which can be used to authenticate a request to the server without sending

 * the user's actual password.  (Auth tokens are normally created with a

 * separate request which does include the user's credentials.)  AccountManager

 * can generate these auth tokens for applications, so the application doesn't

 * need to handle passwords directly.  Auth tokens are normally reusable, and

 * cached by AccountManager, but must be refreshed periodically.  It's the

 * responsibility of applications to <em>invalidate</em> auth tokens when they

 * stop working so the AccountManager knows it needs to regenerate them.

 * can generate auth tokens for applications, so the application doesn't need to

 * handle passwords directly.  Auth tokens are normally reusable and cached by

 * AccountManager, but must be refreshed periodically.  It's the responsibility

 * of applications to <em>invalidate</em> auth tokens when they stop working so

 * the AccountManager knows it needs to regenerate them.

 *

 * <p>Applications accessing a server normally go through these steps:

 *

 * {@link #addAccount} may be called to prompt the user to create an

 * account of the appropriate type.

 *

 * <li><b>Important:</b> If the application is using a previously remembered

 * account selection, it must make sure the account is still in the list

 * of accounts returned by {@link #getAccountsByType}.  Requesting an auth token

 * for an account no longer on the device results in an undefined failure.

 *

 * <li>Request an auth token for the selected account(s) using one of the

 * {@link #getAuthToken} methods or related helpers.  Refer to the description

 * of each method for exact usage and error handling details.

 *

 * <li>Make the request using the auth token.  The form of the auth token,

 * the format of the request, and the protocol used are all specific to the

 * service you are accessing.  The application makes the request itself, using

 * whatever network and protocol libraries are useful.

 * service you are accessing.  The application may use whatever network and

 * protocol libraries are useful.

 *

 * <li><b>Important:</b> If the request fails with an authentication error,

 * it could be that a cached auth token is stale and no longer honored by

 * appropriate actions taken.

 * </ul>

 *

 * <p>Some AccountManager methods may require interaction with the user to

 * <p>Some AccountManager methods may need to interact with the user to

 * prompt for credentials, present options, or ask the user to add an account.

 * The caller may choose whether to allow AccountManager to directly launch the

 * necessary user interface and wait for the user, or to return an Intent which

 * the current foreground {@link Activity} context.

 *

 * <p>Many AccountManager methods take {@link AccountManagerCallback} and

 * {@link Handler} as parameters.  These methods return immediately but

 * {@link Handler} as parameters.  These methods return immediately and

 * run asynchronously. If a callback is provided then

 * {@link AccountManagerCallback#run} will be invoked on the Handler's

 * thread when the request completes, successfully or not.

 * An {@link AccountManagerFuture} is returned by these requests and also

 * supplied to the callback (if any).  The result is retrieved by calling

 * {@link AccountManagerFuture#getResult()} which waits for the operation

 * to complete (if necessary) and either returns the result or throws an

 * exception if an error occurred during the operation.

 * To make the request synchronously, call

 * The result is retrieved by calling {@link AccountManagerFuture#getResult()}

 * on the {@link AccountManagerFuture} returned by the method (and also passed

 * to the callback).  This method waits for the operation to complete (if

 * necessary) and either returns the result or throws an exception if an error

 * occurred during the operation.  To make the request synchronously, call

 * {@link AccountManagerFuture#getResult()} immediately on receiving the

 * future from the method.  No callback need be supplied.

 * future from the method; no callback need be supplied.

 *

 * <p>Requests which may block, including

 * {@link AccountManagerFuture#getResult()}, must never be called on

    public static final int ERROR_CODE_BAD_REQUEST = 8;

    /**

     * The Bundle key used for the {@link String} account name in results

     * Bundle key used for the {@link String} account name in results

     * from methods which return information about a particular account.

     */

    public static final String KEY_ACCOUNT_NAME = "authAccount";

    /**

     * The Bundle key used for the {@link String} account type in results

     * Bundle key used for the {@link String} account type in results

     * from methods which return information about a particular account.

     */

    public static final String KEY_ACCOUNT_TYPE = "accountType";

    /**

     * The Bundle key used for the auth token value in results

     * Bundle key used for the auth token value in results

     * from {@link #getAuthToken} and friends.

     */

    public static final String KEY_AUTHTOKEN = "authtoken";

    /**

     * The Bundle key used for an {@link Intent} in results from methods that

     * Bundle key used for an {@link Intent} in results from methods that

     * may require the caller to interact with the user.  The Intent can

     * be used to start the corresponding user interface activity.

     */

    public static final String KEY_INTENT = "intent";

    /**

     * The Bundle key used to supply the password directly in options to

     * Bundle key used to supply the password directly in options to

     * {@link #confirmCredentials}, rather than prompting the user with

     * the standard password prompt.

     */

     * @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 none

     * @return Whether the account was successfully added.  False if the account

     * @return True if the account was successfully added, false if the account

     *     already exists, the account is null, or another error occurs.

     */

    public boolean addAccountExplicitly(Account account, String password, Bundle userdata) {

     * sense to ask the user directly for a password.

     *

     * <p>If a previously generated auth token is cached for this account and

     * type, then it will be returned.  Otherwise, if we have a saved password

     * the server accepts, it will be used to generate a new auth token.

     * Otherwise, the user will be asked for a password, which will be sent to

     * the server to generate a new auth token.

     * type, then it is returned.  Otherwise, if a saved password is

     * available, it is sent to the server to generate a new auth token.

     * Otherwise, the user is prompted to enter a password.

     *

     * <p>The value of the auth token type depends on the authenticator.

     * Some services use different tokens to access different functionality --

     * for example, Google uses different auth tokens to access Gmail and

     * Google Calendar for the same account.

     * <p>Some authenticators have auth token <em>types</em>, whose value

     * is authenticator-dependent.  Some services use different token types to

     * access different functionality -- for example, Google uses different auth

     * tokens to access Gmail and Google Calendar for the same account.

     *

     * <p>This method may be called from any thread, but the returned

     * {@link AccountManagerFuture} must not be used on the main thread.

     * <li> {@link IOException} if the authenticator experienced an I/O problem

     *      creating a new auth token, usually because of network trouble

     * </ul>

     * If the account is no longer present on the device, the return value is

     * authenticator-dependent.  The caller should verify the validity of the

     * account before requesting an auth token.

     */

    public AccountManagerFuture<Bundle> getAuthToken(

            final Account account, final String authTokenType, final Bundle options,

     * user should not be immediately interrupted with a password prompt.

     *

     * <p>If a previously generated auth token is cached for this account and

     * type, then it will be returned.  Otherwise, if we have saved credentials

     * the server accepts, it will be used to generate a new auth token.

     * Otherwise, an Intent will be returned which, when started, will prompt

     * the user for a password.  If the notifyAuthFailure parameter is set,

     * the same Intent will be associated with a status bar notification,

     * type, then it is returned.  Otherwise, if a saved password is

     * available, it is sent to the server to generate a new auth token.

     * Otherwise, an {@link Intent} is returned which, when started, will

     * prompt the user for a password.  If the notifyAuthFailure parameter is

     * set, a status bar notification is also created with the same Intent,

     * alerting the user that they need to enter a password at some point.

     *

     * <p>If the intent is left in a notification, you will need to wait until

     * the user gets around to entering a password before trying again,

     * which could be hours or days or never.  When it does happen, the

     * account manager will broadcast the {@link #LOGIN_ACCOUNTS_CHANGED_ACTION}

     * {@link Intent}, which applications can use to trigger another attempt

     * to fetch an auth token.

     * <p>In that case, you may need to wait until the user responds, which

     * could take hours or days or forever.  When the user does respond and

     * supply a new password, the account manager will broadcast the

     * {@link #LOGIN_ACCOUNTS_CHANGED_ACTION} Intent, which applications can

     * use to try again.

     *

     * <p>If notifications are not enabled, it is the application's

     * responsibility to launch the returned intent at some point to let

     * the user enter credentials.  In either case, the result from this

     * call will not wait for user action.

     * <p>If notifyAuthFailure is not set, it is the application's

     * responsibility to launch the returned Intent at some point.

     * Either way, the result from this call will not wait for user action.

     *

     * <p>The value of the auth token type depends on the authenticator.

     * Some services use different tokens to access different functionality --

     * for example, Google uses different auth tokens to access Gmail and

     * Google Calendar for the same account.

     * <p>Some authenticators have auth token <em>types</em>, whose value

     * is authenticator-dependent.  Some services use different token types to

     * access different functionality -- for example, Google uses different auth

     * tokens to access Gmail and Google Calendar for the same account.

     *

     * <p>This method may be called from any thread, but the returned

     * {@link AccountManagerFuture} must not be used on the main thread.

     * must enter credentials, the returned Bundle contains only

     * {@link #KEY_INTENT} with the {@link Intent} needed to launch a prompt.

     *

     * <p>If an error occurred, {@link AccountManagerFuture#getResult()} throws:

     * If an error occurred, {@link AccountManagerFuture#getResult()} throws:

     * <ul>

     * <li> {@link AuthenticatorException} if the authenticator failed to respond

     * <li> {@link OperationCanceledException} if the operation is canceled for

     * <li> {@link IOException} if the authenticator experienced an I/O problem

     *      creating a new auth token, usually because of network trouble

     * </ul>

     * If the account is no longer present on the device, the return value is

     * authenticator-dependent.  The caller should verify the validity of the

     * account before requesting an auth token.

     */

    public AccountManagerFuture<Bundle> getAuthToken(

            final Account account, final String authTokenType, final boolean notifyAuthFailure,

     *

     * If no activity was specified, the returned Bundle contains only

     * {@link #KEY_INTENT} with the {@link Intent} needed to launch the

     * actual account creation process.

     *

     * <p>If an error occurred, {@link AccountManagerFuture#getResult()} throws:

     * actual account creation process.  If an error occurred,

     * {@link AccountManagerFuture#getResult()} throws:

     * <ul>

     * <li> {@link AuthenticatorException} if no authenticator was registered for

     *      this account type or the authenticator failed to respond

     *

     * If no activity or password was specified, the returned Bundle contains

     * only {@link #KEY_INTENT} with the {@link Intent} needed to launch the

     * password prompt.

     *

     * <p>If an error occurred, {@link AccountManagerFuture#getResult()} throws:

     * password prompt.  If an error occurred,

     * {@link AccountManagerFuture#getResult()} throws:

     * <ul>

     * <li> {@link AuthenticatorException} if the authenticator failed to respond

     * <li> {@link OperationCanceledException} if the operation was canceled for

     *

     * If no activity was specified, the returned Bundle contains only

     * {@link #KEY_INTENT} with the {@link Intent} needed to launch the

     * password prompt.

     *

     * <p>If an error occurred, {@link AccountManagerFuture#getResult()} throws:

     * password prompt.  If an error occurred,

     * {@link AccountManagerFuture#getResult()} throws:

     * <ul>

     * <li> {@link AuthenticatorException} if the authenticator failed to respond

     * <li> {@link OperationCanceledException} if the operation was canceled for

     *     which is empty if properties were edited successfully, or

     *     if no activity was specified, contains only {@link #KEY_INTENT}

     *     needed to launch the authenticator's settings dialog.

     *

     * <p>If an error occurred, {@link AccountManagerFuture#getResult()} throws:

     *     If an error occurred, {@link AccountManagerFuture#getResult()}

     *     throws:

     * <ul>

     * <li> {@link AuthenticatorException} if no authenticator was registered for

     *      this account type or the authenticator failed to respond

     * <li> {@link #KEY_AUTHTOKEN} - the auth token you wanted

     * </ul>

     *

     * <p>If an error occurred, {@link AccountManagerFuture#getResult()} throws:

     * If an error occurred, {@link AccountManagerFuture#getResult()} throws:

     * <ul>

     * <li> {@link AuthenticatorException} if no authenticator was registered for

     *      this account type or the authenticator failed to respond