js-apis-privacyManager.md 28.9 KB
Newer Older
A
Annie_wang 已提交
1
# @ohos.privacyManager (Privacy Management)
A
Annie_wang 已提交
2

A
Annie_wang 已提交
3
The **privacyManager** module provides APIs for privacy management, such as management of permission usage records.
A
Annie_wang 已提交
4 5

> **NOTE**
A
Annie_wang 已提交
6
> The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version.
A
Annie_wang 已提交
7
> The APIs provided by this module are system APIs.
A
Annie_wang 已提交
8 9 10 11 12 13 14 15 16 17

## Modules to Import

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


## privacyManager.addPermissionUsedRecord

A
Annie_wang 已提交
18
addPermissionUsedRecord(tokenID: number, permissionName: Permissions, successCount: number, failCount: number): Promise<void>
A
Annie_wang 已提交
19 20

Adds a permission usage record when an application protected by the permission is called by another service or application. This API uses a promise to return the result.
A
Annie_wang 已提交
21
The permission usage record includes the application identity (token ID) of the invoker, name of the permission used, and number of successful and failed accesses to the target application.
A
Annie_wang 已提交
22 23 24 25 26 27 28 29 30

**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)

**System capability**: SystemCapability.Security.AccessToken

**Parameters**

| Name  | Type                | Mandatory| Description                                      |
| -------- | -------------------  | ---- | ------------------------------------------ |
A
Annie_wang 已提交
31 32
| tokenID   |  number   | Yes  | Application token ID of the invoker. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).             |
| permissionName | Permissions | Yes  | Name of the permission.|
A
Annie_wang 已提交
33 34 35 36 37 38 39
| successCount | number | Yes  | Number of successful accesses.|
| failCount | number | Yes  | Number of failed accesses.|

**Return value**

| Type         | Description                               |
| :------------ | :---------------------------------- |
A
Annie_wang 已提交
40
| Promise<void> | Promise that returns no value.|
A
Annie_wang 已提交
41

A
Annie_wang 已提交
42 43 44
**Error codes**

For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
A
Annie_wang 已提交
45

A
Annie_wang 已提交
46 47
| ID| Error Message|
| -------- | -------- |
A
Annie_wang 已提交
48 49 50 51 52
| 12100001 | The parameter is invalid. The tokenID is 0 |
| 12100002 | The specified tokenID does not exist or it does not refer to an application process. |
| 12100003 | The specified permission does not exist or it is not an user_grant permission. |
| 12100007 | Service is abnormal. |
| 12100008 | Out of memory. |
A
Annie_wang 已提交
53

A
Annie_wang 已提交
54 55 56
**Example**

```js
A
Annie_wang 已提交
57 58 59 60 61 62 63 64 65 66 67 68
import privacyManager from '@ohos.privacyManager';

let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID.
try {
    privacyManager.addPermissionUsedRecord(tokenID, "ohos.permission.PERMISSION_USED_STATS", 1, 0).then(() => {
        console.log('addPermissionUsedRecord success');
    }).catch((err) => {
        console.log(`addPermissionUsedRecord fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
A
Annie_wang 已提交
69 70 71 72
```

## privacyManager.addPermissionUsedRecord

A
Annie_wang 已提交
73
addPermissionUsedRecord(tokenID: number, permissionName: Permissions, successCount: number, failCount: number, callback: AsyncCallback<void>): void
A
Annie_wang 已提交
74 75

Adds a permission usage record when an application protected by the permission is called by another service or application. This API uses an asynchronous callback to return the result.
A
Annie_wang 已提交
76
The permission usage record includes the application identity (token ID) of the invoker, name of the permission used, and number of successful and failed accesses to the target application.
A
Annie_wang 已提交
77 78 79 80 81 82 83 84 85

**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)

**System capability**: SystemCapability.Security.AccessToken

**Parameters**

| Name  | Type                | Mandatory| Description                                      |
| -------- | -------------------  | ---- | ------------------------------------------ |
A
Annie_wang 已提交
86 87
| tokenID   |  number   | Yes  | Application token ID of the invoker. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).             |
| permissionName | Permissions | Yes  | Name of the permission.|
A
Annie_wang 已提交
88 89
| successCount | number | Yes  | Number of successful accesses.|
| failCount | number | Yes  | Number of failed accesses.|
A
Annie_wang 已提交
90 91 92 93 94
| callback | AsyncCallback<void> | Yes  | Callback invoked to return the result. If a usage record is added successfully, **err** is **undefine**. Otherwise, **err** is an error object.|

**Error codes**

For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
A
Annie_wang 已提交
95

A
Annie_wang 已提交
96 97
| ID| Error Message|
| -------- | -------- |
A
Annie_wang 已提交
98 99 100 101 102
| 12100001 | The parameter is invalid. The tokenID is 0 |
| 12100002 | The specified tokenID does not exist or it does not refer to an application process. |
| 12100003 | The specified permission does not exist or it is not an user_grant permission. |
| 12100007 | Service is abnormal. |
| 12100008 | Out of memory. |
A
Annie_wang 已提交
103 104 105 106

**Example**

```js
A
Annie_wang 已提交
107 108 109 110
import privacyManager from '@ohos.privacyManager';

let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID.
try {
A
Annie_wang 已提交
111
    privacyManager.addPermissionUsedRecord(tokenID, "ohos.permission.PERMISSION_USED_STATS", 1, 0, (err, data) => {
A
Annie_wang 已提交
112 113 114 115 116 117 118 119 120
        if (err) {
            console.log(`addPermissionUsedRecord fail, err->${JSON.stringify(err)}`);
        } else {
            console.log('addPermissionUsedRecord success');
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
A
Annie_wang 已提交
121 122
```

L
lsq 已提交
123
## privacyManager.getPermissionUsedRecord
A
Annie_wang 已提交
124

L
lsq 已提交
125
getPermissionUsedRecord(request: PermissionUsedRequest): Promise<PermissionUsedResponse>
A
Annie_wang 已提交
126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142

Obtains historical permission usage records. This API uses a promise to return the result.

**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)

**System capability**: SystemCapability.Security.AccessToken

**Parameters**

| Name  | Type                | Mandatory| Description                                      |
| -------- | -------------------  | ---- | ------------------------------------------ |
| request   |  [PermissionUsedRequest](#permissionusedrequest)   | Yes  | Request for querying permission usage records.             |

**Return value**

| Type         | Description                               |
| :------------ | :---------------------------------- |
A
Annie_wang 已提交
143 144 145 146 147
| Promise<[PermissionUsedResponse](#permissionusedresponse)> | Promise used to return the permission usage records.|

**Error codes**

For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
A
Annie_wang 已提交
148

A
Annie_wang 已提交
149 150
| ID| Error Message|
| -------- | -------- |
A
Annie_wang 已提交
151 152 153 154 155
| 12100001 | The parameter is invalid. the value of flag in request is invalid. |
| 12100002 | The specified tokenID does not exist or it does not refer to an application process. |
| 12100003 | The specified permission does not exist or it is not an user_grant permission. |
| 12100007 | Service is abnormal. |
| 12100008 | Out of memory. |
A
Annie_wang 已提交
156 157 158 159

**Example**

```js
A
Annie_wang 已提交
160 161
import privacyManager from '@ohos.privacyManager';

A
Annie_wang 已提交
162 163
let request = {
    "tokenId": 1,
A
Annie_wang 已提交
164
    "isRemote": false,
A
Annie_wang 已提交
165 166
    "deviceId": "device",
    "bundleName": "bundle",
A
Annie_wang 已提交
167
    "permissionNames": [],
A
Annie_wang 已提交
168 169 170 171
    "beginTime": 0,
    "endTime": 1,
    "flag":privacyManager.PermissionUsageFlag.FLAG_PERMISSION_USAGE_DETAIL,
};
A
Annie_wang 已提交
172
try {
L
lsq 已提交
173 174
    privacyManager.getPermissionUsedRecord(request).then((data) => {
        console.log(`getPermissionUsedRecord success, data->${JSON.stringify(data)}`);
A
Annie_wang 已提交
175
    }).catch((err) => {
L
lsq 已提交
176
        console.log(`getPermissionUsedRecord fail, err->${JSON.stringify(err)}`);
A
Annie_wang 已提交
177 178 179 180
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
A
Annie_wang 已提交
181 182
```

L
lsq 已提交
183
## privacyManager.getPermissionUsedRecord
A
Annie_wang 已提交
184

L
lsq 已提交
185
getPermissionUsedRecord(request: PermissionUsedRequest, callback: AsyncCallback&lt;PermissionUsedResponse&gt;): void
A
Annie_wang 已提交
186 187 188 189 190 191 192 193 194 195 196 197

Obtains historical permission usage records. This API uses an asynchronous callback to return the result.

**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)

**System capability**: SystemCapability.Security.AccessToken

**Parameters**

| Name  | Type                | Mandatory| Description                                      |
| -------- | -------------------  | ---- | ------------------------------------------ |
| request | [PermissionUsedRequest](#permissionusedrequest) | Yes| Request for querying permission usage records.|
A
Annie_wang 已提交
198 199 200 201 202
| callback | AsyncCallback<[PermissionUsedResponse](#permissionusedresponse)> | Yes| Callback invoked to return the result. If the query is successful, **err** is **undefine** and **data** is the permission usage record. Otherwise, **err** is an error object.|

**Error codes**

For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
A
Annie_wang 已提交
203

A
Annie_wang 已提交
204 205
| ID| Error Message|
| -------- | -------- |
A
Annie_wang 已提交
206 207 208 209 210
| 12100001 | The parameter is invalid. the value of flag in request is invalid. |
| 12100002 | The specified tokenID does not exist or it does not refer to an application process. |
| 12100003 | The specified permission does not exist or it is not an user_grant permission. |
| 12100007 | Service is abnormal. |
| 12100008 | Out of memory. |
A
Annie_wang 已提交
211 212 213 214

**Example**

```js
A
Annie_wang 已提交
215 216
import privacyManager from '@ohos.privacyManager';

A
Annie_wang 已提交
217 218
let request = {
    "tokenId": 1,
A
Annie_wang 已提交
219
    "isRemote": false,
A
Annie_wang 已提交
220 221
    "deviceId": "device",
    "bundleName": "bundle",
A
Annie_wang 已提交
222
    "permissionNames": [],
A
Annie_wang 已提交
223 224 225 226
    "beginTime": 0,
    "endTime": 1,
    "flag":privacyManager.PermissionUsageFlag.FLAG_PERMISSION_USAGE_DETAIL,
};
A
Annie_wang 已提交
227
try {
L
lsq 已提交
228
    privacyManager.getPermissionUsedRecord(request, (err, data) => {
A
Annie_wang 已提交
229
        if (err) {
L
lsq 已提交
230
            console.log(`getPermissionUsedRecord fail, err->${JSON.stringify(err)}`);
A
Annie_wang 已提交
231
        } else {
L
lsq 已提交
232
            console.log(`getPermissionUsedRecord success, data->${JSON.stringify(data)}`);
A
Annie_wang 已提交
233 234 235 236 237 238 239 240 241
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
```

## privacyManager.startUsingPermission

A
Annie_wang 已提交
242
startUsingPermission(tokenID: number, permissionName: Permissions): Promise&lt;void&gt;
A
Annie_wang 已提交
243

A
Annie_wang 已提交
244
Starts to use a permission and flushes the permission usage record. This API is called by a system application, either running in the foreground or background, and uses a promise to return the result. This API uses a promise to return the result.
A
Annie_wang 已提交
245 246 247 248 249 250 251 252 253

**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)

**System capability**: SystemCapability.Security.AccessToken

**Parameters**

| Name         | Type  | Mandatory| Description                                 |
| -------------- | ------ | ---- | ------------------------------------ |
A
Annie_wang 已提交
254 255
| tokenID        | number | Yes  | Application token ID of the invoker. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).|
| permissionName | Permissions | Yes  | Permission to use.                    |
A
Annie_wang 已提交
256 257 258 259 260 261 262

**Return value**

| Type         | Description                                   |
| ------------- | --------------------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|

A
Annie_wang 已提交
263 264 265
**Error codes**

For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
A
Annie_wang 已提交
266

A
Annie_wang 已提交
267 268
| ID| Error Message|
| -------- | -------- |
A
Annie_wang 已提交
269 270 271 272 273 274
| 12100001 | The parameter is invalid. The tokenID is 0 |
| 12100002 | The specified tokenID does not exist or it does not refer to an application process. |
| 12100003 | The specified permission does not exist or it is not an user_grant permission. |
| 12100004 | The interface is called repeatedly with the same input. It means the application specified by the tokenID has been using the specified permission. |
| 12100007 | Service is abnormal. |
| 12100008 | Out of memory. |
A
Annie_wang 已提交
275

A
Annie_wang 已提交
276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294
**Example**

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

let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID.
try {
    privacyManager.startUsingPermission(tokenID, "ohos.permission.PERMISSION_USED_STATS").then(() => {
        console.log('startUsingPermission success');
    }).catch((err) => {
        console.log(`startUsingPermission fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
```

## privacyManager.startUsingPermission

A
Annie_wang 已提交
295
startUsingPermission(tokenID: number, permissionName: Permissions, callback: AsyncCallback&lt;void&gt;): void
A
Annie_wang 已提交
296

A
Annie_wang 已提交
297
Starts to use a permission and flushes the permission usage record. This API is called by a system application, either running in the foreground or background, and uses a promise to return the result. This API uses an asynchronous callback to return the result.
A
Annie_wang 已提交
298 299 300 301 302 303 304 305 306

**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)

**System capability**: SystemCapability.Security.AccessToken

**Parameters**

| Name         | Type                 | Mandatory| Description                                 |
| -------------- | --------------------- | ---- | ------------------------------------ |
A
Annie_wang 已提交
307 308 309 310 311 312 313
| tokenID        | number                | Yes  | Application token ID of the invoker. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).|
| permissionName | Permissions                | Yes  | Permission to use.                    |
| callback       | AsyncCallback&lt;void&gt; | Yes  | Callback invoked to return the result. If the permission is successfully used, **err** is **undefine**. Otherwise, **err** is an error object.|

**Error codes**

For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
A
Annie_wang 已提交
314

A
Annie_wang 已提交
315 316
| ID| Error Message|
| -------- | -------- |
A
Annie_wang 已提交
317 318 319 320 321 322
| 12100001 | The parameter is invalid. The tokenID is 0 |
| 12100002 | The specified tokenID does not exist or it does not refer to an application process. |
| 12100003 | The specified permission does not exist or it is not an user_grant permission. |
| 12100004 | The interface is called repeatedly with the same input. It means the application specified by the tokenID has been using the specified permission. |
| 12100007 | Service is abnormal. |
| 12100008 | Out of memory. |
A
Annie_wang 已提交
323 324 325 326 327 328 329 330

**Example**

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

let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID.
try {
A
Annie_wang 已提交
331
    privacyManager.startUsingPermission(tokenID, "ohos.permission.PERMISSION_USED_STATS", (err, data) => {
A
Annie_wang 已提交
332 333 334 335 336 337 338 339 340 341 342 343 344
        if (err) {
            console.log(`startUsingPermission fail, err->${JSON.stringify(err)}`);
        } else {
            console.log('startUsingPermission success');
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
```

## privacyManager.stopUsingPermission

A
Annie_wang 已提交
345
stopUsingPermission(tokenID: number, permissionName: Permissions): Promise&lt;void&gt;
A
Annie_wang 已提交
346

A
Annie_wang 已提交
347
Stops using a permission. This API is called by a system application and uses a promise to return the result. **startUsingPermission** and **stopUsingPermission** are used in pairs. This API uses a promise to return the result.
A
Annie_wang 已提交
348 349 350 351 352 353 354 355 356

**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)

**System capability**: SystemCapability.Security.AccessToken

**Parameters**

| Name         | Type  | Mandatory| Description                                 |
| -------------- | ------ | ---- | ------------------------------------ |
A
Annie_wang 已提交
357 358
| tokenID        | number | Yes  | Application token ID of the invoker. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).|
| permissionName | Permissions | Yes  | Permission to use.                    |
A
Annie_wang 已提交
359 360 361 362 363 364 365

**Return value**

| Type         | Description                                   |
| ------------- | --------------------------------------- |
| Promise&lt;void&gt; | Promise that returns no value.|

A
Annie_wang 已提交
366 367 368
**Error codes**

For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
A
Annie_wang 已提交
369

A
Annie_wang 已提交
370 371
| ID| Error Message|
| -------- | -------- |
A
Annie_wang 已提交
372 373 374 375 376 377
| 12100001 | The parameter is invalid. The tokenID is 0 |
| 12100002 | The specified tokenID does not exist or it does not refer to an application process. |
| 12100003 | The specified permission does not exist or it is not an user_grant permission. |
| 12100004 | The interface is not used with |
| 12100007 | Service is abnormal. |
| 12100008 | Out of memory. |
A
Annie_wang 已提交
378

A
Annie_wang 已提交
379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397
**Example**

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

let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID.
try {
    privacyManager.stopUsingPermission(tokenID, "ohos.permission.PERMISSION_USED_STATS").then(() => {
        console.log('stopUsingPermission success');
    }).catch((err) => {
        console.log(`stopUsingPermission fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
```

## privacyManager.stopUsingPermission

A
Annie_wang 已提交
398
stopUsingPermission(tokenID: number, permissionName: Permissions, callback: AsyncCallback&lt;void&gt;): void
A
Annie_wang 已提交
399

A
Annie_wang 已提交
400
Stops using a permission. This API is called by a system application and uses a promise to return the result. **startUsingPermission** and **stopUsingPermission** are used in pairs. This API uses an asynchronous callback to return the result.
A
Annie_wang 已提交
401 402 403 404 405 406 407 408 409

**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)

**System capability**: SystemCapability.Security.AccessToken

**Parameters**

| Name         | Type                 | Mandatory| Description                                 |
| -------------- | --------------------- | ---- | ------------------------------------ |
A
Annie_wang 已提交
410 411 412 413 414 415 416
| tokenID        | number                | Yes  | Application token ID of the invoker. The value can be obtained from [ApplicationInfo](js-apis-bundle-ApplicationInfo.md).|
| permissionName | Permissions                | Yes  | Permission to use.                     |
| callback       | AsyncCallback&lt;void&gt; | Yes  | Callback invoked to return the result. If the operation is successful, **err** is **undefine**. Otherwise, **err** is an error object.|

**Error codes**

For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
A
Annie_wang 已提交
417

A
Annie_wang 已提交
418 419
| ID| Error Message|
| -------- | -------- |
A
Annie_wang 已提交
420 421 422 423 424 425
| 12100001 | The parameter is invalid. The tokenID is 0 |
| 12100002 | The specified tokenID does not exist or it does not refer to an application process. |
| 12100003 | The specified permission does not exist or it is not an user_grant permission. |
| 12100004 | The interface is not used with |
| 12100007 | Service is abnormal. |
| 12100008 | Out of memory. |
A
Annie_wang 已提交
426 427 428 429 430 431 432 433

**Example**

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

let tokenID = 0; // You can use getApplicationInfo to obtain the access token ID.
try {
A
Annie_wang 已提交
434
    privacyManager.stopUsingPermission(tokenID, "ohos.permission.PERMISSION_USED_STATS", (err, data) => {
A
Annie_wang 已提交
435 436 437 438 439 440 441 442 443 444 445 446 447
        if (err) {
            console.log(`stopUsingPermission fail, err->${JSON.stringify(err)}`);
        } else {
            console.log('stopUsingPermission success');
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
```

## privacyManager.on

A
Annie_wang 已提交
448
on(type: 'activeStateChange', permissionNameList: Array&lt;Permissions&gt;, callback: Callback&lt;ActiveChangeResponse&gt;): void
A
Annie_wang 已提交
449

A
Annie_wang 已提交
450
Subscribes to the permission usage status changes of the specified permissions.
A
Annie_wang 已提交
451

A
Annie_wang 已提交
452
**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)
A
Annie_wang 已提交
453 454 455 456 457 458 459

**System capability**: SystemCapability.Security.AccessToken

**Parameters**

| Name            | Type                  | Mandatory| Description                                                         |
| ------------------ | --------------------- | ---- | ------------------------------------------------------------ |
A
Annie_wang 已提交
460
| type               | string                | Yes  | Event type to subscribe to. The value is **'activeStateChange'**, which indicates the permission usage change event.  |
A
Annie_wang 已提交
461
| permissionNameList | Array&lt;Permissions&gt;   | Yes  | List of permissions to be observed. If this parameter is left empty, the usage changes of all permissions are observed.          |
A
Annie_wang 已提交
462 463 464 465 466
| callback | Callback&lt;[ActiveChangeResponse](#activechangeresponse)&gt; | Yes| Callback invoked to return a change in the permission usage.|

**Error codes**

For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
A
Annie_wang 已提交
467

A
Annie_wang 已提交
468 469
| ID| Error Message|
| -------- | -------- |
A
Annie_wang 已提交
470 471 472 473 474
| 12100001 | The parameter is invalid. The tokenID is 0 |
| 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. |
A
Annie_wang 已提交
475 476 477 478 479 480

**Example**

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

A
Annie_wang 已提交
481
let permissionNameList = [];
A
Annie_wang 已提交
482
try {
A
Annie_wang 已提交
483
    privacyManager.on('activeStateChange', permissionNameList, (data) => {
A
Annie_wang 已提交
484 485 486 487 488 489 490 491 492
        console.debug("receive permission state change, data:" + JSON.stringify(data));
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
```

## privacyManager.off

A
Annie_wang 已提交
493
off(type: 'activeStateChange', permissionNameList: Array&lt;Permissions&gt;, callback?: Callback&lt;ActiveChangeResponse&gt;): void;
A
Annie_wang 已提交
494

A
Annie_wang 已提交
495
Unsubscribes from the permission usage status changes of the specified permissions.
A
Annie_wang 已提交
496

A
Annie_wang 已提交
497
**Required permissions**: ohos.permission.PERMISSION_USED_STATS (available only to system applications)
A
Annie_wang 已提交
498 499 500 501 502 503 504

**System capability**: SystemCapability.Security.AccessToken

**Parameters**

| Name            | Type                  | Mandatory| Description                                                         |
| ------------------ | --------------------- | ---- | ------------------------------------------------------------ |
A
Annie_wang 已提交
505
| type               | string                | Yes  | Event type to subscribe to. The value is **'activeStateChange'**, which indicates the permission usage change event.  |
A
Annie_wang 已提交
506
| permissionNameList | Array&lt;Permissions&gt;   | Yes  | List of permissions to be observed. If this parameter is left blank, the usage changes of all permissions are unsubscribed from. The value must be the same as that specified in **on()**.|
A
Annie_wang 已提交
507 508
| callback | Callback&lt;[ActiveChangeResponse](#activechangeresponse)&gt; | No| Callback for the permission usage change event.|

A
Annie_wang 已提交
509 510 511
**Error codes**

For details about the error codes, see [Ability Access Control Error Codes](../errorcodes/errorcode-access-token.md).
A
Annie_wang 已提交
512

A
Annie_wang 已提交
513 514
| ID| Error Message|
| -------- | -------- |
A
Annie_wang 已提交
515 516 517 518
| 12100001 | The parameter is invalid. The permissionName in list is all invalid or the list size is larger than 1024. |
| 12100004 | The interface is not used with |
| 12100007 | Service is abnormal. |
| 12100008 | Out of memory. |
A
Annie_wang 已提交
519

A
Annie_wang 已提交
520 521 522 523 524
**Example**

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

A
Annie_wang 已提交
525
let permissionNameList = [];
A
Annie_wang 已提交
526 527 528 529 530
try {
    privacyManager.off('activeStateChange', permissionNameList);
}catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}
A
Annie_wang 已提交
531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551
```

## PermissionUsageFlag

Enumerates the modes for querying the permission usage records.

**System capability**: SystemCapability.Security.AccessToken

| Name                   | Value| Description                  |
| ----------------------- | ------ | ---------------------- |
| FLAG_PERMISSION_USAGE_SUMMARY             | 0    | Query the permission usage summary.|
| FLAG_PERMISSION_USAGE_DETAIL         | 1    | Query detailed permission usage records.        |

## PermissionUsedRequest

Represents the request for querying permission usage records.

**System capability**: SystemCapability.Security.AccessToken

| Name      | Type            | Mandatory  | Description                                      |
| -------- | -------------- | ---- | ---------------------------------------- |
A
Annie_wang 已提交
552 553
| tokenId  | number         | No   | Token ID of the application (invoker).                                |
| isRemote | boolean         | No   | Whether the token ID belongs to the application on a remote device. The default value is **false**.|
A
Annie_wang 已提交
554 555
| deviceId  | string         | No   | ID of the device hosting the target application.                                |
| bundleName | string         | No   | Bundle name of the target application.|
A
Annie_wang 已提交
556
| permissionNames  | Array&lt;Permissions&gt;         | No   | Permissions to query.                                |
A
Annie_wang 已提交
557 558 559 560 561 562 563 564 565 566 567 568 569 570
| beginTime | number         | No   | Start time of the query, in ms. The default value is **0**, indicating that no start time is set.|
| endTime | number         | No   | End time of the query, in ms. The default value is **0**, indicating that no end time is set.|
| flag | [PermissionUsageFlag](#permissionusageflag)         | Yes   | Query mode. The default value is **FLAG_PERMISSION_USAGE_SUMMARY**.|

## PermissionUsedResponse

Represents the permission usage records of all applications.

**System capability**: SystemCapability.Security.AccessToken

| Name      | Type            | Mandatory  | Description                                      |
| -------- | -------------- | ---- | ---------------------------------------- |
| beginTime | number         | No   | Start time of the query, in ms.|
| endTime | number         | No   | End time of the query, in ms.|
A
Annie_wang 已提交
571
| bundleRecords  | Array&lt;[BundleUsedRecord](#bundleusedrecord)&gt;         | No   | Permission usage records.                                |
A
Annie_wang 已提交
572 573 574

## BundleUsedRecord

A
Annie_wang 已提交
575
Represents the permission access records of an application.
A
Annie_wang 已提交
576 577 578 579 580

**System capability**: SystemCapability.Security.AccessToken

| Name      | Type            | Mandatory  | Description                                      |
| -------- | -------------- | ---- | ---------------------------------------- |
A
Annie_wang 已提交
581 582
| tokenId  | number         | No   | Token ID of the application (invoker).                                |
| isRemote | boolean         | No   | Whether the token ID belongs to the application on a remote device. The default value is **false**.|
A
Annie_wang 已提交
583 584
| deviceId  | string         | No   | ID of the device hosting the target application.                                |
| bundleName | string         | No   | Bundle name of the target application.|
A
Annie_wang 已提交
585
| permissionRecords  | Array&lt;[PermissionUsedRecord](#permissionusedrecord)&gt;         | No   | Permission usage records of the target application.                                |
A
Annie_wang 已提交
586 587 588

## PermissionUsedRecord

A
Annie_wang 已提交
589
Represents the usage records of a permission.
A
Annie_wang 已提交
590 591 592 593 594

**System capability**: SystemCapability.Security.AccessToken

| Name      | Type            | Mandatory  | Description                                      |
| -------- | -------------- | ---- | ---------------------------------------- |
A
Annie_wang 已提交
595
| permissionName  | Permissions         | No   | Name of the permission.                                |
A
Annie_wang 已提交
596 597
| accessCount | number         | No   | Total number of times that the permission is accessed.|
| rejectCount | number         | No   | Total number of times that the access to the permission is rejected.|
A
Annie_wang 已提交
598 599
| lastAccessTime | number         | No   | Last time when the permission was accessed, accurate to ms.|
| lastRejectTime | number         | No   | Last time when the access to the permission was rejected, accurate to ms.|
A
Annie_wang 已提交
600
| lastAccessDuration | number         | No   | Last access duration, in ms.|
A
Annie_wang 已提交
601 602
| accessRecords  | Array&lt;[UsedRecordDetail](#usedrecorddetail)&gt;         | No   | Successful access records. This parameter is valid only when **flag** is **FLAG_PERMISSION_USAGE_SUMMARY**. By default, 10 records are provided.                                |
| rejectRecords  | Array&lt;[UsedRecordDetail](#usedrecorddetail)&gt;         | No   | Rejected access records. This parameter is valid only when **flag** is **FLAG_PERMISSION_USAGE_SUMMARY**. By default, 10 records are provided.                                |
A
Annie_wang 已提交
603 604 605 606 607 608 609 610 611 612 613 614

## UsedRecordDetail

Represents the details of a single access record.

**System capability**: SystemCapability.Security.AccessToken

| Name      | Type            | Mandatory  | Description                                      |
| -------- | -------------- | ---- | ---------------------------------------- |
| status  | number         | No   | Access status.                                |
| timestamp | number         | No   | Access timestamp, in ms.|
| accessDuration  | number         | No   | Access duration, in ms.                                |
A
Annie_wang 已提交
615 616 617

## PermissionActiveStatus

A
Annie_wang 已提交
618
Enumerates the permission usage statuses.
A
Annie_wang 已提交
619 620 621

**System capability**: SystemCapability.Security.AccessToken

A
Annie_wang 已提交
622
| Name                     | Value    | Description             |
A
Annie_wang 已提交
623 624
| ------------------------- | ------ | ---------------- |
| PERM_INACTIVE             | 0      | The permission is not used.  |
A
Annie_wang 已提交
625 626
| PERM_ACTIVE_IN_FOREGROUND | 1      | The permission is being used by an application running in the foreground.|
| PERM_ACTIVE_IN_BACKGROUND | 2      | The permission is being used by an application running in the background.|
A
Annie_wang 已提交
627 628 629 630 631 632 633 634 635

## ActiveChangeResponse

Defines the detailed permission usage information.

 **System capability**: SystemCapability.Security.AccessToken

| Name          | Type                   | Readable| Writable| Description                  |
| -------------- | ---------------------- | ---- | ---- | --------------------- |
A
Annie_wang 已提交
636 637 638
| tokenId        | number                 | Yes  | No  | Token ID of the application.   |
| permissionName | Permissions                 | Yes  | No  | Name of the permission.|
| deviceId       | string                 | Yes  | No  | Device ID.                |
A
Annie_wang 已提交
639
| activeStatus   | [PermissionActiveStatus](#permissionactivestatus) | Yes  | No  | Permission usage status.       |