From eb928545d397abb53aef0c138f0dc8e5b576d167 Mon Sep 17 00:00:00 2001 From: Annie_wang Date: Fri, 14 Jul 2023 18:04:37 +0800 Subject: [PATCH] update docs Signed-off-by: Annie_wang --- .../reference/apis/Readme-EN.md | 1 + ...ppAccount-authorizationExtensionAbility.md | 70 ++++ .../reference/apis/js-apis-appAccount.md | 303 +++++++++++++++++- 3 files changed, 370 insertions(+), 4 deletions(-) create mode 100644 en/application-dev/reference/apis/js-apis-appAccount-authorizationExtensionAbility.md diff --git a/en/application-dev/reference/apis/Readme-EN.md b/en/application-dev/reference/apis/Readme-EN.md index e9cdf59666..9c22502616 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 0000000000..dd40fcecca --- /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 6bb26ca37a..ddf515f985 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)); +} +``` -- GitLab