js-apis-abilityAccessCtrl.md 33.8 KB
Newer Older
Z
zengyawen 已提交
1
# @ohos.abilityAccessCtrl (程序访问控制管理)
2 3

程序访问控制提供程序的权限管理能力,包括鉴权、授权和取消授权等。
Z
zengyawen 已提交
4

Z
zengyawen 已提交
5
> **说明:**
Z
zengyawen 已提交
6 7 8 9
> 本模块首批接口从API version 8开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

## 导入模块

Z
zengyawen 已提交
10
```js
Z
zengyawen 已提交
11 12 13 14 15 16 17 18 19
import abilityAccessCtrl from '@ohos.abilityAccessCtrl'
```

## abilityAccessCtrl.createAtManager

createAtManager(): AtManager

访问控制管理:获取访问控制模块对象。

20 21 22
**系统能力:** SystemCapability.Security.AccessToken


Z
zengyawen 已提交
23 24 25 26 27 28 29 30
**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| [AtManager](#atmanager) | 获取访问控制模块的实例。 |

**示例:**

Z
zengyawen 已提交
31
```js
C
chennian 已提交
32
let atManager = abilityAccessCtrl.createAtManager();
Z
zengyawen 已提交
33 34 35 36 37 38
```

## AtManager

管理访问控制模块的实例。

C
chennian 已提交
39
### checkAccessToken<sup>9+</sup>
Z
zengyawen 已提交
40

L
lsq 已提交
41
checkAccessToken(tokenID: number, permissionName: Permissions): Promise&lt;GrantStatus&gt;
Z
zengyawen 已提交
42

C
chennian 已提交
43
校验应用是否授予权限。使用Promise异步回调。
Z
zengyawen 已提交
44

45 46
**系统能力:** SystemCapability.Security.AccessToken

Z
zengyawen 已提交
47 48 49 50
**参数:**

| 参数名   | 类型                 | 必填 | 说明                                       |
| -------- | -------------------  | ---- | ------------------------------------------ |
F
fanchenxuan 已提交
51
| tokenID   |  number   | 是   | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。             |
L
lsq 已提交
52
| permissionName | Permissions | 是   | 需要校验的权限名称,合法的权限名取值可在[系统权限定义列表](../../security/permission-list.md)中查询。 |
Z
zengyawen 已提交
53 54 55 56 57

**返回值:**

| 类型          | 说明                                |
| :------------ | :---------------------------------- |
C
chennian 已提交
58
| Promise&lt;GrantStatus&gt; | Promise对象。返回授权状态结果。 |
Z
zengyawen 已提交
59

C
chennian 已提交
60 61 62
**错误码:**

以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)
F
fanchenxuan 已提交
63

C
chennian 已提交
64 65
| 错误码ID | 错误信息 |
| -------- | -------- |
Y
yu 已提交
66
| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. |
C
chennian 已提交
67

Z
zengyawen 已提交
68 69
**示例:**

Z
zengyawen 已提交
70
```js
C
chennian 已提交
71
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
C
chennian 已提交
72

C
chennian 已提交
73
let atManager = abilityAccessCtrl.createAtManager();
F
fanchenxuan 已提交
74
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
C
chennian 已提交
75
try {
C
chennian 已提交
76
    atManager.checkAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data) => {
C
chennian 已提交
77 78 79 80 81 82 83
        console.log(`checkAccessToken success, data->${JSON.stringify(data)}`);
    }).catch((err) => {
        console.log(`checkAccessToken fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
Z
zengyawen 已提交
84 85
```

Z
zhouyan 已提交
86 87
### verifyAccessTokenSync<sup>9+</sup>

L
lsq 已提交
88
verifyAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus
Z
zhouyan 已提交
89 90 91 92 93 94 95 96 97

校验应用是否被授予权限,同步返回结果。

**系统能力:** SystemCapability.Security.AccessToken

**参数:**

| 参数名   | 类型                 | 必填 | 说明                                       |
| -------- | -------------------  | ---- | ------------------------------------------ |
F
fanchenxuan 已提交
98
| tokenID   |  number   | 是   | 要校验应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。              |
L
lsq 已提交
99
| permissionName | Permissions | 是   | 需要校验的权限名称,合法的权限名取值可在[系统权限定义列表](../../security/permission-list.md)中查询。 |
Z
zhouyan 已提交
100 101 102 103 104 105 106

**返回值:**

| 类型          | 说明                                |
| :------------ | :---------------------------------- |
| [GrantStatus](#grantstatus) | 枚举实例,返回授权状态。 |

C
chennian 已提交
107 108 109
**错误码:**

以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)
F
fanchenxuan 已提交
110

C
chennian 已提交
111 112
| 错误码ID | 错误信息 |
| -------- | -------- |
Y
yu 已提交
113
| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. |
C
chennian 已提交
114

Z
zhouyan 已提交
115 116 117
**示例:**

```js
C
chennian 已提交
118
let atManager = abilityAccessCtrl.createAtManager();
F
fanchenxuan 已提交
119
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
C
chennian 已提交
120
let data = atManager.verifyAccessTokenSync(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS');
Z
zhouyan 已提交
121 122 123
console.log(`data->${JSON.stringify(data)}`);
```

Z
zengyawen 已提交
124 125
### grantUserGrantedPermission

L
lsq 已提交
126
grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise&lt;void&gt;
Z
zengyawen 已提交
127

C
chennian 已提交
128
授予应用user grant权限。使用Promise异步回调。
Z
zengyawen 已提交
129

C
chennian 已提交
130
**系统接口:** 此接口为系统接口。
131

C
chennian 已提交
132
**需要权限:** ohos.permission.GRANT_SENSITIVE_PERMISSIONS,仅系统应用可用。
133 134

**系统能力:** SystemCapability.Security.AccessToken
Z
zengyawen 已提交
135 136 137 138 139

**参数:**

| 参数名    | 类型                | 必填 | 说明                                                         |
| --------- | ------------------- | ---- | ------------------------------------------------------------ |
F
fanchenxuan 已提交
140
| tokenID      | number              | 是   | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。            |
L
lsq 已提交
141
| permissionName | Permissions              | 是   | 被授予的权限名称,合法的权限名取值可在[系统权限定义列表](../../security/permission-list.md)中查询。 |
Z
zhouyan 已提交
142
| permissionFlags  | number | 是   | 授权选项<br>- 0表示权限未经过用户主动设置。<br>- 1表示当次用户若选择禁止该权限,下次权限弹窗仍可以弹出申请用户授权。<br>- 2表示当次用户若选择禁止该权限,下次不会再弹出权限弹窗,需要用户在setting的权限管理中进行授权。<br>- 4表示当次权限设置为系统授权,用户不可更改这个权限授权状态。 |
Z
zengyawen 已提交
143 144 145 146 147

**返回值:**

| 类型          | 说明                                |
| :------------ | :---------------------------------- |
C
chennian 已提交
148
| Promise&lt;void&gt; | Promise对象。无返回结果的Promise对象。 |
Z
zengyawen 已提交
149

C
chennian 已提交
150 151 152
**错误码:**

以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)
F
fanchenxuan 已提交
153

C
chennian 已提交
154 155
| 错误码ID | 错误信息 |
| -------- | -------- |
Y
yu 已提交
156
| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid. |
F
fanchenxuan 已提交
157 158 159 160
| 12100002 | The specified tokenID does not exist. |
| 12100003 | The specified permission does not exist. |
| 12100006 | The application specified by the tokenID is not allowed to be granted with the specified permission. Either the application is a sandbox or the tokenID is from a remote device. |
| 12100007 | Service is abnormal. |
C
chennian 已提交
161

Z
zengyawen 已提交
162 163
**示例:**

Z
zengyawen 已提交
164
```js
C
chennian 已提交
165
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
C
chennian 已提交
166

C
chennian 已提交
167
let atManager = abilityAccessCtrl.createAtManager();
F
fanchenxuan 已提交
168
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
L
lsq 已提交
169
let permissionFlags = 1;
C
chennian 已提交
170
try {
C
chennian 已提交
171
    atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS', permissionFlags).then(() => {
C
chennian 已提交
172 173 174 175 176 177 178
        console.log('grantUserGrantedPermission success');
    }).catch((err) => {
        console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
Z
zengyawen 已提交
179 180 181 182
```

### grantUserGrantedPermission

L
lsq 已提交
183
grantUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback&lt;void&gt;): void
Z
zengyawen 已提交
184

C
chennian 已提交
185
授予应用user grant权限。使用callback异步回调。
Z
zengyawen 已提交
186

C
chennian 已提交
187
**系统接口:** 此接口为系统接口。
188

C
chennian 已提交
189
**需要权限:** ohos.permission.GRANT_SENSITIVE_PERMISSIONS,仅系统应用可用。
190 191

**系统能力:** SystemCapability.Security.AccessToken
Z
zengyawen 已提交
192 193 194 195 196

**参数:**

| 参数名    | 类型                | 必填 | 说明                          |
| --------- | ------------------- | ---- | ------------------------------------------------------------ |
F
fanchenxuan 已提交
197
| tokenID      | number              | 是   | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。|
L
lsq 已提交
198
| permissionName | Permissions              | 是   | 被授予的权限名称,合法的权限名取值可在[系统权限定义列表](../../security/permission-list.md)中查询。 |
Z
zhouyan 已提交
199
| permissionFlags  | number | 是   | 授权选项<br>- 0表示权限未经过用户主动设置。<br>- 1表示当次用户若选择禁止该权限,下次权限弹窗仍可以弹出申请用户授权。<br>- 2表示当次用户若选择禁止该权限,下次不会再弹出权限弹窗,需要用户在setting的权限管理中进行授权。<br>- 4表示当次权限设置为系统授权,用户不可更改这个权限授权状态。 |
C
chennian 已提交
200 201 202 203 204
| callback | AsyncCallback&lt;void&gt; | 是 | 授予应用user grant权限。当授予权限成功时,err为undefine;否则为错误对象。 |

**错误码:**

以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)
F
fanchenxuan 已提交
205

C
chennian 已提交
206 207
| 错误码ID | 错误信息 |
| -------- | -------- |
Y
yu 已提交
208
| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid. |
C
chennian 已提交
209 210
| 12100002 | The specified tokenID does not exist. |
| 12100003 | The specified permission does not exist. |
F
fanchenxuan 已提交
211 212
| 12100006 | The application specified by the tokenID is not allowed to be granted with the specified permission. Either the application is a sandbox or the tokenID is from a remote device. |
| 12100007 | Service is abnormal. |
Z
zengyawen 已提交
213 214 215

**示例:**

Z
zengyawen 已提交
216
```js
C
chennian 已提交
217
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
C
chennian 已提交
218

C
chennian 已提交
219
let atManager = abilityAccessCtrl.createAtManager();
F
fanchenxuan 已提交
220
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
L
lsq 已提交
221
let permissionFlags = 1;
C
chennian 已提交
222
try {
C
chennian 已提交
223
    atManager.grantUserGrantedPermission(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS', permissionFlags, (err, data) => {
C
chennian 已提交
224 225 226 227 228 229 230 231 232
        if (err) {
            console.log(`grantUserGrantedPermission fail, err->${JSON.stringify(err)}`);
        } else {
            console.log('grantUserGrantedPermission success');
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
Z
zengyawen 已提交
233 234 235 236
```

### revokeUserGrantedPermission

L
lsq 已提交
237
revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number): Promise&lt;void&gt;
Z
zengyawen 已提交
238

C
chennian 已提交
239
撤销应用user grant权限。使用Promise异步回调。
Z
zengyawen 已提交
240

C
chennian 已提交
241
**系统接口:** 此接口为系统接口。
242

C
chennian 已提交
243
**需要权限:** ohos.permission.REVOKE_SENSITIVE_PERMISSIONS,仅系统应用可用。
244 245

**系统能力:** SystemCapability.Security.AccessToken
Z
zengyawen 已提交
246 247 248 249 250

**参数:**

| 参数名    | 类型                | 必填 | 说明                                                         |
| --------- | ------------------- | ---- | ------------------------------------------------------------ |
F
fanchenxuan 已提交
251
| tokenID      | number              | 是   | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。           |
L
lsq 已提交
252
| permissionName | Permissions              | 是   | 被撤销的权限名称,合法的权限名取值可在[系统权限定义列表](../../security/permission-list.md)中查询。 |
Z
zhouyan 已提交
253
| permissionFlags  | number | 是   | 授权选项<br>- 0表示权限未经过用户主动设置。<br>- 1表示当次用户若选择禁止该权限,下次权限弹窗仍可以弹出申请用户授权。<br>- 2表示当次用户若选择禁止该权限,下次不会再弹出权限弹窗,需要用户在setting的权限管理中进行授权。<br>- 4表示当次权限设置为系统授权,用户不可更改这个权限授权状态。 |
Z
zengyawen 已提交
254 255 256 257 258

**返回值:**

| 类型          | 说明                                |
| :------------ | :---------------------------------- |
C
chennian 已提交
259
| Promise&lt;void&gt; | Promise对象。无返回结果的Promise对象。 |
Z
zengyawen 已提交
260

C
chennian 已提交
261 262 263
**错误码:**

以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)
F
fanchenxuan 已提交
264

C
chennian 已提交
265 266
| 错误码ID | 错误信息 |
| -------- | -------- |
Y
yu 已提交
267
| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid. |
F
fanchenxuan 已提交
268 269 270 271
| 12100002 | The specified tokenID does not exist. |
| 12100003 | The specified permission does not exist. |
| 12100006 | The application specified by the tokenID is not allowed to be revoked with the specified permission. Either the application is a sandbox or the tokenID is from a remote device. |
| 12100007 | Service is abnormal. |
C
chennian 已提交
272

Z
zengyawen 已提交
273 274
**示例:**

Z
zengyawen 已提交
275
```js
C
chennian 已提交
276
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
C
chennian 已提交
277

C
chennian 已提交
278
let atManager = abilityAccessCtrl.createAtManager();
F
fanchenxuan 已提交
279
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
L
lsq 已提交
280
let permissionFlags = 1;
C
chennian 已提交
281
try {
C
chennian 已提交
282
    atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS', permissionFlags).then(() => {
C
chennian 已提交
283 284 285 286 287 288 289
        console.log('revokeUserGrantedPermission success');
    }).catch((err) => {
        console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
Z
zengyawen 已提交
290 291 292 293
```

### revokeUserGrantedPermission

L
lsq 已提交
294
revokeUserGrantedPermission(tokenID: number, permissionName: Permissions, permissionFlags: number, callback: AsyncCallback&lt;void&gt;): void
Z
zengyawen 已提交
295

C
chennian 已提交
296
撤销应用user grant权限。使用callback异步回调。
Z
zengyawen 已提交
297

C
chennian 已提交
298
**系统接口:** 此接口为系统接口。
299

C
chennian 已提交
300
**需要权限:** ohos.permission.REVOKE_SENSITIVE_PERMISSIONS,仅系统应用可用。
301 302

**系统能力:** SystemCapability.Security.AccessToken
Z
zengyawen 已提交
303 304 305 306 307

**参数:**

| 参数名    | 类型                | 必填 | 说明                          |
| --------- | ------------------- | ---- | ------------------------------------------------------------ |
F
fanchenxuan 已提交
308
| tokenID      | number              | 是   | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。           |
L
lsq 已提交
309
| permissionName | Permissions              | 是   | 被撤销的权限名称,合法的权限名取值可在[系统权限定义列表](../../security/permission-list.md)中查询。 |
Z
zhouyan 已提交
310
| permissionFlags  | number | 是   | 授权选项<br>- 0表示权限未经过用户主动设置。<br>- 1表示当次用户若选择禁止该权限,下次权限弹窗仍可以弹出申请用户授权。<br>- 2表示当次用户若选择禁止该权限,下次不会再弹出权限弹窗,需要用户在setting的权限管理中进行授权。<br>- 4表示当次权限设置为系统授权,用户不可更改这个权限授权状态。 |
C
chennian 已提交
311 312 313 314 315
| callback | AsyncCallback&lt;void&gt; | 是 | 撤销应用user grant权限。当撤销权限成功时,err为undefine;否则为错误对象。 |

**错误码:**

以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)
F
fanchenxuan 已提交
316

C
chennian 已提交
317 318
| 错误码ID | 错误信息 |
| -------- | -------- |
Y
yu 已提交
319
| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256, or the flags value is invalid. |
C
chennian 已提交
320 321
| 12100002 | The specified tokenID does not exist. |
| 12100003 | The specified permission does not exist. |
F
fanchenxuan 已提交
322 323
| 12100006 | The application specified by the tokenID is not allowed to be revoked with the specified permission. Either the application is a sandbox or the tokenID is from a remote device. |
| 12100007 | Service is abnormal. |
Z
zengyawen 已提交
324 325 326

**示例:**

Z
zengyawen 已提交
327
```js
C
chennian 已提交
328
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
C
chennian 已提交
329

C
chennian 已提交
330
let atManager = abilityAccessCtrl.createAtManager();
F
fanchenxuan 已提交
331
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
L
lsq 已提交
332
let permissionFlags = 1;
C
chennian 已提交
333
try {
C
chennian 已提交
334
    atManager.revokeUserGrantedPermission(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS', permissionFlags, (err, data) => {
C
chennian 已提交
335 336 337 338 339 340 341 342 343
        if (err) {
            console.log(`revokeUserGrantedPermission fail, err->${JSON.stringify(err)}`);
        } else {
            console.log('revokeUserGrantedPermission success');
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
Z
zengyawen 已提交
344 345 346 347
```

### getPermissionFlags

L
lsq 已提交
348
getPermissionFlags(tokenID: number, permissionName: Permissions): Promise&lt;number&gt;
Z
zengyawen 已提交
349

C
chennian 已提交
350
获取指定应用的指定权限的flag。使用Promise异步回调。
Z
zengyawen 已提交
351

C
chennian 已提交
352
**系统接口:** 此接口为系统接口。
353

C
chennian 已提交
354
**需要权限:** ohos.permission.GET_SENSITIVE_PERMISSIONS or ohos.permission.GRANT_SENSITIVE_PERMISSIONS or ohos.permission.REVOKE_SENSITIVE_PERMISSIONS,仅系统应用可用。
355

356 357
**系统能力:** SystemCapability.Security.AccessToken

Z
zengyawen 已提交
358 359 360 361
**参数:**

| 参数名    | 类型                | 必填 | 说明                          |
| --------- | ------------------- | ---- | ------------------------------------------------------------ |
F
fanchenxuan 已提交
362
| tokenID      | number              | 是   | 目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。            |
L
lsq 已提交
363
| permissionName | Permissions              | 是   | 查询的权限名称,合法的权限名取值可在[系统权限定义列表](../../security/permission-list.md)中查询。 |
Z
zengyawen 已提交
364 365 366 367 368

**返回值:**

| 类型          | 说明                                |
| :------------ | :---------------------------------- |
C
chennian 已提交
369
| Promise&lt;number&gt; | Promise对象。返回查询结果。 |
Z
zengyawen 已提交
370

C
chennian 已提交
371 372 373
**错误码:**

以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)
F
fanchenxuan 已提交
374

C
chennian 已提交
375 376
| 错误码ID | 错误信息 |
| -------- | -------- |
Y
yu 已提交
377
| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. |
F
fanchenxuan 已提交
378 379
| 12100002 | The specified tokenID does not exist. |
| 12100003 | The specified permission does not exist. |
F
fanchenxuan 已提交
380
| 12100006 | The operation is not allowed. Either the application is a sandbox or the tokenID is from a remote device. |
F
fanchenxuan 已提交
381
| 12100007 | Service is abnormal. |
C
chennian 已提交
382

Z
zengyawen 已提交
383 384
**示例:**

Z
zengyawen 已提交
385
```js
C
chennian 已提交
386
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
C
chennian 已提交
387

C
chennian 已提交
388
let atManager = abilityAccessCtrl.createAtManager();
F
fanchenxuan 已提交
389
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
C
chennian 已提交
390
try {
C
chennian 已提交
391
    atManager.getPermissionFlags(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS').then((data) => {
C
chennian 已提交
392
        console.log(`getPermissionFlags success, data->${JSON.stringify(data)}`);
F
fanchenxuan 已提交
393
    }).catch((err) => {
C
chennian 已提交
394 395 396 397 398
        console.log(`getPermissionFlags fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
L
l00520400 已提交
399 400
```

Z
zhouyan 已提交
401
### getVersion<sup>9+</sup>
Z
zhouyan 已提交
402 403 404

getVersion(): Promise&lt;number&gt;

C
chennian 已提交
405
获取当前权限管理的数据版本。使用Promise异步回调。
Z
zhouyan 已提交
406

C
chennian 已提交
407
**系统接口:** 此接口为系统接口。
Z
zhouyan 已提交
408 409 410 411 412 413 414

**系统能力:** SystemCapability.Security.AccessToken

**返回值:**

| 类型          | 说明                                |
| :------------ | :---------------------------------- |
C
chennian 已提交
415
| Promise&lt;number&gt; | Promise对象。返回查询到的版本号。 |
Z
zhouyan 已提交
416 417 418 419

**示例:**

```js
C
chennian 已提交
420 421
let atManager = abilityAccessCtrl.createAtManager();
let promise = atManager.getVersion();
Z
zhouyan 已提交
422 423 424 425 426
promise.then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});
```

427 428
### on<sup>9+</sup>

L
lsq 已提交
429
on(type: 'permissionStateChange', tokenIDList: Array&lt;number&gt;, permissionList: Array&lt;Permissions&gt;, callback: Callback&lt;PermissionStateChangeInfo&gt;): void;
430

C
chennian 已提交
431
订阅指定tokenId列表与权限列表的权限状态变更事件。
432

C
chennian 已提交
433
**系统接口:** 此接口为系统接口。
434

C
chennian 已提交
435
**需要权限:** ohos.permission.GET_SENSITIVE_PERMISSIONS,仅系统应用可用。
436 437 438 439 440 441 442 443

**系统能力:** SystemCapability.Security.AccessToken

**参数:**

| 参数名             | 类型                   | 必填 | 说明                                                          |
| ------------------ | --------------------- | ---- | ------------------------------------------------------------ |
| type               | string                | 是   | 订阅事件类型,固定为'permissionStateChange',权限状态变更事件。  |
F
fanchenxuan 已提交
444
| tokenIDList        | Array&lt;number&gt;   | 是   | 订阅的tokenId列表,为空时表示订阅所有的应用的权限状态变化。        |
L
lsq 已提交
445
| permissionList | Array&lt;Permissions&gt;   | 是   | 订阅的权限名列表,为空时表示订阅所有的权限状态变化。               |
446 447
| callback | Callback&lt;[PermissionStateChangeInfo](#permissionstatechangeinfo9)&gt; | 是 | 订阅指定tokenId与指定权限名状态变更事件的回调。|

C
chennian 已提交
448 449 450
**错误码:**

以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)
F
fanchenxuan 已提交
451

C
chennian 已提交
452 453
| 错误码ID | 错误信息 |
| -------- | -------- |
Y
yu 已提交
454
| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. |
F
fanchenxuan 已提交
455 456 457 458
| 12100004 | The interface is called repeatedly with the same input. |
| 12100005 | The registration time has exceeded the limitation. |
| 12100007 | Service is abnormal. |
| 12100008 | Out of memory. |
C
chennian 已提交
459

460 461 462
**示例:**

```js
Z
zhouyan 已提交
463
import {Permissions} from '@ohos.abilityAccessCtrl';
464
import bundleManager from '@ohos.bundle.bundleManager';
465 466

let atManager = abilityAccessCtrl.createAtManager();
467
let appInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100);
L
lsq 已提交
468
let tokenIDList: Array<number> = [appInfo.accessTokenId];
C
chennian 已提交
469
let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC'];
C
chennian 已提交
470
try {
L
lsq 已提交
471
    atManager.on('permissionStateChange', tokenIDList, permissionList, (data) => {
C
chennian 已提交
472
        console.debug('receive permission state change, data:' + JSON.stringify(data));
C
chennian 已提交
473 474 475
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
476 477 478 479 480
}
```

### off<sup>9+</sup>

L
lsq 已提交
481
off(type: 'permissionStateChange', tokenIDList: Array&lt;number&gt;, permissionList: Array&lt;Permissions&gt;, callback?: Callback&lt;PermissionStateChangeInfo&gt;): void;
482 483 484

取消订阅指定tokenId列表与权限列表的权限状态变更事件,使用callback回调异步返回结果。

C
chennian 已提交
485
**系统接口:** 此接口为系统接口。
486

C
chennian 已提交
487
**需要权限:** ohos.permission.GET_SENSITIVE_PERMISSIONS,仅系统应用可用。
488 489 490 491 492 493 494 495

**系统能力:** SystemCapability.Security.AccessToken

**参数:**

| 参数名             | 类型                   | 必填 | 说明                                                          |
| ------------------ | --------------------- | ---- | ------------------------------------------------------------ |
| type               | string                | 是   | 订阅事件类型,固定为'permissionStateChange',权限状态变更事件。  |
F
fanchenxuan 已提交
496
| tokenIDList        | Array&lt;number&gt;   | 是   | 订阅的tokenId列表,为空时表示订阅所有的应用的权限状态变化,必须与on的输入一致。 |
L
lsq 已提交
497
| permissionList | Array&lt;Permissions&gt;   | 是   | 订阅的权限名列表,为空时表示订阅所有的权限状态变化,必须与on的输入一致。 |
498 499
| callback | Callback&lt;[PermissionStateChangeInfo](#permissionstatechangeinfo9)&gt; | 否 | 取消订阅指定tokenId与指定权限名状态变更事件的回调。|

C
chennian 已提交
500 501 502
**错误码:**

以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)
F
fanchenxuan 已提交
503

C
chennian 已提交
504 505
| 错误码ID | 错误信息 |
| -------- | -------- |
C
chennian 已提交
506
| 12100001 | The parameter is invalid. The tokenIDs or permissionNames in the list are all invalid. |
C
chennian 已提交
507
| 12100004 | The interface is not used together with 'on'. |
F
fanchenxuan 已提交
508 509
| 12100007 | Service is abnormal. |
| 12100008 | Out of memory. |
C
chennian 已提交
510

511 512 513
**示例:**

```js
Z
zhouyan 已提交
514
import {Permissions} from '@ohos.abilityAccessCtrl';
515
import bundleManager from '@ohos.bundle.bundleManager';
516 517

let atManager = abilityAccessCtrl.createAtManager();
518
let appInfo = bundleManager.getApplicationInfoSync('com.example.myapplication', 0, 100);
L
lsq 已提交
519
let tokenIDList: Array<number> = [appInfo.accessTokenId];
C
chennian 已提交
520
let permissionList: Array<Permissions> = ['ohos.permission.DISTRIBUTED_DATASYNC'];
C
chennian 已提交
521
try {
L
lsq 已提交
522
    atManager.off('permissionStateChange', tokenIDList, permissionList);
C
chennian 已提交
523 524
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
525 526 527
}
```

L
lsq 已提交
528 529 530 531 532 533
### verifyAccessToken<sup>9+</sup>

verifyAccessToken(tokenID: number, permissionName: Permissions): Promise&lt;GrantStatus&gt;

校验应用是否授予权限。使用Promise异步回调。

Z
zengyawen 已提交
534 535 536
> **说明:**
>
> 建议使用[checkAccessToken](#checkaccesstoken9)替代。
L
lsq 已提交
537 538 539 540 541 542 543

**系统能力:** SystemCapability.Security.AccessToken

**参数:**

| 参数名   | 类型                 | 必填 | 说明                                       |
| -------- | -------------------  | ---- | ------------------------------------------ |
F
fanchenxuan 已提交
544
| tokenID   |  number   | 是   | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。             |
L
lsq 已提交
545
| permissionName | Permissions | 是   | 需要校验的权限名称,合法的权限名取值可在[系统权限定义列表](../../security/permission-list.md)中查询。 |
L
lsq 已提交
546 547 548 549 550 551 552 553 554 555 556 557

**返回值:**

| 类型          | 说明                                |
| :------------ | :---------------------------------- |
| Promise&lt;GrantStatus&gt; | Promise对象。返回授权状态结果。 |

**示例:**

```js
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';

C
chennian 已提交
558
let atManager = abilityAccessCtrl.createAtManager();
F
fanchenxuan 已提交
559
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
C
chennian 已提交
560
let promise = atManager.verifyAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS');
L
lsq 已提交
561 562 563 564 565
promise.then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});
```

566 567
### requestPermissionsFromUser<sup>9+</sup>

L
lsq 已提交
568
requestPermissionsFromUser(context: Context, permissionList: Array&lt;Permissions&gt;, requestCallback: AsyncCallback&lt;PermissionRequestResult&gt;) : void;
569

L
lsq 已提交
570 571 572 573
用于UIAbility拉起弹框请求用户授权。使用callback异步回调。
> **说明:**
>
> 非UIAbility不支持调用本函数。
574 575 576 577 578 579 580 581 582

**模型约束**:此接口仅可在Stage模型下使用。

**系统能力**: SystemCapability.Security.AccessToken

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
L
lsq 已提交
583
| context | Context | 是 | 请求权限的UIAbility的UIAbilityContext。 |
L
lsq 已提交
584
| permissionList | Array&lt;Permissions&gt; | 是 | 权限名列表,合法的权限名取值可在[系统权限定义列表](../../security/permission-list.md)中查询。 |
585 586 587 588 589
| callback | AsyncCallback&lt;[PermissionRequestResult](js-apis-permissionrequestresult.md)&gt; | 是 | 回调函数,返回接口调用是否成功的结果。 |

**错误码:**

以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)
Y
yu 已提交
590

591 592
| 错误码ID | 错误信息 |
| -------- | -------- |
Z
zhouyan 已提交
593
| 12100001 | The parameter is invalid. The context is invalid when it does not belong to the application itself. |
594 595 596 597 598 599 600

**示例:**

  ```js
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
let atManager = abilityAccessCtrl.createAtManager();
try {
C
chennian 已提交
601 602 603 604
    atManager.requestPermissionsFromUser(this.context, ['ohos.permission.CAMERA'], (err, data)=>{
        console.info('data:' + JSON.stringify(data));
        console.info('data permissions:' + data.permissions);
        console.info('data authResults:' + data.authResults);
605 606 607 608 609 610 611 612
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
  ```

### requestPermissionsFromUser<sup>9+</sup>

L
lsq 已提交
613
requestPermissionsFromUser(context: Context, permissionList: Array&lt;Permissions&gt;) : Promise&lt;PermissionRequestResult&gt;;
614

L
lsq 已提交
615 616 617 618 619
用于UIAbility拉起弹框请求用户授权。使用promise异步回调。

> **说明:**
>
> 非UIAbility不支持调用本函数。
620 621 622 623 624 625 626 627 628

**模型约束**:此接口仅可在Stage模型下使用。

**系统能力**: SystemCapability.Security.AccessToken

**参数:**

| 参数名 | 类型 | 必填 | 说明 |
| -------- | -------- | -------- | -------- |
L
lsq 已提交
629
| context | Context | 是 | 请求权限的UIAbility的UIAbilityContext。 |
L
lsq 已提交
630
| permissionList | Array&lt;Permissions&gt; | 是 | 需要校验的权限名称,合法的权限名取值可在[系统权限定义列表](../../security/permission-list.md)中查询。 |
631 632 633 634 635 636 637 638 639 640

**返回值:**

| 类型 | 说明 |
| -------- | -------- |
| Promise&lt;[PermissionRequestResult](js-apis-permissionrequestresult.md)&gt; | 返回一个Promise,包含接口的结果。 |

**错误码:**

以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)
Y
yu 已提交
641

642 643
| 错误码ID | 错误信息 |
| -------- | -------- |
Z
zhouyan 已提交
644
| 12100001 | The parameter is invalid. The context is invalid when it does not belong to the application itself. |
645 646 647 648 649 650 651

**示例:**

  ```js
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
let atManager = abilityAccessCtrl.createAtManager();
try {
C
chennian 已提交
652 653 654 655
    atManager.requestPermissionsFromUser(this.context, ['ohos.permission.CAMERA']).then((data) => {
        console.info('data:' + JSON.stringify(data));
        console.info('data permissions:' + data.permissions);
        console.info('data authResults:' + data.authResults);
656
    }).catch((err) => {
C
chennian 已提交
657
        console.info('data:' + JSON.stringify(err));
658 659 660 661 662 663
    })
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
  ```

C
chennian 已提交
664 665 666 667
### verifyAccessToken<sup>(deprecated)</sup>

verifyAccessToken(tokenID: number, permissionName: string): Promise&lt;GrantStatus&gt;

C
chennian 已提交
668
校验应用是否授予权限。使用Promise异步回调。
C
chennian 已提交
669

Z
zengyawen 已提交
670 671 672
> **说明:**
>
> 从API version 9开始不再维护,建议使用[checkAccessToken](#checkaccesstoken9)替代。
C
chennian 已提交
673 674 675 676 677 678 679

**系统能力:** SystemCapability.Security.AccessToken

**参数:**

| 参数名   | 类型                 | 必填 | 说明                                       |
| -------- | -------------------  | ---- | ------------------------------------------ |
F
fanchenxuan 已提交
680
| tokenID   |  number   | 是   | 要校验的目标应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。             |
C
chennian 已提交
681 682 683 684 685 686 687 688 689 690 691
| permissionName | string | 是   | 需要校验的权限名称。 |

**返回值:**

| 类型          | 说明                                |
| :------------ | :---------------------------------- |
| Promise&lt;GrantStatus&gt; | Promise对象。返回授权状态结果。 |

**示例:**

```js
C
chennian 已提交
692
import abilityAccessCtrl from '@ohos.abilityAccessCtrl';
C
chennian 已提交
693

C
chennian 已提交
694
let atManager = abilityAccessCtrl.createAtManager();
F
fanchenxuan 已提交
695
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
C
chennian 已提交
696
let promise = atManager.verifyAccessToken(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS');
C
chennian 已提交
697 698 699 700 701
promise.then(data => {
    console.log(`promise: data->${JSON.stringify(data)}`);
});
```

C
chennian 已提交
702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735
### checkAccessTokenSync<sup>10+</sup>

checkAccessTokenSync(tokenID: number, permissionName: Permissions): GrantStatus;

校验应用是否被授予权限,同步返回结果。

**系统能力:** SystemCapability.Security.AccessToken

**参数:**

| 参数名   | 类型                 | 必填 | 说明                                       |
| -------- | -------------------  | ---- | ------------------------------------------ |
| tokenID   |  number   | 是   | 要校验应用的身份标识。可通过应用的[ApplicationInfo](js-apis-bundleManager-applicationInfo.md)获得。              |
| permissionName | Permissions | 是   | 需要校验的权限名称,合法的权限名取值可在[系统权限定义列表](../../security/permission-list.md)中查询。 |

**返回值:**

| 类型          | 说明                                |
| :------------ | :---------------------------------- |
| [GrantStatus](#grantstatus) | 枚举实例,返回授权状态。 |

**错误码:**

以下错误码的详细介绍请参见[程序访问控制错误码](../errorcodes/errorcode-access-token.md)

| 错误码ID | 错误信息 |
| -------- | -------- |
| 12100001 | The parameter is invalid. The tokenID is 0, or the string size of permissionName is larger than 256. |

**示例:**

```js
let atManager = abilityAccessCtrl.createAtManager();
let tokenID = 0; // 系统应用可以通过bundleManager.getApplicationInfo获取,普通应用可以通过bundleManager.getBundleInfoForSelf获取
C
chennian 已提交
736
let data = atManager.checkAccessTokenSync(tokenID, 'ohos.permission.GRANT_SENSITIVE_PERMISSIONS');
C
chennian 已提交
737 738 739
console.log(`data->${JSON.stringify(data)}`);
```

L
l00520400 已提交
740 741 742 743
### GrantStatus

表示授权状态的枚举。

744 745
**系统能力:** SystemCapability.Security.AccessToken

F
fanchenxuan 已提交
746
| 名称               |    值 | 说明        |
747 748 749 750 751 752
| ------------------ | ----- | ----------- |
| PERMISSION_DENIED  | -1    | 表示未授权。 |
| PERMISSION_GRANTED | 0     | 表示已授权。 |

### PermissionStateChangeType<sup>9+</sup>

L
lsq 已提交
753
表示权限授权状态变化操作类型的枚举。
754

F
fanchenxuan 已提交
755 756
**系统接口:** 此接口为系统接口。

757 758
**系统能力:** SystemCapability.Security.AccessToken

F
fanchenxuan 已提交
759
| 名称                     |    值 | 说明              |
760 761
| ----------------------- | ------ | ----------------- |
| PERMISSION_REVOKED_OPER | 0      | 表示权限取消操作。 |
Z
zhouyan 已提交
762
| PERMISSION_GRANTED_OPER | 1      | 表示权限授予操作。 |
763 764 765

### PermissionStateChangeInfo<sup>9+</sup>

L
lsq 已提交
766 767
表示某次权限授权状态变化的详情。

F
fanchenxuan 已提交
768 769
**系统接口:** 此接口为系统接口。

C
chennian 已提交
770
**系统能力:** SystemCapability.Security.AccessToken
771

772 773
| 名称           | 类型                       | 可读 | 可写 | 说明                |
| -------------- | ------------------------- | ---- | ---- | ------------------ |
774 775
| change         | [PermissionStateChangeType](#permissionstatechangetype9) | 是   | 否   | 权限授权状态变化类型。        |
| tokenID        | number                    | 是   | 否   | 被订阅的应用身份标识。 |
L
lsq 已提交
776
| permissionName | Permissions                    | 是   | 否   | 当前授权状态发生变化的权限名,合法的权限名取值可在[系统权限定义列表](../../security/permission-list.md)中查询。 |