public class AccountManager
extends Object
java.lang.Object | |
↳ | android.accounts.AccountManager |
该课程提供对用户在线帐户的集中注册表的访问。 用户每个帐户输入一次凭据(用户名和密码),通过“单击”批准授予应用程序访问在线资源的权限。
不同的在线服务具有不同的处理帐户和认证的方式,因此客户经理使用可插入的认证模块用于不同的帐户类型 。 身份验证者(可能由第三方编写)处理验证账户凭证和存储账户信息的实际细节。 例如,Google,Facebook和Microsoft Exchange都有自己的身份验证器。
许多服务器支持一些身份验证令牌的概念,该令牌可用于在不发送用户的实际密码的情况下对服务器的请求进行身份验证。 (Auth令牌通常使用包含用户凭证的单独请求创建。)AccountManager可以为应用程序生成授权令牌,因此应用程序无需直接处理密码。 Account身份验证令牌通常可以重复使用和缓存,但必须定期刷新。 当应用程序停止工作时,应用程序有责任使 auth令牌失效,以便AccountManager知道需要重新生成它们。
访问服务器的应用程序通常经历以下步骤:
get(Context)
. getAccountsByType(String)
or getAccountsByTypeAndFeatures(String, String[], AccountManagerCallback
, 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(String, String, String[], Bundle, Activity, AccountManagerCallback
, Handler)
may be called to prompt the user to create an account of the appropriate type. getAccountsByType(String)
. Requesting an auth token for an account no longer on the device results in an undefined failure. getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback
, Handler)
methods or related helpers. Refer to the description of each method for exact usage and error handling details. invalidateAuthToken(String, 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. 某些AccountManager方法可能需要与用户交互以提示输入凭据,显示选项或要求用户添加帐户。 调用者可以选择是否允许AccountManager直接启动必要的用户界面并等待用户,或者返回调用者可用来启动界面的Intent,或者(在某些情况下)安装用户可以使用的通知随时选择启动界面。 要让AccountManager直接启动界面,调用者必须提供当前前景Activity
上下文。
许多AccountManager方法以AccountManagerCallback
和Handler
为参数。 这些方法立即返回并异步运行。 如果提供了回调,则在请求完成时,将在处理程序的线程上调用run(AccountManagerFuture
,成功与否。 通过在方法返回的getResult()
上调用getResult()
来检索结果(并传递给回调AccountManagerFuture
)。 此方法等待操作完成(如有必要),并返回结果或在操作过程中发生错误时引发异常。 为了同步请求,在从方法接收未来时立即调用getResult()
; 不需要提供回调。
不得在应用程序的主事件线程中调用可能阻塞的请求,包括getResult()
。 如果它们在主线程上使用,则这些操作会抛出IllegalStateException
。
Inherited methods |
|
---|---|
From class java.lang.Object
|
String ACTION_AUTHENTICATOR_INTENT
常量值:“android.accounts.AccountAuthenticator”
String AUTHENTICATOR_ATTRIBUTES_NAME
常量值:“account-authenticator”
String AUTHENTICATOR_META_DATA_NAME
常量值:“android.accounts.AccountAuthenticator”
int ERROR_CODE_BAD_AUTHENTICATION
常量值:9(0x00000009)
int ERROR_CODE_UNSUPPORTED_OPERATION
常数值:6(0x00000006)
String KEY_ACCOUNT_AUTHENTICATOR_RESPONSE
常量值:“accountAuthenticatorResponse”
String KEY_ACCOUNT_MANAGER_RESPONSE
常数值:“accountManagerResponse”
String KEY_ACCOUNT_NAME
用于 String
帐户名称的捆绑密钥,用于返回有关特定帐户信息的方法的结果。
常量值:“authAccount”
String KEY_ACCOUNT_TYPE
用于 String
帐户类型的捆绑密钥,该密钥用于返回有关特定帐户信息的方法的结果。
常量值:“accountType”
String KEY_ANDROID_PACKAGE_NAME
调用者的Android包将被设置在AccountManager
的选项包中,并将传递给AccountManagerService和AccountAuthenticators。 AccountManagerService以及AccountAuthenticators可以知道调用者的uid,因此他们将能够验证该包是否与uid一致(uid可能会被许多包共享)。
常量值:“androidPackageName”
String KEY_AUTHENTICATOR_TYPES
常量值:“authenticator_types”
String KEY_AUTHTOKEN
用于来自 getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback
和朋友的结果中的验证令牌值的捆绑密钥。
常量值:“authtoken”
String KEY_CALLER_UID
使用'customTokens'选项的验证器也将获得调用者的UID
常量值:“callerUid”
String KEY_INTENT
Intent
密钥用于Intent
中可能需要调用者与用户交互的方法的结果。 Intent可用于启动相应的用户界面活动。
常数值:“意图”
String KEY_LAST_AUTHENTICATED_TIME
用于提供最后一次成功验证帐户凭证的捆绑密钥。 时间以纪元以来的毫秒数指定。 在添加帐户,确认凭证或更新凭证时成功验证帐户时会更新关联时间。
常量值:“lastAuthenticatedTime”
String KEY_PASSWORD
捆绑密钥用于直接在选项中提供密码至 confirmCredentials(Account, Bundle, Activity, AccountManagerCallback
,而不是用标准密码提示提示用户。
常量值:“密码”
String LOGIN_ACCOUNTS_CHANGED_ACTION
当帐户被添加,帐户被删除,或者帐户的凭证(保存的密码等)被更改时,作为广播意图由AccountsService发送的操作。
常量值:“android.accounts.LOGIN_ACCOUNTS_CHANGED”
AccountManagerFuture<Bundle> addAccount (String accountType, String authTokenType, String[] requiredFeatures, Bundle addAccountOptions, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
要求用户添加指定类型的帐户。 此帐户类型的验证器通过适当的用户界面处理此请求。 如果用户确实选择创建新帐户,则返回帐户名称。
可以从任何线程调用此方法,但返回的 AccountManagerFuture
不得在主线程上使用。
注意:如果您的应用定位在API级别22以及之前,那么这些平台需要MANAGE_ACCOUNTS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
accountType |
String : The type of account to add; must not be null |
authTokenType |
String : The type of auth token (see getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback
) this account will need to be able to generate, null for none |
requiredFeatures |
String : The features (see hasFeatures(Account, String[], AccountManagerCallback
) this account must have, null for none |
addAccountOptions |
Bundle : Authenticator-specific options for the request, may be null or empty |
activity |
Activity : 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 instead |
callback |
AccountManagerCallback : Callback to invoke when the request completes, null for no callback |
handler |
Handler : Handler identifying the callback thread, null for the main thread |
Returns | |
---|---|
AccountManagerFuture<Bundle> |
An AccountManagerFuture which resolves to a Bundle with these fields if activity was specified and an account was created:
KEY_INTENT with the Intent needed to launch the actual account creation process. If an error occurred, getResult() throws:
|
boolean addAccountExplicitly (Account account, String password, Bundle userdata)
直接向AccountManager添加一个账户。 通常由与验证器关联的注册向导使用,而不是直接由应用程序使用。
调用此方法不会更新KEY_LAST_AUTHENTICATED_TIME
所指的最后一个经过身份验证的时间戳。 要更新它,请在获得成功后致电notifyAccountAuthenticated(Account)
。 但是,如果在通过addAccount()或addAccountAsUser()或类似函数触发时调用此方法,则无需手动更新时间戳,因为它会在成功完成所提及的功能时由框架自动更新。
从主线程调用此方法是安全的。
这种方法要求调用者与拥有指定账户的认证者进行签名匹配。
注意:如果您的应用的定位要在API级别22以及之前工作,那么这些平台需要AUTHENTICATE_ACCOUNTS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The Account to add |
password |
String : The password to associate with the account, null for none |
userdata |
Bundle : String values to use for the account's userdata, null for none |
Returns | |
---|---|
boolean |
True if the account was successfully added, false if the account already exists, the account is null, or another error occurs. |
void addOnAccountsUpdatedListener (OnAccountsUpdateListener listener, Handler handler, boolean updateImmediately)
添加一个OnAccountsUpdateListener
到的此实例AccountManager
。 只要设备上的帐户列表发生更改,该监听器就会收到通知。
只要此监听器存在,AccountManager实例就不会被垃圾收集,并且Context
也不会被用于检索它,这可能是一个大型的Activity实例。 为避免内存泄漏,您必须在此之前删除此侦听器。 通常,收听者将添加到活动或服务的onCreate(Bundle)
并在onDestroy()
删除。
收听者只会被通知通过getAccounts()
返回给主叫方的getAccounts()
。 通常这意味着要获得任何账户,调用者需要获得GET_ACCOUNTS权限。
从主线程调用此方法是安全的。
Parameters | |
---|---|
listener |
OnAccountsUpdateListener : The listener to send notifications to |
handler |
Handler : Handler identifying the thread to use for notifications, null for the main thread |
updateImmediately |
boolean : If true, the listener will be invoked (on the handler thread) right away with the current account list |
Throws | |
---|---|
IllegalArgumentException |
if listener is null |
IllegalStateException |
if listener was already added |
String blockingGetAuthToken (Account account, String authTokenType, boolean notifyAuthFailure)
此便利帮助程序会同步获取具有 getAuthToken(Account, String, boolean, AccountManagerCallback, Handler)
的身份验证令牌。
此方法可能在网络请求完成时阻塞,并且绝不能从主线程中创建。
注意:如果您的应用定位在API级别22以及之前,那么这些平台需要USE_CREDENTIALS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The account to fetch an auth token for |
authTokenType |
String : The auth token type, see getAuthToken() |
notifyAuthFailure |
boolean : 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 returning |
Returns | |
---|---|
String |
An auth token of the specified type for this account, or null if authentication fails or none can be fetched. |
Throws | |
---|---|
AuthenticatorException |
if the authenticator failed to respond |
OperationCanceledException |
if the request was canceled for any reason, including 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 |
void clearPassword (Account account)
忘记保存的密码。 这将擦除密码的本地副本; 它不会更改服务器上的用户帐户密码。 与setPassword(account,null)具有相同的效果,但需要较少的权限,并且可能被应用程序或管理界面用于从帐户“注销”。
此方法只有在主叫方与拥有指定帐户的身份验证器具有相同签名时才能成功清除该帐户的密码。 否则,这种方法将无声无息地失败。
从主线程调用此方法是安全的。
注意:如果您的应用定位在API级别22以及之前,那么这些平台需要MANAGE_ACCOUNTS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The account whose password to clear |
AccountManagerFuture<Bundle> confirmCredentials (Account account, Bundle options, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
确认用户知道帐户的密码,以确保他们是帐户的所有者。 用户输入的密码可以直接提供,否则此帐户类型的验证器会提示用户使用适当的界面。 此方法适用于需要额外保证的应用程序; 例如,手机锁定屏幕会使用此功能让用户在忘记锁定模式时使用帐户密码解锁手机。
如果用户输入的密码与此帐户保存的密码匹配,则该请求被认为是有效的; 否则验证者验证密码(通常通过联系服务器)。
可以从任何线程调用此方法,但返回的 AccountManagerFuture
不得在主线程上使用。
注意:如果您的应用定位在API级别22以及之前,那么这些平台需要MANAGE_ACCOUNTS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The account to confirm password knowledge for |
options |
Bundle : 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 empty |
activity |
Activity : 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 instead |
callback |
AccountManagerCallback : Callback to invoke when the request completes, null for no callback |
handler |
Handler : Handler identifying the callback thread, null for the main thread |
Returns | |
---|---|
AccountManagerFuture<Bundle> |
An AccountManagerFuture which resolves to a Bundle with these fields if activity or password was supplied and the account was successfully verified:
KEY_INTENT with the Intent needed to launch the password prompt. 返回的Bundle也可能包含
|
AccountManagerFuture<Bundle> editProperties (String accountType, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
为用户提供更改认证者设置的机会。 这些属性通常用于验证者,而不是特定的帐户。 并非所有的验证器都支持这种方法。
可以从任何线程调用此方法,但返回的 AccountManagerFuture
不得在主线程上使用。
此方法要求调用方具有与指定帐户类型关联的认证方相同的签名。
注意:如果您的应用定位在API级别22以及之前,那么这些平台需要MANAGE_ACCOUNTS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
accountType |
String : The account type associated with the authenticator to adjust |
activity |
Activity : 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 instead |
callback |
AccountManagerCallback : Callback to invoke when the request completes, null for no callback |
handler |
Handler : Handler identifying the callback thread, null for the main thread |
Returns | |
---|---|
AccountManagerFuture<Bundle> |
An AccountManagerFuture 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, getResult() throws:
|
AccountManager get (Context context)
获取与上下文关联的AccountManager实例。 该Context
将只要是的AccountManager积极使用,所以一定要使用Context
,其寿命与注册了任何侦听器相称addOnAccountsUpdatedListener(OnAccountsUpdateListener, Handler, boolean)
或类似的方法。
从主线程调用此方法是安全的。
调用此方法不需要任何权限。
Parameters | |
---|---|
context |
Context : The Context to use when necessary |
Returns | |
---|---|
AccountManager |
An AccountManager instance |
Account[] getAccounts ()
列出设备上注册的任何类型的所有帐户。 等同于getAccountsByType(null)。
从主线程调用此方法是安全的。
尚未被授予 GET_ACCOUNTS
权限的此方法的客户端将只能看到由AbstractAccountAuthenticators管理的帐户,其签名与客户端匹配。
Returns | |
---|---|
Account[] |
An array of Account , one for each account. Empty (never null) if no accounts have been added. |
Account[] getAccountsByType (String type)
列出特定类型的所有帐户。 账户类型是与认证者和账户的有用域相对应的字符串标记。 例如,有与Google和Facebook相对应的类型。 要使用的确切字符串标记将在与相关验证器关联的地方发布。
从主线程调用此方法是安全的。
尚未被授予 GET_ACCOUNTS
权限的此方法的客户端只能看到AbstractAccountAuthenticators管理的帐户,其签名与客户端匹配。
注意:如果您的应用程序的目标是在API级别22以及之前的版本上运行,那么无论是否使用uid或签名匹配,这些平台都需要GET_ACCOUNTS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
type |
String : The type of accounts to return, null to retrieve all accounts |
Returns | |
---|---|
Account[] |
An array of Account , one per matching account. Empty (never null) if no accounts of the specified type have been added. |
AccountManagerFuture<Account[]> getAccountsByTypeAndFeatures (String type, String[] features, AccountManagerCallback<Account[]> callback, Handler handler)
列出具有某些功能的类型的所有帐户。 账户类型标识认证者(见getAccountsByType(String)
)。 帐户功能是识别符特定的字符串标识,用于标识布尔帐户属性(请参阅hasFeatures(Account, String[], AccountManagerCallback
)。
与 getAccountsByType(String)
不同,此方法调用验证器,该验证器可能会联系服务器或执行其他工作来检查帐户功能,因此该方法返回 AccountManagerFuture
。
可以从任何线程调用此方法,但返回的 AccountManagerFuture
一定不能用于主线程。
尚未被授予 GET_ACCOUNTS
权限的此方法的客户端将只能看到由AbstractAccountAuthenticators管理的帐户,其签名与客户端匹配。
Parameters | |
---|---|
type |
String : The type of accounts to return, must not be null |
features |
String : An array of the account features to require, may be null or empty 注意:如果您的应用程序的目标是在API级别22以及之前的版本上运行,那么无论是否使用uid或签名匹配,这些平台都需要GET_ACCOUNTS权限。 请参阅API级别22中有关此功能的文档。 |
callback |
AccountManagerCallback : Callback to invoke when the request completes, null for no callback |
handler |
Handler : Handler identifying the callback thread, null for the main thread |
Returns | |
---|---|
AccountManagerFuture<Account[]> |
An AccountManagerFuture which resolves to an array of Account , one per account of the specified type which matches the requested features. |
Account[] getAccountsByTypeForPackage (String type, String packageName)
在某些应用无权查看所有帐户的环境中,返回指定包可见的帐户。 此方法只能由系统应用程序调用。
Parameters | |
---|---|
type |
String : The type of accounts to return, null to retrieve all accounts |
packageName |
String : The package name of the app for which the accounts are to be returned |
Returns | |
---|---|
Account[] |
An array of Account , one per matching account. Empty (never null) if no accounts of the specified type have been added. |
AccountManagerFuture<Bundle> getAuthToken (Account account, String authTokenType, Bundle options, boolean notifyAuthFailure, AccountManagerCallback<Bundle> callback, Handler handler)
获取特定帐户的指定类型的身份验证令牌,如果用户必须输入凭据,则可选择引发通知。 此方法适用于不应立即用密码提示中断用户的后台任务和服务。
如果先前生成的身份验证令牌针对此帐户和类型进行了缓存,则会返回该令牌。 否则,如果保存的密码可用,则将其发送到服务器以生成新的身份验证令牌。 否则,将返回一个Intent
,它在启动时会提示用户输入密码。 如果设置了notifyAuthFailure参数,则还会使用相同的Intent创建状态栏通知,提醒用户他们需要在某个时间输入密码。
在这种情况下,您可能需要等待用户响应,这可能需要几小时,几天或永远。 当用户确实响应并提供新密码时,客户经理将广播LOGIN_ACCOUNTS_CHANGED_ACTION
意图,应用程序可以使用该意图再次尝试。
如果notifyAuthFailure未设置,则应用程序有责任在某个时刻启动返回的Intent。 无论哪种方式,此调用的结果都不会等待用户操作。
一些认证者具有认证令牌类型 ,其值依赖于认证者。 某些服务使用不同的令牌类型来访问不同的功能 - 例如,Google使用不同的身份验证令牌访问同一个帐户的Gmail和Google日历。
可以从任何线程调用此方法,但返回的 AccountManagerFuture
不得在主线程上使用。
注意:如果您的应用定位在API级别22以及之前,那么这些平台需要USE_CREDENTIALS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The account to fetch an auth token for |
authTokenType |
String : The auth token type, an authenticator-dependent string token, must not be null |
options |
Bundle : Authenticator-specific options for the request, may be null or empty |
notifyAuthFailure |
boolean : True to add a notification to prompt the user for a password if necessary, false to leave that to the caller |
callback |
AccountManagerCallback : Callback to invoke when the request completes, null for no callback |
handler |
Handler : Handler identifying the callback thread, null for the main thread |
Returns | |
---|---|
AccountManagerFuture<Bundle> |
An AccountManagerFuture which resolves to a Bundle with at least the following fields on success:
KEY_INTENT with the Intent needed to launch a prompt. If an error occurred, getResult() throws:
|
AccountManagerFuture<Bundle> getAuthToken (Account account, String authTokenType, Bundle options, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
获取特定帐户的指定类型的身份验证令牌,并在必要时提示用户输入凭据。 此方法适用于在前台运行的应用程序,它可以直接询问用户密码。
如果先前生成的身份验证令牌针对此帐户和类型进行了缓存,则会返回该令牌。 否则,如果保存的密码可用,则将其发送到服务器以生成新的身份验证令牌。 否则,将提示用户输入密码。
一些认证者具有认证令牌类型 ,其值依赖于认证者。 某些服务使用不同的令牌类型来访问不同的功能 - 例如,Google使用不同的身份验证令牌访问同一个帐户的Gmail和Google日历。
注意:如果您的应用定位在API级别22以及之前,那么这些平台需要USE_CREDENTIALS权限。 请参阅API级别22中有关此功能的文档。
可以从任何线程调用此方法,但返回的 AccountManagerFuture
不得在主线程上使用。
Parameters | |
---|---|
account |
Account : The account to fetch an auth token for |
authTokenType |
String : The auth token type, an authenticator-dependent string token, must not be null |
options |
Bundle : Authenticator-specific options for the request, may be null or empty |
activity |
Activity : 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 |
AccountManagerCallback : Callback to invoke when the request completes, null for no callback |
handler |
Handler : Handler identifying the callback thread, null for the main thread |
Returns | |
---|---|
AccountManagerFuture<Bundle> |
An AccountManagerFuture which resolves to a Bundle with at least the following fields:
getResult() throws:
|
AccountManagerFuture<Bundle> getAuthToken (Account account, String authTokenType, boolean notifyAuthFailure, AccountManagerCallback<Bundle> callback, Handler handler)
此方法在API级别14中已弃用。
改为使用getAuthToken(Account, String, android.os.Bundle, boolean, AccountManagerCallback, android.os.Handler)
获取特定帐户的指定类型的身份验证令牌,如果用户必须输入凭据,则可选择引发通知。 此方法适用于不应立即用密码提示中断用户的后台任务和服务。
如果先前生成的身份验证令牌针对此帐户和类型进行了缓存,则会返回该令牌。 否则,如果保存的密码可用,则将其发送到服务器以生成新的身份验证令牌。 否则,将返回一个Intent
,启动后会提示用户输入密码。 如果设置了notifyAuthFailure参数,则还会使用相同的Intent创建状态栏通知,提醒用户他们需要在某个时间输入密码。
在这种情况下,您可能需要等待用户响应,这可能需要几小时,几天或永远。 当用户确实回应并提供新密码时,客户经理将广播LOGIN_ACCOUNTS_CHANGED_ACTION
意图,哪些应用程序可以用来再次尝试。
如果notifyAuthFailure未设置,则应用程序有责任在某个时刻启动返回的Intent。 无论哪种方式,此调用的结果都不会等待用户操作。
一些认证者具有认证令牌类型 ,其值依赖于认证者。 某些服务使用不同的令牌类型来访问不同的功能 - 例如,Google使用不同的身份验证令牌访问同一个帐户的Gmail和Google日历。
可以从任何线程调用此方法,但返回的 AccountManagerFuture
不得在主线程上使用。
Parameters | |
---|---|
account |
Account : The account to fetch an auth token for |
authTokenType |
String : The auth token type, an authenticator-dependent string token, must not be null |
notifyAuthFailure |
boolean : True to add a notification to prompt the user for a password if necessary, false to leave that to the caller |
callback |
AccountManagerCallback : Callback to invoke when the request completes, null for no callback |
handler |
Handler : Handler identifying the callback thread, null for the main thread |
Returns | |
---|---|
AccountManagerFuture<Bundle> |
An AccountManagerFuture which resolves to a Bundle with at least the following fields on success:
KEY_INTENT with the Intent needed to launch a prompt. If an error occurred, getResult() throws:
|
AccountManagerFuture<Bundle> getAuthTokenByFeatures (String accountType, String authTokenType, String[] features, Activity activity, Bundle addAccountOptions, Bundle getAuthTokenOptions, AccountManagerCallback<Bundle> callback, Handler handler)
这种便利的辅助相结合的功能 getAccountsByTypeAndFeatures(String, String[], AccountManagerCallback
, getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback
,并 addAccount(String, String, String[], Bundle, Activity, AccountManagerCallback
。
此方法获取与指定类型和功能集匹配的帐户列表; 如果只有一个,则使用它; 如果有多个,则提示用户选择一个; 如果没有,则提示用户添加一个。 最后,为所选帐户获取身份验证令牌。
可以从任何线程调用此方法,但返回的 AccountManagerFuture
不得在主线程上使用。
注意:如果您的应用定位在API级别22以及之前,那么这些平台需要MANAGE_ACCOUNTS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
accountType |
String : The account type required (see getAccountsByType(String) ), must not be null |
authTokenType |
String : The desired auth token type (see getAuthToken(Account, String, Bundle, Activity, AccountManagerCallback
), must not be null |
features |
String : Required features for the account (see getAccountsByTypeAndFeatures(String, String[], AccountManagerCallback
), may be null or empty |
activity |
Activity : 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 null |
addAccountOptions |
Bundle : Authenticator-specific options to use for adding new accounts; may be null or empty |
getAuthTokenOptions |
Bundle : Authenticator-specific options to use for getting auth tokens; may be null or empty |
callback |
AccountManagerCallback : Callback to invoke when the request completes, null for no callback |
handler |
Handler : Handler identifying the callback thread, null for the main thread |
Returns | |
---|---|
AccountManagerFuture<Bundle> |
An AccountManagerFuture which resolves to a Bundle with at least the following fields:
getResult() throws:
|
AuthenticatorDescription[] getAuthenticatorTypes ()
列出当前注册的认证者。
从主线程调用此方法是安全的。
调用此方法不需要任何权限。
Returns | |
---|---|
AuthenticatorDescription[] |
An array of AuthenticatorDescription for every authenticator known to the AccountManager service. Empty (never null) if no authenticators are known. |
String getPassword (Account account)
获取与该帐户关联的已保存密码。 这是针对验证者和相关代码的; 应用程序应该获取身份验证令牌。
从主线程调用此方法是安全的。
这种方法要求调用者与拥有指定账户的认证者进行签名匹配。
注意:如果您的应用的定位要在API级别22以及之前工作,那么这些平台需要AUTHENTICATE_ACCOUNTS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The account to query for a password. Must not be null . |
Returns | |
---|---|
String |
The account's password, null if none or if the account doesn't exist |
String getPreviousName (Account account)
获取与帐户关联的以前的名称或null
,如果没有。 这样做的目的是让LOGIN_ACCOUNTS_CHANGED_ACTION
广播的客户端可以确定验证者是否重命名了一个帐户。
从主线程调用此方法是安全的。
Parameters | |
---|---|
account |
Account : The account to query for a previous name. |
Returns | |
---|---|
String |
The account's previous name, null if the account has never been renamed. |
String getUserData (Account account, String key)
获取与该帐户关联的“key”指定的用户数据。 这是用于验证器和相关代码以将任意元数据与帐户一起存储。 密钥和值的含义取决于帐户的身份验证器。
从主线程调用此方法是安全的。
这种方法要求调用者与拥有指定账户的认证者进行签名匹配。
注意:如果您的应用的定位要在API级别22以及之前工作,那么这些平台需要AUTHENTICATE_ACCOUNTS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The account to query for user data |
key |
String
|
Returns | |
---|---|
String |
The user data, null if the account or key doesn't exist |
AccountManagerFuture<Boolean> hasFeatures (Account account, String[] features, AccountManagerCallback<Boolean> callback, Handler handler)
了解特定帐户是否具有所有指定的功能。 帐户功能是用于识别布尔帐户属性的特定于验证者的字符串标记。 例如,功能用于判断Google帐户是否启用了特定服务(如Google日历或Google Talk)。 功能名称及其含义与相关验证器相关联。
可以从任何线程调用此方法,但不得在主线程上使用返回的 AccountManagerFuture
。
此方法要求调用方拥有权限 GET_ACCOUNTS
或与管理帐户的AbstractAccountAuthenticator进行签名匹配。
Parameters | |
---|---|
account |
Account : The Account to test |
features |
String : An array of the account features to check |
callback |
AccountManagerCallback : Callback to invoke when the request completes, null for no callback |
handler |
Handler : Handler identifying the callback thread, null for the main thread |
Returns | |
---|---|
AccountManagerFuture<Boolean> |
An AccountManagerFuture which resolves to a Boolean, true if the account exists and has all of the specified features. |
void invalidateAuthToken (String accountType, String authToken)
从AccountManager的缓存中删除身份验证令牌。 如果身份验证令牌当前不在缓存中,则不执行任何操作。 如果发现身份验证令牌已过期,或者无法验证请求,则应用程序必须调用此方法。 否则,AccountManager不会验证或过期缓存的授权令牌。
从主线程调用此方法是安全的。
注意:如果您的应用的定位要在API级别22以及之前工作,那么这些平台需要MANAGE_ACCOUNTS或USE_CREDENTIALS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
accountType |
String : The account type of the auth token to invalidate, must not be null |
authToken |
String : The auth token to invalidate, may be null |
Intent newChooseAccountIntent (Account selectedAccount, List<Account> allowableAccounts, String[] allowableAccountTypes, String descriptionOverrideText, String addAccountAuthTokenType, String[] addAccountRequiredFeatures, Bundle addAccountOptions)
返回提示用户从帐户列表中进行选择的Activity
的意图。 呼叫者通常将通过呼叫startActivityForResult(intent, ...);
开始活动。
成功时,活动将返回一个捆绑包,其中包含使用密钥 KEY_ACCOUNT_NAME
和 KEY_ACCOUNT_TYPE
指定的帐户名称和类型。
最常见的情况是用一种账户类型来调用它,例如:
newChooseAccountIntent(null, null, new String[]{"com.google"}, null, null, null, null);
Parameters | |
---|---|
selectedAccount |
Account : if specified, indicates that the Account is the currently selected one, according to the caller's definition of selected. |
allowableAccounts |
List : an optional List of accounts that are allowed to be shown. If not specified then this field will not limit the displayed accounts. |
allowableAccountTypes |
String : 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. If not specified then this field will not limit the displayed account types when adding an account. |
descriptionOverrideText |
String : if non-null this string is used as the description in the accounts chooser screen rather than the default |
addAccountAuthTokenType |
String : this string is passed as the addAccount(String, String, String[], Bundle, Activity, AccountManagerCallback
authTokenType parameter |
addAccountRequiredFeatures |
String : this string array is passed as the addAccount(String, String, String[], Bundle, Activity, AccountManagerCallback
requiredFeatures parameter |
addAccountOptions |
Bundle : This Bundle is passed as the addAccount(String, String, String[], Bundle, Activity, AccountManagerCallback
options parameter |
Returns | |
---|---|
Intent |
an Intent that can be used to launch the ChooseAccount activity flow. |
Intent newChooseAccountIntent (Account selectedAccount, ArrayList<Account> allowableAccounts, String[] allowableAccountTypes, boolean alwaysPromptForAccount, String descriptionOverrideText, String addAccountAuthTokenType, String[] addAccountRequiredFeatures, Bundle addAccountOptions)
已弃用,因newChooseAccountIntent(Account, List, String[], String, String, String[], Bundle)
。 返回提示用户从帐户列表中进行选择的Activity
的意图。 呼叫者通常将通过呼叫startActivityForResult(intent, ...);
开始该活动。
成功后,活动将返回一个捆绑软件,其中包含使用密钥 KEY_ACCOUNT_NAME
和 KEY_ACCOUNT_TYPE
指定的帐户名称和类型。
最常见的情况是用一种账户类型来调用它,例如:
newChooseAccountIntent(null, null, new String[]{"com.google"}, false, null, null, null, null);
Parameters | |
---|---|
selectedAccount |
Account : if specified, indicates that the Account is the currently selected one, according to the caller's definition of selected. |
allowableAccounts |
ArrayList : an optional List of accounts that are allowed to be shown. If not specified then this field will not limit the displayed accounts. |
allowableAccountTypes |
String : 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. If not specified then this field will not limit the displayed account types when adding an account. |
alwaysPromptForAccount |
boolean : boolean that is ignored. |
descriptionOverrideText |
String : if non-null this string is used as the description in the accounts chooser screen rather than the default |
addAccountAuthTokenType |
String : this string is passed as the addAccount(String, String, String[], Bundle, Activity, AccountManagerCallback
authTokenType parameter |
addAccountRequiredFeatures |
String : this string array is passed as the addAccount(String, String, String[], Bundle, Activity, AccountManagerCallback
requiredFeatures parameter |
addAccountOptions |
Bundle : This Bundle is passed as the addAccount(String, String, String[], Bundle, Activity, AccountManagerCallback
options parameter |
Returns | |
---|---|
Intent |
an Intent that can be used to launch the ChooseAccount activity flow. |
boolean notifyAccountAuthenticated (Account account)
通知系统该帐户刚通过验证。 此信息可能被其他应用程序用于验证帐户。 只有在用户输入了正确的帐户凭证时才应该调用此选项。
从主线程调用此方法并不安全。 因此,从另一个线程调用它。
这种方法要求调用者与拥有指定账户的认证者进行签名匹配。
Parameters | |
---|---|
account |
Account : The Account to be updated. |
Returns | |
---|---|
boolean |
boolean true if the authentication of the account has been successfully acknowledged. Otherwise false . |
String peekAuthToken (Account account, String authTokenType)
从AccountManager的缓存中获取身份验证令牌。 如果此帐户没有对身份验证令牌进行缓存,则会返回空值 - 将不会生成新的身份验证令牌,并且不会与服务器联系。 旨在供认证者使用,而不是直接由应用程序使用。
从主线程调用此方法是安全的。
此方法要求主叫方与管理指定帐户的鉴定人进行签名匹配。
注意:如果您的应用的目标是在API级别22以及之前工作,那么这些平台需要AUTHENTICATE_ACCOUNTS权限和与帐户身份验证器相同的UID。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The account for which an auth token is to be fetched. Cannot be null . |
authTokenType |
String : The type of auth token to fetch. Cannot be null . |
Returns | |
---|---|
String |
The cached auth token for this account and type, or null if no auth token is cached or the account does not exist. |
AccountManagerFuture<Bundle> removeAccount (Account account, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
从AccountManager中删除一个帐户。 如果帐户不存在,则不做任何事。 不要从服务器上删除帐户。 验证者可能有自己的策略来防止账户被删除,在这种情况下,账户不会被删除。
可以从任何线程调用此方法,但返回的 AccountManagerFuture
不得在主线程上使用。
此方法要求主叫方与管理指定帐户的鉴定人进行签名匹配。
注意:如果您的应用定位在API级别22以及之前,那么这些平台需要MANAGE_ACCOUNTS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The Account to remove |
activity |
Activity : The Activity context to use for launching a new authenticator-defined sub-Activity to prompt the user to delete an account; used only to call startActivity(); if null, the prompt will not be launched directly, but the Intent may be returned to the caller instead |
callback |
AccountManagerCallback : Callback to invoke when the request completes, null for no callback |
handler |
Handler : Handler identifying the callback thread, null for the main thread |
Returns | |
---|---|
AccountManagerFuture<Bundle> |
An AccountManagerFuture which resolves to a Bundle with KEY_BOOLEAN_RESULT if activity was specified and an account was removed or if active. If no activity was specified, the returned Bundle contains only KEY_INTENT with the Intent needed to launch the actual account removal process, if authenticator needs the activity launch. If an error occurred, getResult() throws:
|
AccountManagerFuture<Boolean> removeAccount (Account account, AccountManagerCallback<Boolean> callback, Handler handler)
此方法在API级别22中已弃用。
改为使用removeAccount(Account, Activity, AccountManagerCallback, Handler)
从AccountManager中删除一个帐户。 如果帐户不存在,则不做任何事。 不要从服务器上删除帐户。 验证者可能有自己的策略来防止账户被删除,在这种情况下,账户不会被删除。
此方法要求主叫方与管理指定帐户的鉴定人进行签名匹配。
注意:如果您的应用定位在API级别22以及之前,那么这些平台需要MANAGE_ACCOUNTS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The Account to remove |
callback |
AccountManagerCallback : Callback to invoke when the request completes, null for no callback |
handler |
Handler : Handler identifying the callback thread, null for the main thread |
Returns | |
---|---|
AccountManagerFuture<Boolean> |
An AccountManagerFuture which resolves to a Boolean, true if the account has been successfully removed |
boolean removeAccountExplicitly (Account account)
直接删除帐户。 通常由认证者使用,而不是直接由应用程序使用。 不要从服务器上删除帐户。 验证者可能有自己的策略来防止账户被删除,在这种情况下,账户不会被删除。
从主线程调用此方法是安全的。
此方法要求主叫方与管理指定帐户的鉴定人进行签名匹配。
注意:如果您的应用的目标是在API级别22以及之前工作,那么这些平台需要AUTHENTICATE_ACCOUNTS权限和与帐户身份验证器相同的UID。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The Account to delete. |
Returns | |
---|---|
boolean |
True if the account was successfully deleted, false if the account did not exist, the account is null, or another error occurs. |
void removeOnAccountsUpdatedListener (OnAccountsUpdateListener listener)
删除一个OnAccountsUpdateListener
先前注册addOnAccountsUpdatedListener(OnAccountsUpdateListener, Handler, boolean)
。 监听者将不再收到帐户更改的通知。
从主线程调用此方法是安全的。
调用此方法不需要任何权限。
Parameters | |
---|---|
listener |
OnAccountsUpdateListener : The previously added listener to remove |
Throws | |
---|---|
IllegalArgumentException |
if listener is null |
IllegalStateException |
if listener was not already added |
AccountManagerFuture<Account> renameAccount (Account account, String newName, AccountManagerCallback<Account> callback, Handler handler)
重命名指定的Account
。 这相当于删除现有帐户并添加一个新的重命名帐户与旧帐户的用户数据。
从主线程调用此方法是安全的。
此方法要求主叫方与管理指定帐户的鉴定人进行签名匹配。
注意:如果您的应用的目标是在API级别22以及之前工作,那么这些平台需要AUTHENTICATE_ACCOUNTS权限和与帐户身份验证器相同的UID。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The Account to rename |
newName |
String : String name to be associated with the account. |
callback |
AccountManagerCallback : Callback to invoke when the request completes, null for no callback |
handler |
Handler : Handler identifying the callback thread, null for the main thread |
Returns | |
---|---|
AccountManagerFuture<Account> |
An AccountManagerFuture which resolves to the Account after the name change. If successful the account's name will be the specified new name. |
void setAuthToken (Account account, String authTokenType, String authToken)
为账户添加一个授权令牌给AccountManager缓存。 如果该帐户不存在,则该呼叫不起作用。 替换此帐户的任何先前授权令牌和授权令牌类型。 旨在供认证者使用,而不是直接由应用程序使用。
从主线程调用此方法是安全的。
此方法要求主叫方与管理指定帐户的鉴定人进行签名匹配。
注意:如果您的应用的目标是在API级别22以及之前工作,那么这些平台需要AUTHENTICATE_ACCOUNTS权限和与帐户身份验证器相同的UID。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The account to set an auth token for |
authTokenType |
String : The type of the auth token, see {#getAuthToken} |
authToken |
String : The auth token to add to the cache |
void setPassword (Account account, String password)
设置或忘记保存的密码。 这会修改用于自动验证用户的密码的本地副本; 它不会更改服务器上的用户帐户密码。 旨在供认证者使用,而不是直接由应用程序使用。
调用此方法不会更新由KEY_LAST_AUTHENTICATED_TIME
引用的最后一个经过身份验证的时间戳。 要更新它,请在获得成功后致电notifyAccountAuthenticated(Account)
。
从主线程调用此方法是安全的。
此方法要求主叫方与管理指定帐户的鉴定人进行签名匹配。
注意:如果您的应用的目标是在API级别22以及之前工作,那么这些平台需要AUTHENTICATE_ACCOUNTS权限和与帐户身份验证器相同的UID。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The account whose password is to be set. Cannot be null . |
password |
String : The password to set, null to clear the password |
void setUserData (Account account, String key, String value)
为帐户设置一个用户数据键。 用于认证者为自己存储状态,而不是直接由应用程序使用。 密钥和值的含义取决于认证者。
从主线程调用此方法是安全的。
此方法要求主叫方与管理指定帐户的鉴定人进行签名匹配。
注意:如果您的应用的目标是在API级别22以及之前工作,那么这些平台需要AUTHENTICATE_ACCOUNTS权限和与帐户身份验证器相同的UID。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : Account whose user data is to be set. Must not be null . |
key |
String : String user data key to set. Must not be null |
value |
String : String value to set, null to clear this user data key |
AccountManagerFuture<Bundle> updateCredentials (Account account, String authTokenType, Bundle options, Activity activity, AccountManagerCallback<Bundle> callback, Handler handler)
要求用户输入一个帐户的新密码,更新该帐户保存的凭证。 通常,当服务器在auth令牌获取期间拒绝凭证时,会自动发生这种情况,但可以直接调用此凭据以确保存储正确的凭据。
可以从任何线程调用此方法,但返回的 AccountManagerFuture
不得在主线程上使用。
注意:如果您的应用定位在API级别22以及之前,那么这些平台需要MANAGE_ACCOUNTS权限。 请参阅API级别22中有关此功能的文档。
Parameters | |
---|---|
account |
Account : The account to update credentials for |
authTokenType |
String : The credentials entered must allow an auth token of this type to be created (but no actual auth token is returned); may be null |
options |
Bundle : Authenticator-specific options for the request; may be null or empty |
activity |
Activity : 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 instead |
callback |
AccountManagerCallback : Callback to invoke when the request completes, null for no callback |
handler |
Handler : Handler identifying the callback thread, null for the main thread |
Returns | |
---|---|
AccountManagerFuture<Bundle> |
An AccountManagerFuture which resolves to a Bundle with these fields if an activity was supplied and the account credentials were successfully updated:
KEY_INTENT with the Intent needed to launch the password prompt. If an error occurred, getResult() throws:
|