@ohos.privacyManager (Privacy Management)

The privacyManager module provides APIs for privacy management, such as management of permission usage records.

NOTE

  • 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.
  • The APIs provided by this module are system APIs.

Modules to Import

import privacyManager from '@ohos.privacyManager';

privacyManager.addPermissionUsedRecord

addPermissionUsedRecord(tokenID: number, permissionName: Permissions, successCount: number, failCount: number): Promise<void>

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. 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.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Name Type Mandatory Description
tokenID number Yes Application token ID of the invoker. The value can be obtained from ApplicationInfo.
permissionName Permissions Yes Name of the permission.
successCount number Yes Number of successful accesses.
failCount number Yes Number of failed accesses.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Ability Access Control Error Codes.

ID Error Message
12100001 The parameter is invalid. The tokenID is 0, the permissionName is longer than 256 bytes, or the count value is invalid.
12100002 The specified tokenID does not exist or refer to an application process.
12100003 The specified permission does not exist or is not an user_grant permission.
12100007 Service is abnormal.
12100008 Out of memory.

Example

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)}`);
}

privacyManager.addPermissionUsedRecord

addPermissionUsedRecord(tokenID: number, permissionName: Permissions, successCount: number, failCount: number, callback: AsyncCallback<void>): void

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. 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.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Name Type Mandatory Description
tokenID number Yes Application token ID of the invoker. The value can be obtained from ApplicationInfo.
permissionName Permissions Yes Name of the permission.
successCount number Yes Number of successful accesses.
failCount number Yes Number of failed accesses.
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.

ID Error Message
12100001 The parameter is invalid. The tokenID is 0, the permissionName is longer than 256 bytes, or the count value is invalid.
12100002 The specified tokenID does not exist or refer to an application process.
12100003 The specified permission does not exist or is not an user_grant permission.
12100007 Service is abnormal.
12100008 Out of memory.

Example

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, (err, data) => {
        if (err) {
            console.log(`addPermissionUsedRecord fail, err->${JSON.stringify(err)}`);
        } else {
            console.log('addPermissionUsedRecord success');
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

privacyManager.getPermissionUsedRecord

getPermissionUsedRecord(request: PermissionUsedRequest): Promise<PermissionUsedResponse>

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 Yes Request for querying permission usage records.

Return value

Type Description
Promise<PermissionUsedResponse> Promise used to return the permission usage records.

Error codes

For details about the error codes, see Ability Access Control Error Codes.

ID Error Message
12100001 The parameter is invalid. the value of flag in request is invalid.
12100002 The specified tokenID does not exist or refer to an application process.
12100003 The specified permission does not exist or is not an user_grant permission.
12100007 Service is abnormal.
12100008 Out of memory.

Example

import privacyManager from '@ohos.privacyManager';

let request = {
    "tokenId": 1,
    "isRemote": false,
    "deviceId": "device",
    "bundleName": "bundle",
    "permissionNames": [],
    "beginTime": 0,
    "endTime": 1,
    "flag":privacyManager.PermissionUsageFlag.FLAG_PERMISSION_USAGE_DETAIL,
};
try {
    privacyManager.getPermissionUsedRecord(request).then((data) => {
        console.log(`getPermissionUsedRecord success, data->${JSON.stringify(data)}`);
    }).catch((err) => {
        console.log(`getPermissionUsedRecord fail, err->${JSON.stringify(err)}`);
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

privacyManager.getPermissionUsedRecord

getPermissionUsedRecord(request: PermissionUsedRequest, callback: AsyncCallback<PermissionUsedResponse>): void

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 Yes Request for querying permission usage records.
callback AsyncCallback<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.

ID Error Message
12100001 The parameter is invalid. the value of flag in request is invalid.
12100002 The specified tokenID does not exist or refer to an application process.
12100003 The specified permission does not exist or is not an user_grant permission.
12100007 Service is abnormal.
12100008 Out of memory.

Example

import privacyManager from '@ohos.privacyManager';

let request = {
    "tokenId": 1,
    "isRemote": false,
    "deviceId": "device",
    "bundleName": "bundle",
    "permissionNames": [],
    "beginTime": 0,
    "endTime": 1,
    "flag":privacyManager.PermissionUsageFlag.FLAG_PERMISSION_USAGE_DETAIL,
};
try {
    privacyManager.getPermissionUsedRecord(request, (err, data) => {
        if (err) {
            console.log(`getPermissionUsedRecord fail, err->${JSON.stringify(err)}`);
        } else {
            console.log(`getPermissionUsedRecord success, data->${JSON.stringify(data)}`);
        }
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

privacyManager.startUsingPermission

startUsingPermission(tokenID: number, permissionName: Permissions): Promise<void>

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.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Name Type Mandatory Description
tokenID number Yes Application token ID of the invoker. The value can be obtained from ApplicationInfo.
permissionName Permissions Yes Permission to use.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Ability Access Control Error Codes.

ID Error Message
12100001 The parameter is invalid. The tokenID is 0, the permissionName is longer than 256 bytes, or the count value is invalid.
12100002 The specified tokenID does not exist or refer to an application process.
12100003 The specified permission does not exist or 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.

Example

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

startUsingPermission(tokenID: number, permissionName: Permissions, callback: AsyncCallback<void>): void

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.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Name Type Mandatory Description
tokenID number Yes Application token ID of the invoker. The value can be obtained from ApplicationInfo.
permissionName Permissions Yes Permission to use.
callback AsyncCallback<void> 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.

ID Error Message
12100001 The parameter is invalid. The tokenID is 0, or the permissionName is longer than 256 bytes.
12100002 The specified tokenID does not exist or refer to an application process.
12100003 The specified permission does not exist or 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.

Example

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", (err, data) => {
        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

stopUsingPermission(tokenID: number, permissionName: Permissions): Promise<void>

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.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Name Type Mandatory Description
tokenID number Yes Application token ID of the invoker. The value can be obtained from ApplicationInfo.
permissionName Permissions Yes Permission to use.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Ability Access Control Error Codes.

ID Error Message
12100001 The parameter is invalid. The tokenID is 0, or the permissionName is longer than 256 bytes.
12100002 The specified tokenID does not exist or refer to an application process.
12100003 The specified permission does not exist or is not an user_grant permission.
12100004 The interface is not used with
12100007 Service is abnormal.
12100008 Out of memory.

Example

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

stopUsingPermission(tokenID: number, permissionName: Permissions, callback: AsyncCallback<void>): void

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.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Name Type Mandatory Description
tokenID number Yes Application token ID of the invoker. The value can be obtained from ApplicationInfo.
permissionName Permissions Yes Permission to use.
callback AsyncCallback<void> 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.

ID Error Message
12100001 The parameter is invalid. The tokenID is 0, or the permissionName is longer than 256 bytes.
12100002 The specified tokenID does not exist or refer to an application process.
12100003 The specified permission does not exist or is not an user_grant permission.
12100004 The interface is not used with
12100007 Service is abnormal.
12100008 Out of memory.

Example

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", (err, data) => {
        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

on(type: 'activeStateChange', permissionList: Array<Permissions>, callback: Callback<ActiveChangeResponse>): void

Subscribes to the permission usage status changes of the specified permissions.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Name Type Mandatory Description
type string Yes Event type to subscribe to. The value is 'activeStateChange', which indicates the permission usage change event.
permissionList Array<Permissions> Yes List of permissions to be observed. If this parameter is left empty, the usage changes of all permissions are observed.
callback Callback<ActiveChangeResponse> 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.

ID Error Message
12100001 The parameter is invalid. The tokenID is 0, or the permissionName is longer than 256 bytes.
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.

Example

import privacyManager from '@ohos.privacyManager';

let permissionList = [];
try {
    privacyManager.on('activeStateChange', permissionList, (data) => {
        console.debug("receive permission state change, data:" + JSON.stringify(data));
    });
} catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

privacyManager.off

off(type: 'activeStateChange', permissionList: Array<Permissions>, callback?: Callback<ActiveChangeResponse>): void;

Unsubscribes from the permission usage status changes of the specified permissions.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Name Type Mandatory Description
type string Yes Event type to subscribe to. The value is 'activeStateChange', which indicates the permission usage change event.
permissionList Array<Permissions> 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().
callback Callback<ActiveChangeResponse> No Callback for the permission usage change event.

Error codes

For details about the error codes, see Ability Access Control Error Codes.

ID Error Message
12100001 The parameter is invalid. The permissionNames in the list are all invalid, or the list size exceeds 1024 bytes.
12100004 The API is not used together with "on()".
12100007 Service is abnormal.
12100008 Out of memory.

Example

import privacyManager from '@ohos.privacyManager';

let permissionList = [];
try {
    privacyManager.off('activeStateChange', permissionList);
}catch(err) {
    console.log(`catch err->${JSON.stringify(err)}`);
}

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
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.
deviceId string No ID of the device hosting the target application.
bundleName string No Bundle name of the target application.
permissionNames Array<Permissions> No Permissions to query.
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 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.
bundleRecords Array<BundleUsedRecord> No Permission usage records.

BundleUsedRecord

Represents the permission access records of an application.

System capability: SystemCapability.Security.AccessToken

Name Type Mandatory Description
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.
deviceId string No ID of the device hosting the target application.
bundleName string No Bundle name of the target application.
permissionRecords Array<PermissionUsedRecord> No Permission usage records of the target application.

PermissionUsedRecord

Represents the usage records of a permission.

System capability: SystemCapability.Security.AccessToken

Name Type Mandatory Description
permissionName Permissions No Name of the permission.
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.
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.
lastAccessDuration number No Last access duration, in ms.
accessRecords Array<UsedRecordDetail> No Successful access records. This parameter is valid only when flag is FLAG_PERMISSION_USAGE_SUMMARY. By default, 10 records are provided.
rejectRecords Array<UsedRecordDetail> No Rejected access records. This parameter is valid only when flag is FLAG_PERMISSION_USAGE_SUMMARY. By default, 10 records are provided.

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.

PermissionActiveStatus

Enumerates the permission usage statuses.

System capability: SystemCapability.Security.AccessToken

Name Value Description
PERM_INACTIVE 0 The permission is not used.
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.

ActiveChangeResponse

Defines the detailed permission usage information.

System capability: SystemCapability.Security.AccessToken

Name Type Readable Writable Description
tokenId number Yes No Token ID of the application.
permissionName Permissions Yes No Name of the permission.
deviceId string Yes No Device ID.
activeStatus PermissionActiveStatus Yes No Permission usage status.