public class AccountManager extends Object
Different online services have different ways of handling accounts and authentication, so the account manager uses pluggable authenticator modules for different account types. 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.
Many servers support some notion of an authentication token, 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 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 invalidate auth tokens when they stop working so the AccountManager knows it needs to regenerate them.
Applications accessing a server normally go through these steps:
get(Context)
.
getAccountsByType(java.lang.String)
or
getAccountsByTypeAndFeatures(java.lang.String, java.lang.String[], android.accounts.AccountManagerCallback<android.accounts.Account[]>, android.os.Handler)
. Normally applications will only
be interested in accounts with one particular type, which
identifies the authenticator. Account features are used to
identify particular account subtypes and capabilities. Both the account
type and features are authenticator-specific strings, and must be known by
the application in coordination with its preferred authenticators.
addAccount(java.lang.String, java.lang.String, java.lang.String[], android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler)
may be called to prompt the user to create an
account of the appropriate type.
getAccountsByType(java.lang.String)
. Requesting an auth token
for an account no longer on the device results in an undefined failure.
getAuthToken(android.accounts.Account, java.lang.String, android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler)
methods or related helpers. Refer to the description
of each method for exact usage and error handling details.
invalidateAuthToken(java.lang.String, java.lang.String)
to remove
the token from the cache, otherwise requests will continue failing! After
invalidating the auth token, immediately go back to the "Request an auth
token" step above. If the process fails the second time, then it can be
treated as a "genuine" authentication failure and the user notified or other
appropriate actions taken.
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 caller may use to launch the interface, or (in some cases) to install a
notification which the user can select at any time to launch the interface.
To have AccountManager launch the interface directly, the caller must supply
the current foreground Activity
context.
Many AccountManager methods take AccountManagerCallback
and
Handler
as parameters. These methods return immediately and
run asynchronously. If a callback is provided then
AccountManagerCallback.run(android.accounts.AccountManagerFuture<V>)
will be invoked on the Handler's
thread when the request completes, successfully or not.
The result is retrieved by calling AccountManagerFuture.getResult()
on the 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
AccountManagerFuture.getResult()
immediately on receiving the
future from the method; no callback need be supplied.
Requests which may block, including
AccountManagerFuture.getResult()
, must never be called on
the application's main event thread. These operations throw
IllegalStateException
if they are used on the main thread.
Modifier and Type | Field and Description |
---|---|
static String |
ACTION_AUTHENTICATOR_INTENT |
static String |
AUTHENTICATOR_ATTRIBUTES_NAME |
static String |
AUTHENTICATOR_META_DATA_NAME |
static int |
ERROR_CODE_BAD_ARGUMENTS |
static int |
ERROR_CODE_BAD_REQUEST |
static int |
ERROR_CODE_CANCELED |
static int |
ERROR_CODE_INVALID_RESPONSE |
static int |
ERROR_CODE_NETWORK_ERROR |
static int |
ERROR_CODE_REMOTE_EXCEPTION |
static int |
ERROR_CODE_UNSUPPORTED_OPERATION |
static String |
KEY_ACCOUNT_AUTHENTICATOR_RESPONSE |
static String |
KEY_ACCOUNT_MANAGER_RESPONSE |
static String |
KEY_ACCOUNT_NAME
Bundle key used for the
String account name in results
from methods which return information about a particular account. |
static String |
KEY_ACCOUNT_TYPE
Bundle key used for the
String account type in results
from methods which return information about a particular account. |
static String |
KEY_ACCOUNTS |
static String |
KEY_ANDROID_PACKAGE_NAME
The Android package of the caller will be set in the options bundle by the
AccountManager and will be passed to the AccountManagerService and
to the AccountAuthenticators. |
static String |
KEY_AUTH_FAILED_MESSAGE |
static String |
KEY_AUTH_TOKEN_LABEL |
static String |
KEY_AUTHENTICATOR_TYPES |
static String |
KEY_AUTHTOKEN
Bundle key used for the auth token value in results
from
getAuthToken(android.accounts.Account, java.lang.String, android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler) and friends. |
static String |
KEY_BOOLEAN_RESULT |
static String |
KEY_CALLER_PID |
static String |
KEY_CALLER_UID
Authenticators using 'customTokens' option will also get the UID of the
caller
|
static String |
KEY_ERROR_CODE |
static String |
KEY_ERROR_MESSAGE |
static String |
KEY_INTENT
Bundle key used for an
Intent in results from methods that
may require the caller to interact with the user. |
static String |
KEY_NOTIFY_ON_FAILURE
Boolean, if set and 'customTokens' the authenticator is responsible for
notifications.
|
static String |
KEY_PASSWORD
Bundle key used to supply the password directly in options to
confirmCredentials(android.accounts.Account, android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler) , rather than prompting the user with
the standard password prompt. |
static String |
KEY_USERDATA |
static String |
LOGIN_ACCOUNTS_CHANGED_ACTION
Action sent as a broadcast Intent by the AccountsService
when accounts are added, accounts are removed, or an
account's credentials (saved password, etc) are changed.
|
Constructor and Description |
---|
AccountManager(Context context,
IAccountManager service) |
AccountManager(Context context,
IAccountManager service,
Handler handler) |
Modifier and Type | Method and Description |
---|---|
AccountManagerFuture<Bundle> |
addAccount(String accountType,
String authTokenType,
String[] requiredFeatures,
Bundle addAccountOptions,
Activity activity,
AccountManagerCallback<Bundle> callback,
Handler handler)
Asks the user to add an account of a specified type.
|
boolean |
addAccountExplicitly(Account account,
String password,
Bundle userdata)
Adds an account directly to the AccountManager.
|
void |
addOnAccountsUpdatedListener(OnAccountsUpdateListener listener,
Handler handler,
boolean updateImmediately)
Adds an
OnAccountsUpdateListener to this instance of the
AccountManager . |
String |
blockingGetAuthToken(Account account,
String authTokenType,
boolean notifyAuthFailure)
This convenience helper synchronously gets an auth token with
getAuthToken(Account, String, boolean, AccountManagerCallback, Handler) . |
void |
clearPassword(Account account)
Forgets a saved password.
|
AccountManagerFuture<Bundle> |
confirmCredentials(Account account,
Bundle options,
Activity activity,
AccountManagerCallback<Bundle> callback,
Handler handler)
Confirms that the user knows the password for an account to make extra
sure they are the owner of the account.
|
AccountManagerFuture<Bundle> |
confirmCredentialsAsUser(Account account,
Bundle options,
Activity activity,
AccountManagerCallback<Bundle> callback,
Handler handler,
UserHandle userHandle) |
AccountManagerFuture<Bundle> |
editProperties(String accountType,
Activity activity,
AccountManagerCallback<Bundle> callback,
Handler handler)
Offers the user an opportunity to change an authenticator's settings.
|
static AccountManager |
get(Context context)
Gets an AccountManager instance associated with a Context.
|
Account[] |
getAccounts()
Lists all accounts of any type registered on the device.
|
Account[] |
getAccountsByType(String type)
Lists all accounts of a particular type.
|
AccountManagerFuture<Account[]> |
getAccountsByTypeAndFeatures(String type,
String[] features,
AccountManagerCallback<Account[]> callback,
Handler handler)
Lists all accounts of a type which have certain features.
|
Account[] |
getAccountsByTypeAsUser(String type,
UserHandle userHandle) |
AuthenticatorDescription[] |
getAuthenticatorTypes()
Lists the currently registered authenticators.
|
AccountManagerFuture<Bundle> |
getAuthToken(Account account,
String authTokenType,
boolean notifyAuthFailure,
AccountManagerCallback<Bundle> callback,
Handler handler)
|
AccountManagerFuture<Bundle> |
getAuthToken(Account account,
String authTokenType,
Bundle options,
Activity activity,
AccountManagerCallback<Bundle> callback,
Handler handler)
Gets an auth token of the specified type for a particular account,
prompting the user for credentials if necessary.
|
AccountManagerFuture<Bundle> |
getAuthToken(Account account,
String authTokenType,
Bundle options,
boolean notifyAuthFailure,
AccountManagerCallback<Bundle> callback,
Handler handler)
Gets an auth token of the specified type for a particular account,
optionally raising a notification if the user must enter credentials.
|
AccountManagerFuture<Bundle> |
getAuthTokenByFeatures(String accountType,
String authTokenType,
String[] features,
Activity activity,
Bundle addAccountOptions,
Bundle getAuthTokenOptions,
AccountManagerCallback<Bundle> callback,
Handler handler)
This convenience helper combines the functionality of
getAccountsByTypeAndFeatures(java.lang.String, java.lang.String[], android.accounts.AccountManagerCallback<android.accounts.Account[]>, android.os.Handler) , getAuthToken(android.accounts.Account, java.lang.String, android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler) , and
addAccount(java.lang.String, java.lang.String, java.lang.String[], android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler) . |
AccountManagerFuture<String> |
getAuthTokenLabel(String accountType,
String authTokenType,
AccountManagerCallback<String> callback,
Handler handler)
Get the user-friendly label associated with an authenticator's auth token.
|
String |
getPassword(Account account)
Gets the saved password associated with the account.
|
String |
getUserData(Account account,
String key)
Gets the user data named by "key" associated with the account.
|
AccountManagerFuture<Boolean> |
hasFeatures(Account account,
String[] features,
AccountManagerCallback<Boolean> callback,
Handler handler)
Finds out whether a particular account has all the specified features.
|
void |
invalidateAuthToken(String accountType,
String authToken)
Removes an auth token from the AccountManager's cache.
|
static Intent |
newChooseAccountIntent(Account selectedAccount,
ArrayList<Account> allowableAccounts,
String[] allowableAccountTypes,
boolean alwaysPromptForAccount,
String descriptionOverrideText,
String addAccountAuthTokenType,
String[] addAccountRequiredFeatures,
Bundle addAccountOptions)
Returns an intent to an
Activity that prompts the user to choose from a list of
accounts. |
String |
peekAuthToken(Account account,
String authTokenType)
Gets an auth token from the AccountManager's cache.
|
AccountManagerFuture<Boolean> |
removeAccount(Account account,
AccountManagerCallback<Boolean> callback,
Handler handler)
Removes an account from the AccountManager.
|
void |
removeOnAccountsUpdatedListener(OnAccountsUpdateListener listener)
Removes an
OnAccountsUpdateListener previously registered with
addOnAccountsUpdatedListener(android.accounts.OnAccountsUpdateListener, android.os.Handler, boolean) . |
static Bundle |
sanitizeResult(Bundle result) |
void |
setAuthToken(Account account,
String authTokenType,
String authToken)
Adds an auth token to the AccountManager cache for an account.
|
void |
setPassword(Account account,
String password)
Sets or forgets a saved password.
|
void |
setUserData(Account account,
String key,
String value)
Sets one userdata key for an account.
|
void |
updateAppPermission(Account account,
String authTokenType,
int uid,
boolean value)
Change whether or not an app (identified by its uid) is allowed to retrieve an authToken
for an account.
|
AccountManagerFuture<Bundle> |
updateCredentials(Account account,
String authTokenType,
Bundle options,
Activity activity,
AccountManagerCallback<Bundle> callback,
Handler handler)
Asks the user to enter a new password for an account, updating the
saved credentials for the account.
|
public static final int ERROR_CODE_REMOTE_EXCEPTION
public static final int ERROR_CODE_NETWORK_ERROR
public static final int ERROR_CODE_CANCELED
public static final int ERROR_CODE_INVALID_RESPONSE
public static final int ERROR_CODE_UNSUPPORTED_OPERATION
public static final int ERROR_CODE_BAD_ARGUMENTS
public static final int ERROR_CODE_BAD_REQUEST
public static final String KEY_ACCOUNT_NAME
String
account name in results
from methods which return information about a particular account.public static final String KEY_ACCOUNT_TYPE
String
account type in results
from methods which return information about a particular account.public static final String KEY_AUTHTOKEN
getAuthToken(android.accounts.Account, java.lang.String, android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler)
and friends.public static final String KEY_INTENT
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_PASSWORD
confirmCredentials(android.accounts.Account, android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler)
, rather than prompting the user with
the standard password prompt.public static final String KEY_ACCOUNTS
public static final String KEY_ACCOUNT_AUTHENTICATOR_RESPONSE
public static final String KEY_ACCOUNT_MANAGER_RESPONSE
public static final String KEY_AUTHENTICATOR_TYPES
public static final String KEY_AUTH_FAILED_MESSAGE
public static final String KEY_AUTH_TOKEN_LABEL
public static final String KEY_BOOLEAN_RESULT
public static final String KEY_ERROR_CODE
public static final String KEY_ERROR_MESSAGE
public static final String KEY_USERDATA
public static final String KEY_CALLER_UID
public static final String KEY_CALLER_PID
public static final String KEY_ANDROID_PACKAGE_NAME
AccountManager
and will be passed to the AccountManagerService and
to the AccountAuthenticators. The uid of the caller will be known by the
AccountManagerService as well as the AccountAuthenticators so they will be able to
verify that the package is consistent with the uid (a uid might be shared by many
packages).public static final String KEY_NOTIFY_ON_FAILURE
public static final String ACTION_AUTHENTICATOR_INTENT
public static final String AUTHENTICATOR_META_DATA_NAME
public static final String AUTHENTICATOR_ATTRIBUTES_NAME
public static final String LOGIN_ACCOUNTS_CHANGED_ACTION
public AccountManager(Context context, IAccountManager service)
public static AccountManager get(Context context)
Context
will be used as long as the AccountManager is
active, so make sure to use a Context
whose lifetime is
commensurate with any listeners registered to
addOnAccountsUpdatedListener(android.accounts.OnAccountsUpdateListener, android.os.Handler, boolean)
or similar methods.
It is safe to call this method from the main thread.
No permission is required to call this method.
context
- The Context
to use when necessaryAccountManager
instancepublic String getPassword(Account account)
It is safe to call this method from the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#AUTHENTICATE_ACCOUNTS
and to have the same UID as the account's authenticator.
account
- The account to query for a passwordpublic String getUserData(Account account, String key)
It is safe to call this method from the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#AUTHENTICATE_ACCOUNTS
and to have the same UID as the account's authenticator.
account
- The account to query for user datapublic AuthenticatorDescription[] getAuthenticatorTypes()
It is safe to call this method from the main thread.
No permission is required to call this method.
AuthenticatorDescription
for every
authenticator known to the AccountManager service. Empty (never
null) if no authenticators are known.public Account[] getAccounts()
It is safe to call this method from the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#GET_ACCOUNTS
.
Account
, one for each account. Empty
(never null) if no accounts have been added.public Account[] getAccountsByType(String type)
It is safe to call this method from the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#GET_ACCOUNTS
.
type
- The type of accounts to return, null to retrieve all accountsAccount
, one per matching account. Empty
(never null) if no accounts of the specified type have been added.public Account[] getAccountsByTypeAsUser(String type, UserHandle userHandle)
public void updateAppPermission(Account account, String authTokenType, int uid, boolean value)
This is only meant to be used by system activities and is not in the SDK.
account
- The account whose permissions are being modifiedauthTokenType
- The type of token whose permissions are being modifieduid
- The uid that identifies the app which is being granted or revoked permission.value
- true is permission is being granted, false for revokedpublic AccountManagerFuture<String> getAuthTokenLabel(String accountType, String authTokenType, AccountManagerCallback<String> callback, Handler handler)
accountType
- the type of the authenticator. must not be null.authTokenType
- the token type. must not be null.callback
- callback to invoke when the result is available. may be null.handler
- the handler on which to invoke the callback, or null for the main threadpublic AccountManagerFuture<Boolean> hasFeatures(Account account, String[] features, AccountManagerCallback<Boolean> callback, Handler handler)
This method may be called from any thread, but the returned
AccountManagerFuture
must not be used on the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#GET_ACCOUNTS
.
account
- The Account
to testfeatures
- An array of the account features to checkcallback
- Callback to invoke when the request completes,
null for no callbackhandler
- Handler
identifying the callback thread,
null for the main threadAccountManagerFuture
which resolves to a Boolean,
true if the account exists and has all of the specified features.public AccountManagerFuture<Account[]> getAccountsByTypeAndFeatures(String type, String[] features, AccountManagerCallback<Account[]> callback, Handler handler)
getAccountsByType(java.lang.String)
).
Account features are authenticator-specific string tokens identifying
boolean account properties (see hasFeatures(android.accounts.Account, java.lang.String[], android.accounts.AccountManagerCallback<java.lang.Boolean>, android.os.Handler)
).
Unlike getAccountsByType(java.lang.String)
, this method calls the authenticator,
which may contact the server or do other work to check account features,
so the method returns an AccountManagerFuture
.
This method may be called from any thread, but the returned
AccountManagerFuture
must not be used on the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#GET_ACCOUNTS
.
type
- The type of accounts to return, must not be nullfeatures
- An array of the account features to require,
may be null or emptycallback
- Callback to invoke when the request completes,
null for no callbackhandler
- Handler
identifying the callback thread,
null for the main threadAccountManagerFuture
which resolves to an array of
Account
, one per account of the specified type which
matches the requested features.public boolean addAccountExplicitly(Account account, String password, Bundle userdata)
It is safe to call this method from the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#AUTHENTICATE_ACCOUNTS
and to have the same UID as the added account's authenticator.
account
- The Account
to addpassword
- The password to associate with the account, null for noneuserdata
- String values to use for the account's userdata, null for nonepublic AccountManagerFuture<Boolean> removeAccount(Account account, AccountManagerCallback<Boolean> callback, Handler handler)
This method may be called from any thread, but the returned
AccountManagerFuture
must not be used on the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#MANAGE_ACCOUNTS
.
account
- The Account
to removecallback
- Callback to invoke when the request completes,
null for no callbackhandler
- Handler
identifying the callback thread,
null for the main threadAccountManagerFuture
which resolves to a Boolean,
true if the account has been successfully removed,
false if the authenticator forbids deleting this account.public void invalidateAuthToken(String accountType, String authToken)
It is safe to call this method from the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#MANAGE_ACCOUNTS
or
android.Manifest.permission#USE_CREDENTIALS
accountType
- The account type of the auth token to invalidate, must not be nullauthToken
- The auth token to invalidate, may be nullpublic String peekAuthToken(Account account, String authTokenType)
It is safe to call this method from the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#AUTHENTICATE_ACCOUNTS
and to have the same UID as the account's authenticator.
account
- The account to fetch an auth token forauthTokenType
- The type of auth token to fetch, see {#getAuthToken}public void setPassword(Account account, String password)
It is safe to call this method from the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#AUTHENTICATE_ACCOUNTS
and have the same UID as the account's authenticator.
account
- The account to set a password forpassword
- The password to set, null to clear the passwordpublic void clearPassword(Account account)
It is safe to call this method from the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#MANAGE_ACCOUNTS
account
- The account whose password to clearpublic void setUserData(Account account, String key, String value)
It is safe to call this method from the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#AUTHENTICATE_ACCOUNTS
and to have the same UID as the account's authenticator.
account
- The account to set the userdata forkey
- The userdata key to set. Must not be nullvalue
- The value to set, null to clear this userdata keypublic void setAuthToken(Account account, String authTokenType, String authToken)
It is safe to call this method from the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#AUTHENTICATE_ACCOUNTS
and to have the same UID as the account's authenticator.
account
- The account to set an auth token forauthTokenType
- The type of the auth token, see {#getAuthToken}authToken
- The auth token to add to the cachepublic String blockingGetAuthToken(Account account, String authTokenType, boolean notifyAuthFailure) throws OperationCanceledException, IOException, AuthenticatorException
getAuthToken(Account, String, boolean, AccountManagerCallback, Handler)
.
This method may block while a network request completes, and must never be made from the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#USE_CREDENTIALS
.
account
- The account to fetch an auth token forauthTokenType
- The auth token type, see {#link getAuthToken}notifyAuthFailure
- If true, display a notification and return null
if authentication fails; if false, prompt and wait for the user to
re-enter correct credentials before returningAuthenticatorException
- if the authenticator failed to respondOperationCanceledException
- if the request was canceled for any
reason, including the user canceling a credential requestIOException
- if the authenticator experienced an I/O problem
creating a new auth token, usually because of network troublepublic AccountManagerFuture<Bundle> getAuthToken(Account account, String authTokenType, Bundle options, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
If a previously generated auth token is cached for this account and 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.
Some authenticators have auth token types, 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.
This method may be called from any thread, but the returned
AccountManagerFuture
must not be used on the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#USE_CREDENTIALS
.
account
- The account to fetch an auth token forauthTokenType
- The auth token type, an authenticator-dependent
string token, must not be nulloptions
- Authenticator-specific options for the request,
may be null or emptyactivity
- The Activity
context to use for launching a new
authenticator-defined sub-Activity to prompt the user for a password
if necessary; used only to call startActivity(); must not be null.callback
- Callback to invoke when the request completes,
null for no callbackhandler
- Handler
identifying the callback thread,
null for the main threadAccountManagerFuture
which resolves to a Bundle with
at least the following fields:
KEY_ACCOUNT_NAME
- the name of the account you supplied
KEY_ACCOUNT_TYPE
- the type of the account
KEY_AUTHTOKEN
- the auth token you wanted
AccountManagerFuture.getResult()
throws:
AuthenticatorException
if the authenticator failed to respond
OperationCanceledException
if the operation is canceled for
any reason, incluidng the user canceling a credential request
IOException
if the authenticator experienced an I/O problem
creating a new auth token, usually because of network trouble
@Deprecated public AccountManagerFuture<Bundle> getAuthToken(Account account, String authTokenType, boolean notifyAuthFailure, AccountManagerCallback<Bundle> callback, Handler handler)
getAuthToken(Account, String, android.os.Bundle,
boolean, AccountManagerCallback, android.os.Handler)
insteadIf a previously generated auth token is cached for this account and
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 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.
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
LOGIN_ACCOUNTS_CHANGED_ACTION
Intent, which applications can
use to try again.
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.
Some authenticators have auth token types, 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.
This method may be called from any thread, but the returned
AccountManagerFuture
must not be used on the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#USE_CREDENTIALS
.
account
- The account to fetch an auth token forauthTokenType
- The auth token type, an authenticator-dependent
string token, must not be nullnotifyAuthFailure
- True to add a notification to prompt the
user for a password if necessary, false to leave that to the callercallback
- Callback to invoke when the request completes,
null for no callbackhandler
- Handler
identifying the callback thread,
null for the main threadAccountManagerFuture
which resolves to a Bundle with
at least the following fields on success:
KEY_ACCOUNT_NAME
- the name of the account you supplied
KEY_ACCOUNT_TYPE
- the type of the account
KEY_AUTHTOKEN
- the auth token you wanted
KEY_INTENT
with the Intent
needed to launch a prompt.
If an error occurred, AccountManagerFuture.getResult()
throws:
AuthenticatorException
if the authenticator failed to respond
OperationCanceledException
if the operation is canceled for
any reason, incluidng the user canceling a credential request
IOException
if the authenticator experienced an I/O problem
creating a new auth token, usually because of network trouble
public AccountManagerFuture<Bundle> getAuthToken(Account account, String authTokenType, Bundle options, boolean notifyAuthFailure, AccountManagerCallback<Bundle> callback, Handler handler)
If a previously generated auth token is cached for this account and
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 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.
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
LOGIN_ACCOUNTS_CHANGED_ACTION
Intent, which applications can
use to try again.
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.
Some authenticators have auth token types, 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.
This method may be called from any thread, but the returned
AccountManagerFuture
must not be used on the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#USE_CREDENTIALS
.
account
- The account to fetch an auth token forauthTokenType
- The auth token type, an authenticator-dependent
string token, must not be nulloptions
- Authenticator-specific options for the request,
may be null or emptynotifyAuthFailure
- True to add a notification to prompt the
user for a password if necessary, false to leave that to the callercallback
- Callback to invoke when the request completes,
null for no callbackhandler
- Handler
identifying the callback thread,
null for the main threadAccountManagerFuture
which resolves to a Bundle with
at least the following fields on success:
KEY_ACCOUNT_NAME
- the name of the account you supplied
KEY_ACCOUNT_TYPE
- the type of the account
KEY_AUTHTOKEN
- the auth token you wanted
KEY_INTENT
with the Intent
needed to launch a prompt.
If an error occurred, AccountManagerFuture.getResult()
throws:
AuthenticatorException
if the authenticator failed to respond
OperationCanceledException
if the operation is canceled for
any reason, incluidng the user canceling a credential request
IOException
if the authenticator experienced an I/O problem
creating a new auth token, usually because of network trouble
public AccountManagerFuture<Bundle> addAccount(String accountType, String authTokenType, String[] requiredFeatures, Bundle addAccountOptions, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
This method may be called from any thread, but the returned
AccountManagerFuture
must not be used on the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#MANAGE_ACCOUNTS
.
accountType
- The type of account to add; must not be nullauthTokenType
- The type of auth token (see getAuthToken(android.accounts.Account, java.lang.String, android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler)
)
this account will need to be able to generate, null for nonerequiredFeatures
- The features (see hasFeatures(android.accounts.Account, java.lang.String[], android.accounts.AccountManagerCallback<java.lang.Boolean>, android.os.Handler)
) this
account must have, null for noneaddAccountOptions
- Authenticator-specific options for the request,
may be null or emptyactivity
- The Activity
context to use for launching a new
authenticator-defined sub-Activity to prompt the user to create an
account; used only to call startActivity(); if null, the prompt
will not be launched directly, but the necessary Intent
will be returned to the caller insteadcallback
- Callback to invoke when the request completes,
null for no callbackhandler
- Handler
identifying the callback thread,
null for the main threadAccountManagerFuture
which resolves to a Bundle with
these fields if activity was specified and an account was created:
KEY_ACCOUNT_NAME
- the name of the account created
KEY_ACCOUNT_TYPE
- the type of the account
KEY_INTENT
with the Intent
needed to launch the
actual account creation process. If an error occurred,
AccountManagerFuture.getResult()
throws:
AuthenticatorException
if no authenticator was registered for
this account type or the authenticator failed to respond
OperationCanceledException
if the operation was canceled for
any reason, including the user canceling the creation process
IOException
if the authenticator experienced an I/O problem
creating a new account, usually because of network trouble
public AccountManagerFuture<Bundle> confirmCredentials(Account account, Bundle options, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
If the user-entered password matches a saved password for this account, the request is considered valid; otherwise the authenticator verifies the password (usually by contacting the server).
This method may be called from any thread, but the returned
AccountManagerFuture
must not be used on the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#MANAGE_ACCOUNTS
.
account
- The account to confirm password knowledge foroptions
- Authenticator-specific options for the request;
if the KEY_PASSWORD
string field is present, the
authenticator may use it directly rather than prompting the user;
may be null or emptyactivity
- The Activity
context to use for launching a new
authenticator-defined sub-Activity to prompt the user to enter a
password; used only to call startActivity(); if null, the prompt
will not be launched directly, but the necessary Intent
will be returned to the caller insteadcallback
- Callback to invoke when the request completes,
null for no callbackhandler
- Handler
identifying the callback thread,
null for the main threadAccountManagerFuture
which resolves to a Bundle
with these fields if activity or password was supplied and
the account was successfully verified:
KEY_ACCOUNT_NAME
- the name of the account created
KEY_ACCOUNT_TYPE
- the type of the account
KEY_BOOLEAN_RESULT
- true to indicate success
KEY_INTENT
with the Intent
needed to launch the
password prompt. If an error occurred,
AccountManagerFuture.getResult()
throws:
AuthenticatorException
if the authenticator failed to respond
OperationCanceledException
if the operation was canceled for
any reason, including the user canceling the password prompt
IOException
if the authenticator experienced an I/O problem
verifying the password, usually because of network trouble
public AccountManagerFuture<Bundle> confirmCredentialsAsUser(Account account, Bundle options, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler, UserHandle userHandle)
public AccountManagerFuture<Bundle> updateCredentials(Account account, String authTokenType, Bundle options, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
This method may be called from any thread, but the returned
AccountManagerFuture
must not be used on the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#MANAGE_ACCOUNTS
.
account
- The account to update credentials forauthTokenType
- The credentials entered must allow an auth token
of this type to be created (but no actual auth token is returned);
may be nulloptions
- Authenticator-specific options for the request;
may be null or emptyactivity
- The Activity
context to use for launching a new
authenticator-defined sub-Activity to prompt the user to enter a
password; used only to call startActivity(); if null, the prompt
will not be launched directly, but the necessary Intent
will be returned to the caller insteadcallback
- Callback to invoke when the request completes,
null for no callbackhandler
- Handler
identifying the callback thread,
null for the main threadAccountManagerFuture
which resolves to a Bundle
with these fields if an activity was supplied and the account
credentials were successfully updated:
KEY_ACCOUNT_NAME
- the name of the account created
KEY_ACCOUNT_TYPE
- the type of the account
KEY_INTENT
with the Intent
needed to launch the
password prompt. If an error occurred,
AccountManagerFuture.getResult()
throws:
AuthenticatorException
if the authenticator failed to respond
OperationCanceledException
if the operation was canceled for
any reason, including the user canceling the password prompt
IOException
if the authenticator experienced an I/O problem
verifying the password, usually because of network trouble
public AccountManagerFuture<Bundle> editProperties(String accountType, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
This method may be called from any thread, but the returned
AccountManagerFuture
must not be used on the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#MANAGE_ACCOUNTS
.
accountType
- The account type associated with the authenticator
to adjustactivity
- The Activity
context to use for launching a new
authenticator-defined sub-Activity to adjust authenticator settings;
used only to call startActivity(); if null, the settings dialog will
not be launched directly, but the necessary Intent
will be
returned to the caller insteadcallback
- Callback to invoke when the request completes,
null for no callbackhandler
- Handler
identifying the callback thread,
null for the main threadAccountManagerFuture
which resolves to a Bundle
which is empty if properties were edited successfully, or
if no activity was specified, contains only KEY_INTENT
needed to launch the authenticator's settings dialog.
If an error occurred, AccountManagerFuture.getResult()
throws:
AuthenticatorException
if no authenticator was registered for
this account type or the authenticator failed to respond
OperationCanceledException
if the operation was canceled for
any reason, including the user canceling the settings dialog
IOException
if the authenticator experienced an I/O problem
updating settings, usually because of network trouble
public AccountManagerFuture<Bundle> getAuthTokenByFeatures(String accountType, String authTokenType, String[] features, Activity activity, Bundle addAccountOptions, Bundle getAuthTokenOptions, AccountManagerCallback<Bundle> callback, Handler handler)
getAccountsByTypeAndFeatures(java.lang.String, java.lang.String[], android.accounts.AccountManagerCallback<android.accounts.Account[]>, android.os.Handler)
, getAuthToken(android.accounts.Account, java.lang.String, android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler)
, and
addAccount(java.lang.String, java.lang.String, java.lang.String[], android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler)
.
This method gets a list of the accounts matching the specified type and feature set; if there is exactly one, it is used; if there are more than one, the user is prompted to pick one; if there are none, the user is prompted to add one. Finally, an auth token is acquired for the chosen account.
This method may be called from any thread, but the returned
AccountManagerFuture
must not be used on the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#MANAGE_ACCOUNTS
.
accountType
- The account type required
(see getAccountsByType(java.lang.String)
), must not be nullauthTokenType
- The desired auth token type
(see getAuthToken(android.accounts.Account, java.lang.String, android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler)
), must not be nullfeatures
- Required features for the account
(see getAccountsByTypeAndFeatures(java.lang.String, java.lang.String[], android.accounts.AccountManagerCallback<android.accounts.Account[]>, android.os.Handler)
), may be null or emptyactivity
- The Activity
context to use for launching new
sub-Activities to prompt to add an account, select an account,
and/or enter a password, as necessary; used only to call
startActivity(); should not be nulladdAccountOptions
- Authenticator-specific options to use for
adding new accounts; may be null or emptygetAuthTokenOptions
- Authenticator-specific options to use for
getting auth tokens; may be null or emptycallback
- Callback to invoke when the request completes,
null for no callbackhandler
- Handler
identifying the callback thread,
null for the main threadAccountManagerFuture
which resolves to a Bundle with
at least the following fields:
KEY_ACCOUNT_NAME
- the name of the account
KEY_ACCOUNT_TYPE
- the type of the account
KEY_AUTHTOKEN
- the auth token you wanted
AccountManagerFuture.getResult()
throws:
AuthenticatorException
if no authenticator was registered for
this account type or the authenticator failed to respond
OperationCanceledException
if the operation was canceled for
any reason, including the user canceling any operation
IOException
if the authenticator experienced an I/O problem
updating settings, usually because of network trouble
public static Intent newChooseAccountIntent(Account selectedAccount, ArrayList<Account> allowableAccounts, String[] allowableAccountTypes, boolean alwaysPromptForAccount, String descriptionOverrideText, String addAccountAuthTokenType, String[] addAccountRequiredFeatures, Bundle addAccountOptions)
Activity
that prompts the user to choose from a list of
accounts.
The caller will then typically start the activity by calling
startActivityWithResult(intent, ...);
.
On success the activity returns a Bundle with the account name and type specified using
keys KEY_ACCOUNT_NAME
and KEY_ACCOUNT_TYPE
.
The most common case is to call this with one account type, e.g.:
newChooseAccountsIntent(null, null, new String[]{"com.google"}, false, null, null, null, null);
selectedAccount
- if specified, indicates that the Account
is the currently
selected one, according to the caller's definition of selected.allowableAccounts
- an optional ArrayList
of accounts that are allowed to be
shown. If not specified then this field will not limit the displayed accounts.allowableAccountTypes
- an optional string array of account types. These are used
both to filter the shown accounts and to filter the list of account types that are shown
when adding an account.alwaysPromptForAccount
- if set the account chooser screen is always shown, otherwise
it is only shown when there is more than one account from which to choosedescriptionOverrideText
- if non-null this string is used as the description in the
accounts chooser screen rather than the defaultaddAccountAuthTokenType
- this string is passed as the addAccount(java.lang.String, java.lang.String, java.lang.String[], android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler)
authTokenType parameteraddAccountRequiredFeatures
- this string array is passed as the addAccount(java.lang.String, java.lang.String, java.lang.String[], android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler)
requiredFeatures parameteraddAccountOptions
- This Bundle
is passed as the addAccount(java.lang.String, java.lang.String, java.lang.String[], android.os.Bundle, android.app.Activity, android.accounts.AccountManagerCallback<android.os.Bundle>, android.os.Handler)
options
parameterIntent
that can be used to launch the ChooseAccount activity flow.public void addOnAccountsUpdatedListener(OnAccountsUpdateListener listener, Handler handler, boolean updateImmediately)
OnAccountsUpdateListener
to this instance of the
AccountManager
. This listener will be notified whenever the
list of accounts on the device changes.
As long as this listener is present, the AccountManager instance
will not be garbage-collected, and neither will the Context
used to retrieve it, which may be a large Activity instance. To avoid
memory leaks, you must remove this listener before then. Normally
listeners are added in an Activity or Service's Activity.onCreate(android.os.Bundle)
and removed in Activity.onDestroy()
.
It is safe to call this method from the main thread.
This method requires the caller to hold the permission
android.Manifest.permission#GET_ACCOUNTS
.
listener
- The listener to send notifications tohandler
- Handler
identifying the thread to use
for notifications, null for the main threadupdateImmediately
- If true, the listener will be invoked
(on the handler thread) right away with the current account listIllegalArgumentException
- if listener is nullIllegalStateException
- if listener was already addedpublic void removeOnAccountsUpdatedListener(OnAccountsUpdateListener listener)
OnAccountsUpdateListener
previously registered with
addOnAccountsUpdatedListener(android.accounts.OnAccountsUpdateListener, android.os.Handler, boolean)
. The listener will no longer
receive notifications of account changes.
It is safe to call this method from the main thread.
No permission is required to call this method.
listener
- The previously added listener to removeIllegalArgumentException
- if listener is nullIllegalStateException
- if listener was not already added