diff options
Diffstat (limited to 'core/java/android/accounts/AccountManager.java')
| -rw-r--r-- | core/java/android/accounts/AccountManager.java | 474 |
1 files changed, 460 insertions, 14 deletions
diff --git a/core/java/android/accounts/AccountManager.java b/core/java/android/accounts/AccountManager.java index d032449..153d95f 100644 --- a/core/java/android/accounts/AccountManager.java +++ b/core/java/android/accounts/AccountManager.java @@ -42,13 +42,34 @@ import java.util.Map; import com.google.android.collect.Maps; /** - * A class that helps with interactions with the AccountManagerService. It provides + * A class that helps with interactions with the AccountManager Service. It provides * methods to allow for account, password, and authtoken management for all accounts on the * device. One accesses the {@link AccountManager} by calling: + * <pre> * AccountManager accountManager = AccountManager.get(context); + * </pre> * * <p> - * TODO(fredq) this interface is still in flux + * The AccountManager Service provides storage for the accounts known to the system, + * provides methods to manage them, and allows the registration of authenticators to + * which operations such as addAccount and getAuthToken are delegated. + * <p> + * Many of the calls take an {@link AccountManagerCallback} and {@link Handler} as parameters. + * These calls return immediately but run asynchronously. If a callback is provided then + * {@link AccountManagerCallback#run} will be invoked wen the request completes, successfully + * or not. An {@link AccountManagerFuture} is returned by these requests and also passed into the + * callback. The result if retrieved by calling {@link AccountManagerFuture#getResult()} which + * either returns the result or throws an exception as appropriate. + * <p> + * The asynchronous request can be made blocking by not providing a callback and instead + * calling {@link AccountManagerFuture#getResult()} on the future that is returned. This will + * cause the running thread to block until the result is returned. Keep in mind that one + * should not block the main thread in this way. Instead one should either use a callback, + * thus making the call asynchronous, or make the blocking call on a separate thread. + * <p> + * If one wants to ensure that the callback is invoked from a specific handler then they should + * pass the handler to the request. This makes it easier to ensure thread-safety by running + * all of one's logic from a single handler. */ public class AccountManager { private static final String TAG = "AccountManager"; @@ -60,6 +81,7 @@ public class AccountManager { public static final int ERROR_CODE_UNSUPPORTED_OPERATION = 6; public static final int ERROR_CODE_BAD_ARGUMENTS = 7; public static final int ERROR_CODE_BAD_REQUEST = 8; + public static final String KEY_ACCOUNTS = "accounts"; public static final String KEY_AUTHENTICATOR_TYPES = "authenticator_types"; public static final String KEY_USERDATA = "userdata"; @@ -110,10 +132,26 @@ public class AccountManager { mMainHandler = handler; } + /** + * Retrieve an AccountManager instance that is associated with the context that is passed in. + * Certain calls such as {@link #addOnAccountsUpdatedListener} use this context internally, + * so the caller must take care to use a {@link Context} whose lifetime is associated with + * the listener registration. + * @param context The {@link Context} to use when necessary + * @return an {@link AccountManager} instance that is associated with context + */ public static AccountManager get(Context context) { return (AccountManager) context.getSystemService(Context.ACCOUNT_SERVICE); } + /** + * Get the password that is associated with the account. Returns null if the account does + * not exist. + * <p> + * Requires that the caller has permission + * {@link android.Manifest.permission#AUTHENTICATE_ACCOUNTS} and is running + * with the same UID as the Authenticator for the account. + */ public String getPassword(final Account account) { try { return mService.getPassword(account); @@ -123,6 +161,14 @@ public class AccountManager { } } + /** + * Get the user data named by "key" that is associated with the account. + * Returns null if the account does not exist or if it does not have a value for key. + * <p> + * Requires that the caller has permission + * {@link android.Manifest.permission#AUTHENTICATE_ACCOUNTS} and is running + * with the same UID as the Authenticator for the account. + */ public String getUserData(final Account account, final String key) { try { return mService.getUserData(account, key); @@ -132,6 +178,14 @@ public class AccountManager { } } + /** + * Query the AccountManager Service for an array that contains a + * {@link AuthenticatorDescription} for each registered authenticator. + * @return an array that contains all the authenticators known to the AccountManager service. + * This array will be empty if there are no authenticators and will never return null. + * <p> + * No permission is required to make this call. + */ public AuthenticatorDescription[] getAuthenticatorTypes() { try { return mService.getAuthenticatorTypes(); @@ -141,6 +195,13 @@ public class AccountManager { } } + /** + * Query the AccountManager Service for all accounts. + * @return an array that contains all the accounts known to the AccountManager service. + * This array will be empty if there are no accounts and will never return null. + * <p> + * Requires that the caller has permission {@link android.Manifest.permission#GET_ACCOUNTS} + */ public Account[] getAccounts() { try { return mService.getAccounts(null); @@ -150,6 +211,15 @@ public class AccountManager { } } + /** + * Query the AccountManager for the set of accounts that have a given type. If null + * is passed as the type than all accounts are returned. + * @param type the account type by which to filter, or null to get all accounts + * @return an array that contains the accounts that match the specified type. This array + * will be empty if no accounts match. It will never return null. + * <p> + * Requires that the caller has permission {@link android.Manifest.permission#GET_ACCOUNTS} + */ public Account[] getAccountsByType(String type) { try { return mService.getAccounts(type); @@ -159,6 +229,18 @@ public class AccountManager { } } + /** + * Add an account to the AccountManager's set of known accounts. + * <p> + * Requires that the caller has permission + * {@link android.Manifest.permission#AUTHENTICATE_ACCOUNTS} and is running + * with the same UID as the Authenticator for the account. + * @param account The account to add + * @param password The password to associate with the account. May be null. + * @param extras A bundle of key/value pairs to set as the account's userdata. May be null. + * @return true if the account was sucessfully added, false otherwise, for example, + * if the account already exists or if the account is null + */ public boolean addAccountExplicitly(Account account, String password, Bundle extras) { try { return mService.addAccount(account, password, extras); @@ -168,6 +250,29 @@ public class AccountManager { } } + /** + * Removes the given account. If this account does not exist then this call has no effect. + * <p> + * This call returns immediately but runs asynchronously and the result is accessed via the + * {@link AccountManagerFuture} that is returned. This future is also passed as the sole + * parameter to the {@link AccountManagerCallback}. If the caller wished to use this + * method asynchronously then they will generally pass in a callback object that will get + * invoked with the {@link AccountManagerFuture}. If they wish to use it synchronously then + * they will generally pass null for the callback and instead call + * {@link android.accounts.AccountManagerFuture#getResult()} on this method's return value, + * which will then block until the request completes. + * <p> + * Requires that the caller has permission {@link android.Manifest.permission#MANAGE_ACCOUNTS}. + * + * @param account The {@link Account} to remove + * @param callback A callback to invoke when the request completes. If null then + * no callback is invoked. + * @param handler The {@link Handler} to use to invoke the callback. If null then the + * main thread's {@link Handler} is used. + * @return an {@link AccountManagerFuture} that represents the future result of the call. + * The future result is a {@link Boolean} that is true if the account is successfully removed + * or false if the authenticator refuses to remove the account. + */ public AccountManagerFuture<Boolean> removeAccount(final Account account, AccountManagerCallback<Boolean> callback, Handler handler) { return new Future2Task<Boolean>(handler, callback) { @@ -183,6 +288,14 @@ public class AccountManager { }.start(); } + /** + * Removes the given authtoken. If this authtoken does not exist for the given account type + * then this call has no effect. + * <p> + * Requires that the caller has permission {@link android.Manifest.permission#MANAGE_ACCOUNTS}. + * @param accountType the account type of the authtoken to invalidate + * @param authToken the authtoken to invalidate + */ public void invalidateAuthToken(final String accountType, final String authToken) { try { mService.invalidateAuthToken(accountType, authToken); @@ -192,6 +305,20 @@ public class AccountManager { } } + /** + * Gets the authtoken named by "authTokenType" for the specified account if it is cached + * by the AccountManager. If no authtoken is cached then null is returned rather than + * asking the authenticaticor to generate one. If the account or the + * authtoken do not exist then null is returned. + * <p> + * Requires that the caller has permission + * {@link android.Manifest.permission#AUTHENTICATE_ACCOUNTS} and is running + * with the same UID as the Authenticator for the account. + * @param account the account whose authtoken is to be retrieved, must not be null + * @param authTokenType the type of authtoken to retrieve + * @return an authtoken for the given account and authTokenType, if one is cached by the + * AccountManager, null otherwise. + */ public String peekAuthToken(final Account account, final String authTokenType) { try { return mService.peekAuthToken(account, authTokenType); @@ -201,6 +328,16 @@ public class AccountManager { } } + /** + * Sets the password for the account. The password may be null. If the account does not exist + * then this call has no affect. + * <p> + * Requires that the caller has permission + * {@link android.Manifest.permission#AUTHENTICATE_ACCOUNTS} and is running + * with the same UID as the Authenticator for the account. + * @param account the account whose password is to be set. Must not be null. + * @param password the password to set for the account. May be null. + */ public void setPassword(final Account account, final String password) { try { mService.setPassword(account, password); @@ -210,6 +347,13 @@ public class AccountManager { } } + /** + * Sets the password for account to null. If the account does not exist then this call + * has no effect. + * <p> + * Requires that the caller has permission {@link android.Manifest.permission#MANAGE_ACCOUNTS}. + * @param account the account whose password is to be cleared. Must not be null. + */ public void clearPassword(final Account account) { try { mService.clearPassword(account); @@ -219,6 +363,17 @@ public class AccountManager { } } + /** + * Sets account's userdata named "key" to the specified value. If the account does not + * exist then this call has no effect. + * <p> + * Requires that the caller has permission + * {@link android.Manifest.permission#AUTHENTICATE_ACCOUNTS} and is running + * with the same UID as the Authenticator for the account. + * @param account the account whose userdata is to be set. Must not be null. + * @param key the key of the userdata to set. Must not be null. + * @param value the value to set. May be null. + */ public void setUserData(final Account account, final String key, final String value) { try { mService.setUserData(account, key, value); @@ -228,6 +383,17 @@ public class AccountManager { } } + /** + * Sets the authtoken named by "authTokenType" to the value specified by authToken. + * If the account does not exist then this call has no effect. + * <p> + * Requires that the caller has permission + * {@link android.Manifest.permission#AUTHENTICATE_ACCOUNTS} and is running + * with the same UID as the Authenticator for the account. + * @param account the account whose authtoken is to be set. Must not be null. + * @param authTokenType the type of the authtoken to set. Must not be null. + * @param authToken the authToken to set. May be null. + */ public void setAuthToken(Account account, final String authTokenType, final String authToken) { try { mService.setAuthToken(account, authTokenType, authToken); @@ -237,6 +403,25 @@ public class AccountManager { } } + /** + * Convenience method that makes a blocking call to + * {@link #getAuthToken(Account, String, boolean, AccountManagerCallback, Handler)} + * then extracts and returns the value of {@link #KEY_AUTHTOKEN} from its result. + * <p> + * Requires that the caller has permission {@link android.Manifest.permission#USE_CREDENTIALS}. + * @param account the account whose authtoken is to be retrieved, must not be null + * @param authTokenType the type of authtoken to retrieve + * @param notifyAuthFailure if true, cause the AccountManager to put up a "sign-on" notification + * for the account if no authtoken is cached by the AccountManager and the the authenticator + * does not have valid credentials to get an authtoken. + * @return an authtoken for the given account and authTokenType, if one is cached by the + * AccountManager, null otherwise. + * @throws AuthenticatorException if the authenticator is not present, unreachable or returns + * an invalid response. + * @throws OperationCanceledException if the request is canceled for any reason + * @throws java.io.IOException if the authenticator experiences an IOException while attempting + * to communicate with its backend server. + */ public String blockingGetAuthToken(Account account, String authTokenType, boolean notifyAuthFailure) throws OperationCanceledException, IOException, AuthenticatorException { @@ -246,16 +431,47 @@ public class AccountManager { } /** - * Request the auth token for this account/authTokenType. If this succeeds then the - * auth token will then be passed to the activity. If this results in an authentication - * failure then a login intent will be returned that can be invoked to prompt the user to - * update their credentials. This login activity will return the auth token to the calling - * activity. If activity is null then the login intent will not be invoked. + * Request that an authtoken of the specified type be returned for an account. + * If the Account Manager has a cached authtoken of the requested type then it will + * service the request itself. Otherwise it will pass the request on to the authenticator. + * The authenticator can try to service this request with information it already has stored + * in the AccountManager but may need to launch an activity to prompt the + * user to enter credentials. If it is able to retrieve the authtoken it will be returned + * in the result. + * <p> + * If the authenticator needs to prompt the user for credentials it will return an intent to + * the activity that will do the prompting. If an activity is supplied then that activity + * will be used to launch the intent and the result will come from it. Otherwise a result will + * be returned that contains the intent. + * <p> + * This call returns immediately but runs asynchronously and the result is accessed via the + * {@link AccountManagerFuture} that is returned. This future is also passed as the sole + * parameter to the {@link AccountManagerCallback}. If the caller wished to use this + * method asynchronously then they will generally pass in a callback object that will get + * invoked with the {@link AccountManagerFuture}. If they wish to use it synchronously then + * they will generally pass null for the callback and instead call + * {@link android.accounts.AccountManagerFuture#getResult()} on this method's return value, + * which will then block until the request completes. + * <p> + * Requires that the caller has permission {@link android.Manifest.permission#USE_CREDENTIALS}. * - * @param account the account whose auth token should be retrieved - * @param authTokenType the auth token type that should be retrieved - * @param loginOptions - * @param activity the activity to launch the login intent, if necessary, and to which + * @param account The account whose credentials are to be updated. + * @param authTokenType the auth token to retrieve as part of updating the credentials. + * May be null. + * @param loginOptions authenticator specific options for the request + * @param activity If the authenticator returns a {@link #KEY_INTENT} in the result then + * the intent will be started with this activity. If activity is null then the result will + * be returned as-is. + * @param callback A callback to invoke when the request completes. If null then + * no callback is invoked. + * @param handler The {@link Handler} to use to invoke the callback. If null then the + * main thread's {@link Handler} is used. + * @return an {@link AccountManagerFuture} that represents the future result of the call. + * The future result is a {@link Bundle} that contains: + * <ul> + * <li> {@link #KEY_ACCOUNT_NAME}, {@link #KEY_ACCOUNT_TYPE} and {@link #KEY_AUTHTOKEN} + * </ul> + * If the user presses "back" then the request will be canceled. */ public AccountManagerFuture<Bundle> getAuthToken( final Account account, final String authTokenType, final Bundle loginOptions, @@ -271,6 +487,48 @@ public class AccountManager { }.start(); } + /** + * Request that an authtoken of the specified type be returned for an account. + * If the Account Manager has a cached authtoken of the requested type then it will + * service the request itself. Otherwise it will pass the request on to the authenticator. + * The authenticator can try to service this request with information it already has stored + * in the AccountManager but may need to launch an activity to prompt the + * user to enter credentials. If it is able to retrieve the authtoken it will be returned + * in the result. + * <p> + * If the authenticator needs to prompt the user for credentials it will return an intent for + * an activity that will do the prompting. If an intent is returned and notifyAuthFailure + * is true then a notification will be created that launches this intent. + * <p> + * This call returns immediately but runs asynchronously and the result is accessed via the + * {@link AccountManagerFuture} that is returned. This future is also passed as the sole + * parameter to the {@link AccountManagerCallback}. If the caller wished to use this + * method asynchronously then they will generally pass in a callback object that will get + * invoked with the {@link AccountManagerFuture}. If they wish to use it synchronously then + * they will generally pass null for the callback and instead call + * {@link android.accounts.AccountManagerFuture#getResult()} on this method's return value, + * which will then block until the request completes. + * <p> + * Requires that the caller has permission {@link android.Manifest.permission#USE_CREDENTIALS}. + * + * @param account The account whose credentials are to be updated. + * @param authTokenType the auth token to retrieve as part of updating the credentials. + * May be null. + * @param notifyAuthFailure if true and the authenticator returns a {@link #KEY_INTENT} in the + * result then a "sign-on needed" notification will be created that will launch this intent. + * @param callback A callback to invoke when the request completes. If null then + * no callback is invoked. + * @param handler The {@link Handler} to use to invoke the callback. If null then the + * main thread's {@link Handler} is used. + * @return an {@link AccountManagerFuture} that represents the future result of the call. + * The future result is a {@link Bundle} that contains either: + * <ul> + * <li> {@link #KEY_INTENT}, which is to be used to prompt the user for the credentials + * <li> {@link #KEY_ACCOUNT_NAME}, {@link #KEY_ACCOUNT_TYPE} and {@link #KEY_AUTHTOKEN} + * if the authenticator is able to retrieve the auth token + * </ul> + * If the user presses "back" then the request will be canceled. + */ public AccountManagerFuture<Bundle> getAuthToken( final Account account, final String authTokenType, final boolean notifyAuthFailure, AccountManagerCallback<Bundle> callback, Handler handler) { @@ -284,6 +542,44 @@ public class AccountManager { }.start(); } + /** + * Request that an account be added with the given accountType. This request + * is processed by the authenticator for the account type. If no authenticator is registered + * in the system then {@link AuthenticatorException} is thrown. + * <p> + * This call returns immediately but runs asynchronously and the result is accessed via the + * {@link AccountManagerFuture} that is returned. This future is also passed as the sole + * parameter to the {@link AccountManagerCallback}. If the caller wished to use this + * method asynchronously then they will generally pass in a callback object that will get + * invoked with the {@link AccountManagerFuture}. If they wish to use it synchronously then + * they will generally pass null for the callback and instead call + * {@link android.accounts.AccountManagerFuture#getResult()} on this method's return value, + * which will then block until the request completes. + * <p> + * Requires that the caller has permission {@link android.Manifest.permission#MANAGE_ACCOUNTS}. + * + * @param accountType The type of account to add. This must not be null. + * @param authTokenType The account that is added should be able to service this auth token + * type. This may be null. + * @param requiredFeatures The account that is added should support these features. + * This array may be null or empty. + * @param addAccountOptions A bundle of authenticator-specific options that is passed on + * to the authenticator. This may be null. + * @param activity If the authenticator returns a {@link #KEY_INTENT} in the result then + * the intent will be started with this activity. If activity is null then the result will + * be returned as-is. + * @param callback A callback to invoke when the request completes. If null then + * no callback is invoked. + * @param handler The {@link Handler} to use to invoke the callback. If null then the + * main thread's {@link Handler} is used. + * @return an {@link AccountManagerFuture} that represents the future result of the call. + * The future result is a {@link Bundle} that contains either: + * <ul> + * <li> {@link #KEY_INTENT}, or + * <li> {@link #KEY_ACCOUNT_NAME}, {@link #KEY_ACCOUNT_TYPE} + * and {@link #KEY_AUTHTOKEN} (if an authTokenType was specified). + * </ul> + */ public AccountManagerFuture<Bundle> addAccount(final String accountType, final String authTokenType, final String[] requiredFeatures, final Bundle addAccountOptions, @@ -318,6 +614,42 @@ public class AccountManager { }.start(); } + /** + * Requests that the authenticator checks that the user knows the credentials for the account. + * This is typically done by returning an intent to an activity that prompts the user to + * enter the credentials. This request + * is processed by the authenticator for the account. If no matching authenticator is + * registered in the system then {@link AuthenticatorException} is thrown. + * <p> + * This call returns immediately but runs asynchronously and the result is accessed via the + * {@link AccountManagerFuture} that is returned. This future is also passed as the sole + * parameter to the {@link AccountManagerCallback}. If the caller wished to use this + * method asynchronously then they will generally pass in a callback object that will get + * invoked with the {@link AccountManagerFuture}. If they wish to use it synchronously then + * they will generally pass null for the callback and instead call + * {@link android.accounts.AccountManagerFuture#getResult()} on this method's return value, + * which will then block until the request completes. + * <p> + * Requires that the caller has permission {@link android.Manifest.permission#MANAGE_ACCOUNTS}. + * + * @param account The account whose credentials are to be checked + * @param options authenticator specific options for the request + * @param activity If the authenticator returns a {@link #KEY_INTENT} in the result then + * the intent will be started with this activity. If activity is null then the result will + * be returned as-is. + * @param callback A callback to invoke when the request completes. If null then + * no callback is invoked. + * @param handler The {@link Handler} to use to invoke the callback. If null then the + * main thread's {@link Handler} is used. + * @return an {@link AccountManagerFuture} that represents the future result of the call. + * The future result is a {@link Bundle} that contains either: + * <ul> + * <li> {@link #KEY_INTENT}, which is to be used to prompt the user for the credentials + * <li> {@link #KEY_ACCOUNT_NAME} and {@link #KEY_ACCOUNT_TYPE} if the user enters the correct + * credentials + * </ul> + * If the user presses "back" then the request will be canceled. + */ public AccountManagerFuture<Bundle> confirmCredentials(final Account account, final Bundle options, final Activity activity, @@ -330,7 +662,46 @@ public class AccountManager { }.start(); } - public AccountManagerFuture<Bundle> updateCredentials(final Account account, final String authTokenType, + /** + * Requests that the authenticator update the the credentials for a user. This is typically + * done by returning an intent to an activity that will prompt the user to update the stored + * credentials for the account. This request + * is processed by the authenticator for the account. If no matching authenticator is + * registered in the system then {@link AuthenticatorException} is thrown. + * <p> + * This call returns immediately but runs asynchronously and the result is accessed via the + * {@link AccountManagerFuture} that is returned. This future is also passed as the sole + * parameter to the {@link AccountManagerCallback}. If the caller wished to use this + * method asynchronously then they will generally pass in a callback object that will get + * invoked with the {@link AccountManagerFuture}. If they wish to use it synchronously then + * they will generally pass null for the callback and instead call + * {@link android.accounts.AccountManagerFuture#getResult()} on this method's return value, + * which will then block until the request completes. + * <p> + * Requires that the caller has permission {@link android.Manifest.permission#MANAGE_ACCOUNTS}. + * + * @param account The account whose credentials are to be updated. + * @param authTokenType the auth token to retrieve as part of updating the credentials. + * May be null. + * @param loginOptions authenticator specific options for the request + * @param activity If the authenticator returns a {@link #KEY_INTENT} in the result then + * the intent will be started with this activity. If activity is null then the result will + * be returned as-is. + * @param callback A callback to invoke when the request completes. If null then + * no callback is invoked. + * @param handler The {@link Handler} to use to invoke the callback. If null then the + * main thread's {@link Handler} is used. + * @return an {@link AccountManagerFuture} that represents the future result of the call. + * The future result is a {@link Bundle} that contains either: + * <ul> + * <li> {@link #KEY_INTENT}, which is to be used to prompt the user for the credentials + * <li> {@link #KEY_ACCOUNT_NAME} and {@link #KEY_ACCOUNT_TYPE} if the user enters the correct + * credentials, and optionally a {@link #KEY_AUTHTOKEN} if an authTokenType was provided. + * </ul> + * If the user presses "back" then the request will be canceled. + */ + public AccountManagerFuture<Bundle> updateCredentials(final Account account, + final String authTokenType, final Bundle loginOptions, final Activity activity, final AccountManagerCallback<Bundle> callback, final Handler handler) { @@ -342,8 +713,41 @@ public class AccountManager { }.start(); } - public AccountManagerFuture<Bundle> editProperties(final String accountType, final Activity activity, - final AccountManagerCallback<Bundle> callback, + /** + * Request that the properties for an authenticator be updated. This is typically done by + * returning an intent to an activity that will allow the user to make changes. This request + * is processed by the authenticator for the account. If no matching authenticator is + * registered in the system then {@link AuthenticatorException} is thrown. + * <p> + * This call returns immediately but runs asynchronously and the result is accessed via the + * {@link AccountManagerFuture} that is returned. This future is also passed as the sole + * parameter to the {@link AccountManagerCallback}. If the caller wished to use this + * method asynchronously then they will generally pass in a callback object that will get + * invoked with the {@link AccountManagerFuture}. If they wish to use it synchronously then + * they will generally pass null for the callback and instead call + * {@link android.accounts.AccountManagerFuture#getResult()} on this method's return value, + * which will then block until the request completes. + * <p> + * Requires that the caller has permission {@link android.Manifest.permission#MANAGE_ACCOUNTS}. + * + * @param accountType The account type of the authenticator whose properties are to be edited. + * @param activity If the authenticator returns a {@link #KEY_INTENT} in the result then + * the intent will be started with this activity. If activity is null then the result will + * be returned as-is. + * @param callback A callback to invoke when the request completes. If null then + * no callback is invoked. + * @param handler The {@link Handler} to use to invoke the callback. If null then the + * main thread's {@link Handler} is used. + * @return an {@link AccountManagerFuture} that represents the future result of the call. + * The future result is a {@link Bundle} that contains either: + * <ul> + * <li> {@link #KEY_INTENT}, which is to be used to prompt the user for the credentials + * <li> nothing, returned if the edit completes successfully + * </ul> + * If the user presses "back" then the request will be canceled. + */ + public AccountManagerFuture<Bundle> editProperties(final String accountType, + final Activity activity, final AccountManagerCallback<Bundle> callback, final Handler handler) { return new AmsTask(activity, handler, callback) { public void doWork() throws RemoteException { @@ -783,6 +1187,48 @@ public class AccountManager { } } + /** + * Convenience method that combines the functionality of {@link #getAccountsByTypeAndFeatures}, + * {@link #getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback, Handler)}, + * and {@link #addAccount}. It first gets the list of accounts that match accountType and the + * feature set. If there are none then {@link #addAccount} is invoked with the authTokenType + * feature set, and addAccountOptions. If there is exactly one then + * {@link #getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback, Handler)} is + * called with that account. If there are more than one then a chooser activity is launched + * to prompt the user to select one of them and then the authtoken is retrieved for it, + * <p> + * This call returns immediately but runs asynchronously and the result is accessed via the + * {@link AccountManagerFuture} that is returned. This future is also passed as the sole + * parameter to the {@link AccountManagerCallback}. If the caller wished to use this + * method asynchronously then they will generally pass in a callback object that will get + * invoked with the {@link AccountManagerFuture}. If they wish to use it synchronously then + * they will generally pass null for the callback and instead call + * {@link android.accounts.AccountManagerFuture#getResult()} on this method's return value, + * which will then block until the request completes. + * <p> + * Requires that the caller has permission {@link android.Manifest.permission#MANAGE_ACCOUNTS}. + * + * @param accountType the accountType to query; this must be non-null + * @param authTokenType the type of authtoken to retrieve; this must be non-null + * @param features a filter for the accounts. See {@link #getAccountsByTypeAndFeatures}. + * @param activityForPrompting The activity used to start any account management + * activities that are required to fulfill this request. This may be null. + * @param addAccountOptions authenticator-specific options used if an account needs to be added + * @param loginOptions authenticator-specific options passed to getAuthToken + * @param callback A callback to invoke when the request completes. If null then + * no callback is invoked. + * @param handler The {@link Handler} to use to invoke the callback. If null then the + * main thread's {@link Handler} is used. + * @return an {@link AccountManagerFuture} that represents the future result of the call. + * The future result is a {@link Bundle} that contains either: + * <ul> + * <li> {@link #KEY_INTENT}, if no activity is supplied yet an activity needs to launched to + * fulfill the request. + * <li> {@link #KEY_ACCOUNT_NAME}, {@link #KEY_ACCOUNT_TYPE} and {@link #KEY_AUTHTOKEN} if the + * request completes successfully. + * </ul> + * If the user presses "back" then the request will be canceled. + */ public AccountManagerFuture<Bundle> getAuthTokenByFeatures( final String accountType, final String authTokenType, final String[] features, final Activity activityForPrompting, final Bundle addAccountOptions, |