@ohos.privacyManager (Privacy Management) (System API)

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 '@kit.AbilityKit';

privacyManager.addPermissionUsedRecord

addPermissionUsedRecord(tokenID: number, permissionName: Permissions, successCount: number, failCount: number, options?: AddPermissionUsedRecordOptions): 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 caller, 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

Return value

Error codes

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

Example

import { privacyManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tokenID: number = 0; // You can use getApplicationInfo to obtain accessTokenId.
privacyManager.addPermissionUsedRecord(tokenID, 'ohos.permission.READ_AUDIO', 1, 0).then(() => {
  console.log('addPermissionUsedRecord success');
}).catch((err: BusinessError) => {
  console.error(`addPermissionUsedRecord fail, err->${JSON.stringify(err)}`);
});
// with options param
let options: privacyManager.AddPermissionUsedRecordOptions = {
  usedType: privacyManager.PermissionUsedType.PICKER_TYPE
};
privacyManager.addPermissionUsedRecord(tokenID, 'ohos.permission.READ_AUDIO', 1, 0, options).then(() => {
  console.log('addPermissionUsedRecord success');
}).catch((err: BusinessError) => {
  console.error(`addPermissionUsedRecord fail, 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 caller, 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

Error codes

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

Example

import { privacyManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tokenID: number = 0; // You can use getApplicationInfo to obtain accessTokenId.
privacyManager.addPermissionUsedRecord(tokenID, 'ohos.permission.READ_AUDIO', 1, 0, (err: BusinessError, data: void) => {
  if (err) {
    console.error(`addPermissionUsedRecord fail, err->${JSON.stringify(err)}`);
  } else {
    console.log('addPermissionUsedRecord success');
  }
});

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

Return value

Error codes

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

Example

import { privacyManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let request: privacyManager.PermissionUsedRequest = {
    'tokenId': 1,
    'isRemote': false,
    'deviceId': 'device',
    'bundleName': 'bundle',
    'permissionNames': [],
    'beginTime': 0,
    'endTime': 1,
    'flag':privacyManager.PermissionUsageFlag.FLAG_PERMISSION_USAGE_DETAIL,
};

privacyManager.getPermissionUsedRecord(request).then((data) => {
  console.log(`getPermissionUsedRecord success, data->${JSON.stringify(data)}`);
}).catch((err: BusinessError) => {
  console.error(`getPermissionUsedRecord fail, 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

Error codes

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

Example

import { privacyManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let request: privacyManager.PermissionUsedRequest = {
    'tokenId': 1,
    'isRemote': false,
    'deviceId': 'device',
    'bundleName': 'bundle',
    'permissionNames': [],
    'beginTime': 0,
    'endTime': 1,
    'flag':privacyManager.PermissionUsageFlag.FLAG_PERMISSION_USAGE_DETAIL,
};

privacyManager.getPermissionUsedRecord(request, (err: BusinessError, data: privacyManager.PermissionUsedResponse) => {
  if (err) {
    console.error(`getPermissionUsedRecord fail, err->${JSON.stringify(err)}`);
  } else {
    console.log(`getPermissionUsedRecord success, data->${JSON.stringify(data)}`);
  }
});

privacyManager.setPermissionUsedRecordToggleStatus¹⁸⁺

setPermissionUsedRecordToggleStatus(status: boolean): Promise<void>

Sets whether to record the permission usage of this user. This API uses a promise to return the result.

If status is true, addPermissionUsedRecord can be called to add permission usage records. If status is set false, addPermissionUsedRecord does not add permission usage records. Instead, it deletes the historical records of the user.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

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

Example

import { privacyManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

privacyManager.setPermissionUsedRecordToggleStatus(true).then(() => {
  console.log('setPermissionUsedRecordToggleStatus success');
}).catch((err: BusinessError) => {
  console.error(`setPermissionUsedRecordToggleStatus fail, err->${JSON.stringify(err)}`);
});

privacyManager.getPermissionUsedRecordToggleStatus¹⁸⁺

getPermissionUsedRecordToggleStatus(): Promise<boolean>

Obtains the settings of the permission usage record switch for this user. 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

Return value

Error codes

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

Example

import { privacyManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

privacyManager.getPermissionUsedRecordToggleStatus().then((res) => {
  console.log('getPermissionUsedRecordToggleStatus success');
  if (res == true) {
    console.log('get status is TRUE');
  } else {
    console.log('get status is FALSE');
  }
}).catch((err: BusinessError) => {
  console.error(`getPermissionUsedRecordToggleStatus fail, err->${JSON.stringify(err)}`);
});

privacyManager.startUsingPermission

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

Starts using a permission. This API is called by a system application to report the permission usage of an application in the foreground and background, allowing the privacy service to respond based on the application lifecycle. This API uses a promise to return the result.

When an application starts to use a permission, the privacy service notifies the privacy indicator that the application is using the permission. Upon the application’s exit, the privacy service notifies the privacy indicator that the application has stopped using the permission and clears the corresponding cache.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

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

Example

import { privacyManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tokenID: number = 0; // You can use getApplicationInfo to obtain accessTokenId.
privacyManager.startUsingPermission(tokenID, 'ohos.permission.READ_AUDIO').then(() => {
  console.log('startUsingPermission success');
}).catch((err: BusinessError) => {
  console.error(`startUsingPermission fail, err->${JSON.stringify(err)}`);
});

privacyManager.startUsingPermission¹⁸⁺

startUsingPermission(tokenID: number, permissionName: Permissions, pid?: number, usedType?: PermissionUsedType): Promise<void>

Starts using a permission. This API is called by a system application to report the permission usage of an application in the foreground and background, allowing the privacy service to respond based on the application lifecycle. This API uses a promise to return the result.

When an application starts to use a permission, the privacy service notifies the privacy indicator that the application is using the permission. Upon the application’s exit, the privacy service notifies the privacy indicator that the application has stopped using the permission and clears the corresponding cache.

For a multi-process application, you can specify the process ID (PID) of the application when reporting the permission usage. If no PID is specified, the privacy service responds by application. When the application exits, the privacy service notifies the privacy indicator and clears the cache.

If a PID is specified, the privacy service responds by process. when the process exits, the privacy service notifies the privacy indicator and clears the cache. In this case, the PID must be that of the application corresponding to the token ID.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

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

Example

import { privacyManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { rpc } from '@kit.IPCKit'

let tokenID: number = rpc.IPCSkeleton.getCallingTokenId(); // accessTokenId can also be obtained by using bundleManager.getBundleInfoForSelfSync.
let pid: number = rpc.IPCSkeleton.getCallingPid();
let usedType: privacyManager.PermissionUsedType = privacyManager.PermissionUsedType.PICKER_TYPE;

// without pid and usedType
privacyManager.startUsingPermission(tokenID, 'ohos.permission.READ_AUDIO').then(() => {
  console.log('startUsingPermission success');
}).catch((err: BusinessError) => {
  console.error(`startUsingPermission fail, err->${JSON.stringify(err)}`);
});
// with pid
privacyManager.startUsingPermission(tokenID, 'ohos.permission.READ_AUDIO', pid).then(() => {
  console.log('startUsingPermission success');
}).catch((err: BusinessError) => {
  console.error(`startUsingPermission fail, err->${JSON.stringify(err)}`);
});
// with usedType
privacyManager.startUsingPermission(tokenID, 'ohos.permission.READ_AUDIO', -1, usedType).then(() => {
  console.log('startUsingPermission success');
}).catch((err: BusinessError) => {
  console.error(`startUsingPermission fail, err->${JSON.stringify(err)}`);
});
// with pid and usedType
privacyManager.startUsingPermission(tokenID, 'ohos.permission.READ_AUDIO', pid, usedType).then(() => {
  console.log('startUsingPermission success');
}).catch((err: BusinessError) => {
  console.error(`startUsingPermission fail, err->${JSON.stringify(err)}`);
});

privacyManager.startUsingPermission

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

Starts using a permission. This API is called by a system application to report the permission usage of an application in the foreground and background, allowing the privacy service to respond based on the application lifecycle. This API uses an asynchronous callback to return the result.

When an application starts to use a permission, the privacy service notifies the privacy indicator that the application is using the permission. Upon the application’s exit, the privacy service notifies the privacy indicator that the application has stopped using the permission and clears the corresponding cache.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

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

Example

import { privacyManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tokenID: number = 0; // You can use getApplicationInfo to obtain accessTokenId.
privacyManager.startUsingPermission(tokenID, 'ohos.permission.READ_AUDIO', (err: BusinessError, data: void) => {
  if (err) {
    console.error(`startUsingPermission fail, err->${JSON.stringify(err)}`);
  } else {
    console.log('startUsingPermission success');
  }
});

privacyManager.stopUsingPermission

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

Stops using a permission. This API must be called by a system application, and used with startUsingPermission 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

Return value

Error codes

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

Example

import { privacyManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tokenID: number = 0; // You can use getApplicationInfo to obtain accessTokenId.
privacyManager.stopUsingPermission(tokenID, 'ohos.permission.READ_AUDIO').then(() => {
  console.log('stopUsingPermission success');
}).catch((err: BusinessError) => {
  console.error(`stopUsingPermission fail, err->${JSON.stringify(err)}`);
});

privacyManager.stopUsingPermission¹⁸⁺

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

Stops using a permission. This API must be called by a system application, and used with startUsingPermission in pairs. This API uses a promise to return the result.

The value of pid must match that used in startUsingPermission.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

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

Example

import { privacyManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { rpc } from '@kit.IPCKit'

let tokenID: number = rpc.IPCSkeleton.getCallingTokenId(); // accessTokenId can also be obtained by using bundleManager.getBundleInfoForSelfSync.
let pid: number = rpc.IPCSkeleton.getCallingPid();

// without pid
privacyManager.stopUsingPermission(tokenID, 'ohos.permission.READ_AUDIO').then(() => {
  console.log('stopUsingPermission success');
}).catch((err: BusinessError) => {
  console.error(`stopUsingPermission fail, err->${JSON.stringify(err)}`);
});

// with pid
privacyManager.stopUsingPermission(tokenID, 'ohos.permission.READ_AUDIO', pid).then(() => {
  console.log('stopUsingPermission success');
}).catch((err: BusinessError) => {
  console.error(`stopUsingPermission fail, err->${JSON.stringify(err)}`);
});

privacyManager.stopUsingPermission

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

Stops using a permission. This API must be called by a system application, and used with startUsingPermission 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

Error codes

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

Example

import { privacyManager } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tokenID: number = 0; // You can use getApplicationInfo to obtain accessTokenId.
privacyManager.stopUsingPermission(tokenID, 'ohos.permission.READ_AUDIO', (err: BusinessError, data: void) => {
  if (err) {
    console.error(`stopUsingPermission fail, err->${JSON.stringify(err)}`);
  } else {
    console.log('stopUsingPermission success');
  }
});

privacyManager.on

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

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

Multiple callbacks can be registered for the same permissionList.

The same callback cannot be registered for the permissionLists with overlapping values.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

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

Example

import { privacyManager, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

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

privacyManager.off

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

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

If callback is not specified, this API will unregister all callbacks for permissionList.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Error codes

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

Example

import { privacyManager, Permissions } from '@kit.AbilityKit';

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

privacyManager.getPermissionUsedTypeInfos¹²⁺

getPermissionUsedTypeInfos(tokenId?: number, permissionName?: Permissions): Promise<Array<PermissionUsedTypeInfo>>

Obtains information about how a sensitive permission is used by an application.

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

System capability: SystemCapability.Security.AccessToken

Parameters

Return value

Error codes

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

Example

import { privacyManager, Permissions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

let tokenId: number = 0; // You can use bundleManager.getApplicationInfo to obtain accessTokenId.
let permissionName: Permissions = 'ohos.permission.CAMERA';
// Without any parameter.
privacyManager.getPermissionUsedTypeInfos().then(() => {
  console.log('getPermissionUsedTypeInfos success');
}).catch((err: BusinessError) => {
  console.error(`getPermissionUsedTypeInfos fail, err->${JSON.stringify(err)}`);
});
// Pass in tokenId only.
privacyManager.getPermissionUsedTypeInfos(tokenId).then(() => {
  console.log('getPermissionUsedTypeInfos success');
}).catch((err: BusinessError) => {
  console.error(`getPermissionUsedTypeInfos fail, err->${JSON.stringify(err)}`);
});
// Pass in permissionName only.
privacyManager.getPermissionUsedTypeInfos(null, permissionName).then(() => {
  console.log('getPermissionUsedTypeInfos success');
}).catch((err: BusinessError) => {
  console.error(`getPermissionUsedTypeInfos fail, err->${JSON.stringify(err)}`);
});
// Pass in tokenId and permissionName.
privacyManager.getPermissionUsedTypeInfos(tokenId, permissionName).then(() => {
  console.log('getPermissionUsedTypeInfos success');
}).catch((err: BusinessError) => {
  console.error(`getPermissionUsedTypeInfos fail, err->${JSON.stringify(err)}`);
});

PermissionUsageFlag

Enumerates the modes for querying the permission usage records.

System capability: SystemCapability.Security.AccessToken

PermissionUsedRequest

Represents the request for querying permission usage records.

System capability: SystemCapability.Security.AccessToken

PermissionUsedResponse

Represents the permission usage records of all applications.

System capability: SystemCapability.Security.AccessToken

BundleUsedRecord

Represents the permission access records of an application.

System capability: SystemCapability.Security.AccessToken

PermissionUsedRecord

Represents the usage records of a permission.

System capability: SystemCapability.Security.AccessToken

UsedRecordDetail

Represents the details of a single access record.

System capability: SystemCapability.Security.AccessToken

PermissionActiveStatus

Enumerates the permission usage statuses.

System capability: SystemCapability.Security.AccessToken

ActiveChangeResponse

Defines the detailed permission usage information.

System capability: SystemCapability.Security.AccessToken

PermissionUsedType¹²⁺

Enumerates the means for using a sensitive permission.

System capability: SystemCapability.Security.AccessToken

|Name |Value|Description | |———————–|–|—————-| |NORMAL_TYPE |0|The sensitive permission is used after authorization through a dialog box or a system settings page.| |PICKER_TYPE |1|The sensitive permission is used through a system picker. This access mode does not grant the permissions to the application.| |SECURITY_COMPONENT_TYPE|2|The sensitive permission is used through a security component, which comes with the authorization.|

PermissionUsedTypeInfo¹²⁺

Represents detailed information about the use of a permission.

System capability: SystemCapability.Security.AccessToken

AddPermissionUsedRecordOptions¹²⁺

Represents the options for adding a permission usage record.

System capability: SystemCapability.Security.AccessToken

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Ability Kit

harmony 鸿蒙AbilityAccessControl

harmony 鸿蒙AbilityBase

harmony 鸿蒙AbilityBase_Element

harmony 鸿蒙AbilityRuntime

harmony 鸿蒙bundle

harmony 鸿蒙OH_NativeBundle_ApplicationInfo

harmony 鸿蒙OH_NativeBundle_ElementName

harmony 鸿蒙ability_access_control.h

harmony 鸿蒙ability_base_common.h