diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index e9cdf59666c6c9a27af9484ecbc401f131bd0bfc..9c225026165d18d24c17bbae3f3ded66cc4c5d83 100644 --- a/en/application-dev/reference/apis/Readme-EN.md +++ b/en/application-dev/reference/apis/Readme-EN.md @@ -381,6 +381,7 @@ - Account Management - [@ohos.account.appAccount (App Account Management)](js-apis-appAccount.md) + - [@ohos.account.appAccount.AuthorizationExtensionAbility (App Account AuthorizationExtensionAbility)](js-apis-appAccount-authorizationExtensionAbility.md) - [@ohos.account.distributedAccount (Distributed Account Management)](js-apis-distributed-account.md) - [@ohos.account.osAccount (OS Account Management)](js-apis-osAccount.md) diff --git a/en/application-dev/reference/apis/js-apis-appAccount-authorizationExtensionAbility.md b/en/application-dev/reference/apis/js-apis-appAccount-authorizationExtensionAbility.md new file mode 100644 index 0000000000000000000000000000000000000000..dd40fcecca457706871fa85fd8ed4dded9734d67 --- /dev/null +++ b/en/application-dev/reference/apis/js-apis-appAccount-authorizationExtensionAbility.md @@ -0,0 +1,70 @@ +# @ohos.account.appAccount.AuthorizationExtensionAbility (App AuthorizationExtensionAbility) + +The **AuthorizationExtensionAbility** module provides APIs for implementing authorization to app accounts based on the ExtensionAbility framework. + +> **NOTE** +> +> The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version. + +## Modules to Import + +```ts +import AuthorizationExtensionAbility, { AuthorizationRequest, AuthorizationCallback } from '@ohos.account.appAccount.AuthorizationExtensionAbility'; +``` + +## AuthorizationRequest + +Defines the app account authorization request. + +**System API**: This is a system API. + +**System capability**: SystemCapability.Account.AppAccount + +| Name | Type | Readable| Writable| Description | +| --------- | ------------------------------- | ---- | ---- | ------------------------------------ | +| callerUid | number | Yes | No | UID of the caller.| +| parameters | [appAccount.AccountCapabilityRequest](js-apis-appAccount.md#accountcapabilityrequest10) | Yes | No | Service parameters.| + +## AuthorizationCallback + +Provides callbacks to be invoked during the app account authorization. + +**System API**: This is a system API. + +**System capability**: SystemCapability.Account.AppAccount + +| Name | Type | Readable| Writable| Description | +| --------- | ------------------------------- | ---- | ---- | ------------------------------------ | +| onResult | AsyncCallback<[appAccount.AccountCapabilityResponse](js-apis-appAccount.md#accountcapabilityresponse10), { [key: string]: object }> | Yes | No | Callback invoked to return the authorization result.| + +## AuthorizationExtensionAbility.onStartAuthorization + +onStartAuthorization(request: AuthorizationRequest, callback: AuthorizationCallback): void + +Called when an authorization request is received. + +**System API**: This is a system API. + +**System capability**: SystemCapability.Account.AppAccount + +**Parameters** + +| Name | Type | Mandatory | Description | +| -------- | ---------------------------------------- | ---- | ----------------------- | +| request | [AuthorizationRequest](#authorizationrequest) | Yes | Authorization request information.| +| callback | [AuthorizationCallback](#authorizationcallback) | Yes | Authorization callback object.| + +**Example** + +```ts +class MyAuthorizationExtensionAbility extends AuthorizationExtensionAbility { + onStartAuthorization(request: AuthorizationRequest, callback: AuthorizationCallback) { + console.log('onStartAuthorization, callerUid: ' + request.callerUid + ', parameters: ' + request.parameters); + let response = { + name: 'xxxx', + scopes: ['xxx', 'xxx'] + }; + callback.onResult(null, response); + } +}; +``` diff --git a/en/application-dev/reference/apis/js-apis-appAccount.md b/en/application-dev/reference/apis/js-apis-appAccount.md index 6bb26ca37ab1d320d904cdaa17c5a100291f322c..ddf515f985c2f34bad319ddceb564307f73f1b95 100644 --- a/en/application-dev/reference/apis/js-apis-appAccount.md +++ b/en/application-dev/reference/apis/js-apis-appAccount.md @@ -132,7 +132,7 @@ Creates an app account with custom data. This API uses a promise to return the r | Name | Type | Mandatory | Description | | --------- | ------ | ---- | ---------------------------------------- | | name | string | Yes | Name of the app account to create. | -| options | [CreateAccountOptions](#createaccountoptions9) | No | Options for creating the app account. You can customize data based on service requirements, but do not add sensitive data (such as passwords and tokens).
By default, no value is passed, which means no additional information needs to be added for the account.| +| options | [CreateAccountOptions](#createaccountoptions9) | No | Options for creating the app account. You can customize data based on service requirements, but do not add sensitive data (such as passwords and tokens).
By default, no value is passed, which means no additional information needs to be added for the account.| **Return value** @@ -730,7 +730,7 @@ Sets a credential for an app account. This API uses an asynchronous callback to | ID| Error Message| | ------- | -------| | 12300001 | System service exception. | -| 12300002 | Invalid name or credentialType or credential. | +| 12300002 | Invalid name, credentialType, or credential. | | 12300003 | Account not found. | **Example** @@ -776,7 +776,7 @@ Sets a credential for an app account. This API uses a promise to return the resu | ID| Error Message| | ------- | -------| | 12300001 | System service exception. | -| 12300002 | Invalid name or credentialType or credential. | +| 12300002 | Invalid name, credentialType, or credential. | | 12300003 | Account not found. | **Example** @@ -2780,7 +2780,7 @@ Adds an app account name and additional information. This API uses an asynchrono | Name | Type | Mandatory | Description | | --------- | ------ | ---- | ---------------------------------------- | | name | string | Yes | Name of the target app account. | -| extraInfo | string | No | Additional information (information that can be converted to the string type).
The additional information cannot be sensitive information (such as the password and token) of the app account.
By default, no value is passed, which means no additional information needs to be added for the account.| +| extraInfo | string | No | Additional information (information that can be converted to the string type).
The additional information cannot be sensitive information (such as the password and token) of the app account.
By default, no value is passed, which means no additional information needs to be added for the account.| **Return value** @@ -4982,3 +4982,298 @@ Obtains the remote object of an authenticator. This API cannot be overloaded. } } ``` + +## AccountCapabilityType10+ + +Enumerates the account capability types. + +**System capability**: SystemCapability.Account.AppAccount + +| Name | Value | Description | +| ---------------- | ----- | ----------------------- | +| AUTHORIZATION | 1 | Authorization capability. | + +## AccountCapabilityProvider10+ + +Represents the **AccountCapabilityProvider** class. + +### Attributes + +**System capability**: SystemCapability.Account.AppAccount + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| capabilityType | [AccountCapabilityType](#accountcapabilitytype10) | Yes| No| Capability type of the account.| + +### constructor10+ + +constructor(capabilityType: AccountCapabilityType) + +A constructor used to create an **AccountCapabilityProvider** instance. + +**System capability**: SystemCapability.Account.AppAccount + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------- | +| capabilityType | [AccountCapabilityType](#accountcapabilitytype10) | Yes | Capability type of the account. | + +**Example** + +```ts +class MyAuthorizationProvider extends account_appAccount.AccountCapabilityProvider { + constructor() { + super(account_appAccount.AccountCapabilityType.AUTHORIZATION); + } +} + +try { + let provider = new MyAuthorizationProvider(); + if (provider instanceof account_appAccount.AccountCapabilityProvider) { + console.log("the provider is an instance of AccountCapabilityProvider"); + } +} catch (err) { + console.error('catch error: ' + JSON.stringify(err)); +} +``` + +## AccountCapabilityRequest10+ + +Represents the **AccountCapabilityRequest** class. + +### constructor10+ + +constructor(provider: AccountCapabilityProvider) + +A constructor used to create an **AccountCapabilityRequest** instance. + +**System capability**: SystemCapability.Account.AppAccount + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------- | +| provider | [AccountCapabilityProvider](#accountcapabilityprovider10) | Yes | Provider of the account capability. | + +**Example** + +```ts +class MyAuthorizationProvider extends account_appAccount.AccountCapabilityProvider { + constructor() { + super(account_appAccount.AccountCapabilityType.AUTHORIZATION); + } +} + +class MyAuthorizationRequest extends account_appAccount.AccountCapabilityRequest { + constructor() { + let provider = new MyAuthorizationProvider(); + super(provider); + } +} + +try { + let request = new MyAuthorizationRequest(); + if (request instanceof account_appAccount.AccountCapabilityRequest) { + console.log("the request is an instance of AccountCapabilityRequest"); + } +} catch (err) { + console.error('catch error: ' + JSON.stringify(err)); +} +``` + +## AccountCapabilityResponse10+ + +Represents the **AccountCapabilityResponse** class. + +### Attributes + +**System capability**: SystemCapability.Account.AppAccount + +| Name| Type| Readable| Writable| Description| +| -------- | -------- | -------- | -------- | -------- | +| request | [AccountCapabilityRequest](#accountcapabilityrequest10) | Yes| No| Account capability request corresponding to the response.| + +### constructor10+ + +constructor(request: AccountCapabilityRequest) + +A constructor used to create an **AccountCapabilityResponse** instance. + +**System capability**: SystemCapability.Account.AppAccount + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------- | +| request | [AccountCapabilityRequest](#accountcapabilityrequest10) | Yes | Account capability request corresponding to the response.| + +**Example** + +```ts +class MyAuthorizationProvider extends account_appAccount.AccountCapabilityProvider { + constructor() { + super(account_appAccount.AccountCapabilityType.AUTHORIZATION); + } +} + +class MyAuthorizationRequest extends account_appAccount.AccountCapabilityRequest { + constructor() { + let provider = new MyAuthorizationProvider(); + super(provider); + } +} + +class MyAuthorizationResponse extends account_appAccount.AccountCapabilityResponse { + constructor(request) { + super(request) + } +} + +try { + let request = new MyAuthorizationRequest(); + let response = new MyAuthorizationResponse(request); + if (response instanceof account_appAccount.AccountCapabilityResponse) { + console.log("the response is an instance of AccountCapabilityResponse"); + } +} catch (err) { + console.error('catch error: ' + JSON.stringify(err)); +} +``` + +## AuthorizationProviderInfo10+ + +Defines information about the authorization provider. + +**System capability**: SystemCapability.Account.AppAccount + +| Name | Type | Readable| Writable| Description | +| ------- | ------ | ---- | --- | ---------- | +| bundleName | string | Yes| No| Bundle name of the authorization provider.| +| abilityName | string | Yes| No| Ability name of the authorization provider.| + +## AuthorizationProvider10+ + +Represents the **AuthorizationProvider** class. + +### constructor10+ + +constructor(info: AuthorizationProviderInfo) + +A constructor used to create an **AuthorizationProvider** instance. + +**System capability**: SystemCapability.Account.AppAccount + +**Parameters** + +| Name| Type | Mandatory| Description | +| ------ | ------ | ---- | ------------------------------------- | +| info | [AuthorizationProviderInfo](#authorizationproviderinfo10) | Yes | Information about the authorization provider.| + +**Example** + +```ts +class MyAuthorizationProvider extends account_appAccount.AuthorizationProvider { + constructor() { + super({bundleName: 'xxx', abilityName: 'xxx'}); + } +} + +try { + let provider = new MyAuthorizationProvider(); + if (provider instanceof account_appAccount.AuthorizationProvider) { + console.log("the provider is an instance of AuthorizationProvider"); + } +} catch (err) { + console.error("catch error: " + JSON.stringify(err)); +} +``` + +## AccountCapabilityScheduler10+ + +Represents the **AccountCapabilityScheduler** class. + +### executeRequest10+ + +executeRequest(request: AccountCapabilityRequest, callback: AsyncCallback<AccountCapabilityResponse, { [key: string]: object }>): void + +Executes an account capability request. This API uses an asynchronous callback to return the result. + +**System capability**: SystemCapability.Account.AppAccount + +**Parameters** + +| Name | Type | Mandatory | Description | +| ---------- | ------------------------- | ---- | ------------------------- | +| request | [AccountCapabilityRequest](#accountcapabilityrequest10) | Yes | Account capability request to execute. | +| callback | AsyncCallback<[AccountCapabilityResponse](#accountcapabilityresponse10), { [key: string]: object }> | Yes | Callback invoked to return the result. If the operation is successful, **err** is **null**. Otherwise, **err** is an error object. | + +**Error codes** + +| ID| Error Message| +| ------- | ------- | +| 12300001 | System service exception. | +| 12300002 | Invalid request. | + +**Example** + +```ts +let scheduler = new account_appAccount.AccountCapabilityScheduler(); +let provider = new account_appAccount.AuthorizationProvider({ bundleName: 'xxx', abilityName: 'xxx' }); +let request = new account_appAccount.AccountCapabilityRequest(provider); +try { + scheduler.executeRequest(request, (err, response) => { + if (err != null) { + console.log('executeRequest failed, error: ' + JSON.stringify(err)); + } else { + console.log('executeRequest response: ' + JSON.stringify(response)); + } + }); +} catch (err) { + console.log('executeRequest exception: ' + JSON.stringify(err)); +} +``` + +### executeRequest10+ + +executeRequest(request: AccountCapabilityRequest): Promise<AccountCapabilityResponse> + +Executes an account capability request. This API uses a promise to return the result. + +**System capability**: SystemCapability.Account.AppAccount + +**Parameters** + +| Name | Type | Mandatory | Description | +| ---------- | ------- | ---- | ------------ | +| request | [AccountCapabilityRequest](#accountcapabilityrequest10) | Yes | Account capability request to execute.| + +**Return value** + +| Type | Description | +| ------------------- | --------------------- | +| Promise<[AccountCapabilityResponse](#accountcapabilityresponse10)> | Promise used to return the result. | + +**Error codes** + +| ID| Error Message| +| ------- | ------- | +| 12300001 | System service exception. | +| 12300002 | Invalid request. | + +**Example** + +```ts +let scheduler = new account_appAccount.AccountCapabilityScheduler(); +let provider = new account_appAccount.AuthorizationProvider({ bundleName: 'xxx', abilityName: 'xxx' }); +let request = new account_appAccount.AccountCapabilityRequest(provider); +try { + scheduler.executeRequest(request).then((response) => { + console.log('executeRequest response: ' + JSON.stringify(response)); + }).catch((err) => { + console.log('executeRequest failed, error: ' + JSON.stringify(err)); + }); +} catch (err) { + console.log('executeRequest exception: ' + JSON.stringify(err)); +} +```