Skip to content

D
Docs

OpenHarmony / Docs
大约 2 年 前同步成功

通知 161
Star 293
Fork 28
D
Docs
“d24d282a7ae585e25faab3c9e4252d586757f5dc”上不存在“paddle/fluid/git@gitcode.net:Crayonxin2000/Paddle.git”
提交 b87b0a2e 编写于 作者: A Annie_wang
浏览文件
操作

update docs 

Signed-off-by: NAnnie_wang <annie.wangli@huawei.com>
上级 19d0e8d3
隐藏空白更改
内联 并排
Showing with 124 addition and 141 deletion
en/application-dev/reference/apis/js-apis-abilityAccessCtrl.md
浏览文件 @ b87b0a2e
......@@ -720,4 +720,4 @@ Defines the detailed permission grant state change information.
| -------------- | ------------------------- | ---- | ---- | ------------------ |
| change | [PermissionStateChangeType](#permissionstatechangetype9) | Yes | No | Operation that triggers the permission grant state change. |
| tokenID | number | Yes | No | Token ID of the application whose permission grant state changes are subscribed.|
| permissionName | Permissions | Yes | No | permission whose grant state is changed. For details about the permissions, see the [Application Permission List](../../security/permission-list.md).|
| permissionName | Permissions | Yes | No | Permission whose authorization status changes. For details about the permissions, see the [Application Permission List](../../security/permission-list.md).|
en/application-dev/security/accesstoken-guidelines.md
浏览文件 @ b87b0a2e
......@@ -2,46 +2,70 @@
## When to Use
The [Ability Privilege Level (APL)](accesstoken-overview.md#app-apls) of an application can be **normal**, **system_basic**, or **system_core**. The default APL is **normal**. The [permission types](accesstoken-overview.md#permission-types) include **system_grant** and **user_grant**. For details about the permissions for apps, see the [App Permission List](permission-list.md).
In this example, the application requires the **ohos.permission.PERMISSION1** and **ohos.permission.PERMISSION2** permissions to implement core functions.
This document describes the following operations:
- The ability privilege level (APL) of the application is **normal**.
- The level of **ohos.permission.PERMISSION1** is **normal**, and the authorization mode is **system_grant**.
- The level of **ohos.permission.PERMISSION2** is **system_basic**, and the authorization mode is **user_grant**.
- [Declaring Permissions in the Configuration File](#declaring-permissions-in-the-configuration-file)
- [Declaring Permissions in the ACL](#declaring-permissions-in-the-acl)
- [Requesting User Authorization](#requesting-user-authorization)
- [Pre-Authorizing user_grant Permissions](#pre-authorizing-user_grant-permissions)
> **CAUTION**
>
> In this scenario, the required permissions include a **user_grant** permission. You can check whether the caller has the required permission through permission verification.
>
> If the application has not obtained that permission, a dialog box will be displayed to request user authorization.
## Declaring Permissions in the Configuration File
For details about the permissions for applications, see the [application permission list](permission-list.md).
During the development, you need to declare the permissions required by your application one by one in the project configuration file. The application cannot obtain the permissions that are not declared in the configuration file. OpenHarmony provides two application models: FA model and stage model. For more information, see [Application Models](../application-models/application-model-description.md). The application bundle and configuration file vary with the application model.
## Available APIs
> **NOTE**<br>The default APL of an application is **normal**. When an application needs the **system_basic** or **system_core** APL, you must declare the permission in the configuration file and the [Access Control List (ACL)](#declaring-permissions-in-the-acl).
The following lists only the APIs used in this guide. The APIs used vary with the applicatin models. For more information, see [Examples](##Examples).
The following table describes the fields in the configuration file.
### FA Model
| API | Description |
| ------------------------------------------------------------ | --------------------------------------------------- |
| requestPermissionsFromUser(permissions: Array&lt;string&gt;, requestCallback: AsyncCallback&lt;PermissionRequestResult&gt;) : void; | Requests permissions from the user.|
> For details, see [AbilityContext](../reference/apis/js-apis-ability-context.md).
| Field | Mandatory| Description |
| --------- | -------- | ------------------------------------------------------------ |
| name | Yes | Name of the permission. |
| reason | No | Reason for requesting the permission.<br>This field is mandatory when the requested permission needs user authorization (user_grant).|
| usedScene | No | Application scenario of the permission.<br>This field is mandatory when the requested permission needs user authorization (user_grant).|
| abilities | No | Abilities that require the permission. The value is an array.<br>**Applicable model**: stage|
| ability | No | Abilities that require the permission. The value is an array.<br>**Applicable model**: FA|
| when | No | Time when the permission is used. <br>Value:<br>- **inuse**: The permission applies only to a foreground application.<br>- **always**: The permission applies to both the foreground and background applications.|
### Stage Model
If the application is based on the stage model, declare the permissions in [**module.json5**](../quick-start/module-configuration-file.md).
| API | Description |
| ------------------------------------------------------------ | --------------------------------------------------- |
| requestPermissionsFromUser(context: Context, permissions: Array&lt;Permissions&gt;, requestCallback: AsyncCallback&lt;PermissionRequestResult&gt;) : void; | Requests permissions from the user.|
> For details, see [Ability Access Control](../reference/apis/js-apis-abilityAccessCtrl.md).
## Declaring Permissions
Declare the permissions required by the application one by one in the project configuration file. The application cannot obtain the permissions that are not declared in the configuration file. OpenHarmony provides two application models: FA model and stage model. For more information, see [Application Models](../application-models/application-model-description.md).
The application bundle structure and configuration file vary with the application models.
The following table describes the fields in the configuration files.
| Field | Description |
| --------- | ------------------------------------------------------------ |
| name | Name of the permission. |
| reason | Reason for requesting the permission. This field is mandatory for a user_grant permission.|
| usedScene | Scenario of the permission. This field is mandatory for a user_grant permission.|
| ability | Abilities that require the permission. The value is an array.<br>**Applicable model**: FA |
| abilities | Abilities that require the permission. The value is an array.<br>**Applicable model**: stage |
| when | Time when the permission is used. The value can be **inuse** (the permission can be used only in the foreground) or **always** (the permission can be used in foreground and background).|
### FA Model
For the applications based on the FA model, declare the required permissions in the **config.json** file.
**Example**
```json
{
"module" : {
// ...
"requestPermissions":[
"reqPermissions":[
{
"name" : "ohos.permission.PERMISSION1",
"reason": "$string:reason",
"usedScene": {
"abilities": [
"ability": [
"FormAbility"
],
"when":"inuse"
......@@ -51,7 +75,7 @@ If the application is based on the stage model, declare the permissions in [**mo
"name" : "ohos.permission.PERMISSION2",
"reason": "$string:reason",
"usedScene": {
"abilities": [
"ability": [
"FormAbility"
],
"when":"always"
......@@ -62,20 +86,21 @@ If the application is based on the stage model, declare the permissions in [**mo
}
```
### FA Model
### Stage Model
If the application is based on the FA model, declare the required permissions in **config.json**.
For the applications based on the stage model, declare the required permissions in the **module.json5** file.
**Example**
```json
{
"module" : {
// ...
"reqPermissions":[
"requestPermissions":[
{
"name" : "ohos.permission.PERMISSION1",
"reason": "$string:reason",
"usedScene": {
"ability": [
"abilities": [
"FormAbility"
],
"when":"inuse"
......@@ -85,7 +110,7 @@ If the application is based on the FA model, declare the required permissions in
"name" : "ohos.permission.PERMISSION2",
"reason": "$string:reason",
"usedScene": {
"ability": [
"abilities": [
"FormAbility"
],
"when":"always"
......@@ -98,149 +123,107 @@ If the application is based on the FA model, declare the required permissions in
## Declaring Permissions in the ACL
If an application of the **normal** level requires permissions corresponding to the **system_basic** or **system_core** level, you need to declare the required permissions in the ACL.
The permission level of **ohos.permission.PERMISSION2** is **system_basic**, which is higher than the app's APL. In this case, use the ACL.
In addition to declaring all the permissions in the configuration file, you must declare the permissions whose levels are higher that the app's APL in the app's profile. For details about the fields in the profile, see [HarmonyAppProvision Configuration File](app-provision-structure.md).
For example, if an application needs to access audio files of a user and capture screenshots, it requires the **ohos.permission.WRITE_AUDIO** permission (of the **system_basic** level) and the **ohos.permission.CAPTURE_SCREEN** permission (of the **system_core** level). In this case, you need to add the related permissions to the **acl** field in the [HarmonyAppProvision configuration file](app-provision-structure.md).
For example, declare the required permission in the **acls** field:
```json
{
// ...
"acls":{
"allowed-acls":[
"ohos.permission.WRITE_AUDIO",
"ohos.permission.CAPTURE_SCREEN"
]
}
"acls": {
"allowed-acls": [
"ohos.permission.PERMISSION2"
]
}
}
```
## Requesting User Authorization
## Applying for the user_grant Permission
If an application needs to access user privacy information or use system abilities, for example, accessing location or calendar information or using the camera to take photos or record videos, it must request the permission from users. A permission verification is performed first to determine whether the current invoker has the corresponding permission. If the application has not obtained that permission, a dialog box will be displayed to request user authorization. The following figure shows an example.
<img src="figures/permission-read_calendar.png" width="40%;" />
After the permissions are declared, the system grants the system_grant permission during the installation of the app. The user_grant permission must be authorized by the user.
> **NOTE**<br>Each time before an API protected by a permission is accessed, the [**requestPermissionsFromUser()**](../reference/apis/js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9) API will be called to request user authorization. After a permission is dynamically granted, the user may revoke the permission. Therefore, the previously granted authorization status cannot be persistent.
Therefore, before allowing the application to call the API protected by the **ohos.permission.PERMISSION2** permission, the system needs to verify whether the application has the permission to do so.
### Stage Model
If the verification result indicates that the application has the permission, the application can access the target API. Otherwise, the application needs to request user authorization and then proceeds based on the authorization result. For details, see [Access Control Overview](accesstoken-overview.md).
Example: Request the permission to read calendar information for an app.
1. Apply for the **ohos.permission.READ_CALENDAR** permission. For details, see [Declaring Permissions in the Configuration File](#declaring-permissions-in-the-configuration-file).
2. Call [**requestPermissionsFromUser()**](../reference/apis/js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9) in the **onWindowStageCreate()** callback of the UIAbility to dynamically apply for the permission, or request user authorization on the UI based on service requirements. The return value of [requestPermissionsFromUser()](../reference/apis/js-apis-abilityAccessCtrl.md#requestpermissionsfromuser9) indicates whether the app has the target permission. If yes, the target API can be called normally.
Request user authorization in UIAbility.
```typescript
import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
import { Permissions } from '@ohos.abilityAccessCtrl';
export default class EntryAbility extends UIAbility {
// ...
onWindowStageCreate(windowStage: window.WindowStage) {
// Main window is created, set main page for this ability
let context = this.context;
let AtManager = abilityAccessCtrl.createAtManager();
// The return value of requestPermissionsFromUser determines whether to display a dialog box to request user authorization.
const permissions: Array<Permissions> = ['ohos.permission.READ_CALENDAR'];
AtManager.requestPermissionsFromUser(context, permissions).then((data) => {
console.info(`[requestPermissions] data: ${JSON.stringify(data)}`);
let grantStatus: Array<number> = data.authResults;
if (grantStatus[0] === -1) {
// The authorization fails.
} else {
// The authorization is successful.
}
}).catch((err) => {
console.error(`[requestPermissions] Failed to start request permissions. Error: ${JSON.stringify(err)}`);
})
// ...
}
}
```
Request user authorization on the UI.
```typescript
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
import { Permissions } from '@ohos.abilityAccessCtrl';
import common from '@ohos.app.ability.common';
@Entry
@Component
struct Index {
reqPermissions() {
let context = getContext(this) as common.UIAbilityContext;
let AtManager = abilityAccessCtrl.createAtManager();
// The return value of requestPermissionsFromUser determines whether to display a dialog box to request user authorization.
const permissions: Array<Permissions> = ['ohos.permission.READ_CALENDAR'];
AtManager.requestPermissionsFromUser(context, permissions).then((data) => {
console.info(`[requestPermissions] data: ${JSON.stringify(data)}`);
let grantStatus: Array<number> = data.authResults;
if (grantStatus[0] === -1) {
// The authorization fails.
} else {
// The authorization is successful.
}
}).catch((err) => {
console.error(`[requestPermissions] Failed to start request permissions. Error: ${JSON.stringify(err)}`);
})
}
// Page display.
build() {
// ...
}
}
```
> **CAUATION**
>
> The permission authorized by a user is not permanent, because the user may revoke the authorization at any time. Each time before the API protected by the permission is called, call **requestPermissionsFromUser()** to request the permission.
### FA Model
## Examples
The procedure for requesting user authorization is as follows:
Call [requestPermissionsFromUser()](../reference/apis/js-apis-inner-app-context.md#contextrequestpermissionsfromuser7) to request user authorization.
1. Obtain the ability context.
2. Call **requestPermissionsFromUser()** to request user authorization. The API determines whether to display a dialog box to request user authorization based on whether the application has the permission.
3. Check whether the application has the permission based on the return value. If the application has the permission, the API can be invoked.
### FA Model
```js
// onWindowStageCreate() of Ability
onWindowStageCreate() {
let context = this.context;
// OnWindowStageCreate of the ability
onWindowStageCreate() {
var context = this.context
let array:Array<string> = ["ohos.permission.PERMISSION2"];
// The return value of requestPermissionsFromUser determines whether to display a dialog box to request user authorization.
context.requestPermissionsFromUser(array).then(function(data) {
console.log("data:" + JSON.stringify(data));
console.log("data permissions:" + JSON.stringify(data.permissions));
console.log("data result:" + JSON.stringify(data.authResults));
console.log("data type:" + typeof(data));
console.log("data:" + data);
console.log("data permissions:" + data.permissions);
console.log("data result:" + data.authResults);
}, (err) => {
console.error('Failed to start ability', err.code);
console.error('Failed to start ability', err.code);
});
}
}
```
## Pre-Authorizing user_grant Permissions
By default, the **user_grant** permissions must be dynamically authorized by the user through a dialog box. However, for pre-installed apps, you can pre-authroize the permissions, for example, the **ohos.permission.MICROPHONE** permission, in the [**install_list_permission.json**](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/preinstall-config/install_list_permissions.json) file to prevent the user authorization dialog box from being displayed. The **install_list_permissions.json** file is in the **/system/etc/app/** directory on a device. When the device is started, the **install_list_permissions.json** file is loaded. When the application is installed, the **user_grant** permissions in the file are granted. The **install_list_permissions.json** file contains the following fields:
> **NOTE**
> For details about how to use the APIs for the FA model, see [AbilityContext] (../reference/apis/js-apis-ability-context.md).
- **bundleName**: bundle name of the application.
- `app_signature`: fingerprint information of the application. For details, see **Configuration in install_list_capability.json** in [Application Privilege Configuration Guide](../../device-dev/subsystems/subsys-app-privilege-config-guide.md).
- **permissions**: **name** specifies the name of the **user_grant** permission to pre-authorize. **userCancellable** specifies whether the user can revoke the pre-authorization. The value **true** means the user can revoke the pre-authorization; the vaue **false** means the opposite.
### Stage Model
```js
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
> **NOTE**<br>This file is available only for preinstalled applications.
// OnWindowStageCreate of the ability
onWindowStageCreate() {
var context = this.context
var AtManager = abilityAccessCtrl.createAtManager();
// The return value of requestPermissionsFromUser determines whether to display a dialog box to request user authorization.
AtManager.requestPermissionsFromUser(context, ["ohos.permission.CAMERA"]).then((data) => {
console.log("data type:" + typeof(data));
console.log("data:" + data);
console.log("data permissions:" + data.permissions);
console.log("data result:" + data.authResults);
}).catch((err) => {
console.error('Failed to start ability', err.code);
})
}
```
> **NOTE**
> For details about how to use the APIs for the stage model, see [Application Access Control](../reference/apis/js-apis-abilityAccessCtrl.md).
## Pre-Authorizing user_grant Permissions
By default, the **user_grant** permissions must be granted by the user through a dialog box. However, for pre-installed applications, such as screenshot applications, you can pre-authorize the permissions to prevent the user authorization dialog box from being displayed. The [**install_list_permissions.json** file](https://gitee.com/openharmony/vendor_hihope/blob/master/rk3568/preinstall-config/install_list_permissions.json) is in the **/system/etc/app/** directory on a device. When the device is started, the **install_list_permissions.json** file is loaded. When the application is installed, the **user_grant** permissions in the file are granted. The **install_list_permissions.json** file is available only for preinstalled applications.
The **install_list_permissions.json** file contains the **bundleName**, **app_signature**, and **permissions** fields.
1. The permissions here are user_grant permissions only. For details about the permissions, see the [Application Permission List](permission-list.md).
2. **userCancellable** specifies whether the user can revoke the authorization. The value **true** means the user can revoke the authorization; the value **false** means the opposite.
```json
[
// ...
{
"bundleName": "com.example.myapplication", // Bundle Name.
"app_signature": ["****"], // Fingerprint information.
"bundleName": "com.ohos.myapplication", // Bundle name.
"app_signature":[], // Fingerprint information.
"permissions":[
{
"name": "ohos.permission.PERMISSION_X", // Permission to pre-authorize.
"userCancellable": false // The user cannot revoke the authorization.
"name":"xxxx", // Permission name, which cannot be left blank.
"userCancellable":false // The user cannot revoke the authorization. This field cannot be left blank.
},
{
"name": "ohos.permission.PERMISSION_X", // Permission to pre-authorize.
"userCancellable": true // The user can revoke the authorization.
"name":"yyy", // Permission name, which cannot be left blank.
"userCancellable":true // The user can revoke the authorization. This field cannot be left blank.
}
]
}
]
```
```
\ No newline at end of file
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或