@ohos.dlpPermission (DLP)

Data loss prevention (DLP) is a system solution provided to prevent data disclosure. The dlpPermission module provides APIs for cross-device file access management, encrypted storage, and access authorization.

NOTE

The initial APIs of this module are supported since API version 10. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import dlpPermission from '@ohos.dlpPermission';

dlpPermission.isDLPFile

isDLPFile(fd: number): Promise<boolean>

Checks whether a file is a DLP file based on the file descriptor (FD). This API uses a promise to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import fs from '@ohos.file.fs';
import { BusinessError } from '@ohos.base';

let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp";
let file = fs.openSync(uri);

try {
  let res = dlpPermission.isDLPFile(file.fd);  // Check whether the file is a DLP file.
  console.info('res', res);
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}
fs.closeSync(file);

dlpPermission.isDLPFile

isDLPFile(fd: number, callback: AsyncCallback<boolean>): void

Checks whether a file is a DLP file based on the FD. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import fs from '@ohos.file.fs';
import { BusinessError } from '@ohos.base';

let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp";
let file = fs.openSync(uri);

try {
  dlpPermission.isDLPFile(file.fd, (err, res) => {
    if (err != undefined) {
      console.error('isDLPFile error,', err.code, err.message);
    } else {
      console.info('res', res);
    }
    fs.closeSync(file);
  });
} catch (err) {
  console.error('isDLPFile error,', (err as BusinessError).code, (err as BusinessError).message);
  fs.closeSync(file);
}

dlpPermission.getDLPPermissionInfo

getDLPPermissionInfo(): Promise<DLPPermissionInfo>

Obtains the permission information of this DLP file. This API uses a promise to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  dlpPermission.isInSandbox().then((inSandbox) => {// Check whether the application is running in a sandbox.
    if (inSandbox) {
      let res: Promise<dlpPermission.DLPPermissionInfo> = dlpPermission.getDLPPermissionInfo(); // Obtain the permission information.
      console.info('res', JSON.stringify(res));
    }
  });
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

dlpPermission.getDLPPermissionInfo

getDLPPermissionInfo(callback: AsyncCallback<DLPPermissionInfo>): void

Obtains the permission information of this DLP file. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import fs from '@ohos.file.fs';
import { BusinessError } from '@ohos.base';

try {
  dlpPermission.isInSandbox().then((inSandbox) => {// Check whether the application is running in a sandbox.
    if (inSandbox) {
      dlpPermission.getDLPPermissionInfo((err, res) => {
        if (err != undefined) {
          console.error('getDLPPermissionInfo error,', err.code, err.message);
        } else {
          console.info('res', JSON.stringify(res));
        }
      }); // Obtain the permission information.
    }
  });
} catch (err) {
  console.error('getDLPPermissionInfo error,', (err as BusinessError).code, (err as BusinessError).message);
}

dlpPermission.getOriginalFileName

getOriginalFileName(fileName: string): string

Obtains the original file name of a DLP file. This API returns the result synchronously.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  let res = dlpPermission.getOriginalFileName('test.txt.dlp'); // Obtain the original file name.
  console.info('res', res);
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

dlpPermission.getDLPSuffix

getDLPSuffix(): string

Obtains the DLP file name extension. This API returns the result synchronously.

System capability: SystemCapability.Security.DataLossPrevention

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  let res = dlpPermission.getDLPSuffix(); // Obtain the DLP file name extension.
  console.info('res', res);
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

dlpPermission.on('openDLPFile')

on(type: 'openDLPFile', listener: Callback<AccessedDLPFileInfo>): void

Subscribes to a DLP file open event. The application will be notified when the DLP file is opened.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  dlpPermission.on('openDLPFile', (info: dlpPermission.AccessedDLPFileInfo) => {
    console.info('openDlpFile event', info.uri, info.lastOpenTime)
  // Subscribe to the DLP file open event.
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

dlpPermission.off('openDLPFile')

off(type: 'openDLPFile', listener?: Callback<AccessedDLPFileInfo>): void

Unsubscribes from the DLP file open event. The application will not be notified when a DLP file is opened.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  dlpPermission.off('openDLPFile', (info: dlpPermission.AccessedDLPFileInfo) => {
    console.info('openDlpFile event', info.uri, info.lastOpenTime)
  // Unsubscribe from the DLP file open events.
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

dlpPermission.isInSandbox

isInSandbox(): Promise<boolean>

Checks whether this application is running in a DLP sandbox environment. This API uses a promise to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  let inSandbox = dlpPermission.isInSandbox(); // Check whether the application is running in a sandbox.
  console.info('res', inSandbox);
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

dlpPermission.isInSandbox

isInSandbox(callback: AsyncCallback<boolean>): void

Checks whether this application is running in a DLP sandbox environment. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  dlpPermission.isInSandbox((err, data) => {
    if (err) {
      console.error('isInSandbox error,', err.code, err.message);
    } else {
      console.info('isInSandbox, data', JSON.stringify(data));
    }
  }); // Check whether the application is running in the sandbox.
} catch (err) {
  console.error('isInSandbox error,', (err as BusinessError).code, (err as BusinessError).message);
}

dlpPermission.getDLPSupportedFileTypes

getDLPSupportedFileTypes(): Promise<Array<string>>

Obtains the file name extension types that support DLP. This API uses a promise to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  let res = dlpPermission.getDLPSupportedFileTypes(); // Obtain the file types that support DLP.
  console.info('res', JSON.stringify(res));
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

dlpPermission.getDLPSupportedFileTypes

getDLPSupportedFileTypes(callback: AsyncCallback<Array<string>>): void

Obtains the file name extension types that support DLP. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  dlpPermission.getDLPSupportedFileTypes((err, res) => {
    if (err != undefined) {
      console.error('getDLPSupportedFileTypes error,', err.code, err.message);
    } else {
      console.info('res', JSON.stringify(res));
    }
  }); // Obtain the file types that support DLP.
} catch (err) {
  console.error('getDLPSupportedFileTypes error,', (err as BusinessError).code, (err as BusinessError).message);
}

dlpPermission.setRetentionState

setRetentionState(docUris: Array<string>): Promise<void>

Sets the sandbox retention state. This API uses a promise to return the result.

A sandbox application is automatically installed when a DLP file is opened, and automatically uninstalled when the DLP file is closed. Once the sandbox retention state is set for a DLP file, the sandbox application will not be automatically uninstalled when the DLP file is closed.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp";
try {
  dlpPermission.isInSandbox().then((inSandbox) => {// Check whether the application is running in a sandbox.
    if (inSandbox) {
      dlpPermission.setRetentionState([uri]); // Set the retention state for a sandbox application.
    }
  });
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

dlpPermission.setRetentionState

setRetentionState(docUris: Array<string>, callback: AsyncCallback<void>): void

Sets the sandbox retention state. This API uses an asynchronous callback to return the result. A sandbox application is automatically installed when a DLP file is opened, and automatically uninstalled when the DLP file is closed. Once the sandbox retention state is set for a DLP file, the sandbox application will not be automatically uninstalled when the DLP file is closed.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp";
try {
  dlpPermission.setRetentionState([uri], (err, res) => {
    if (err != undefined) {
      console.error('setRetentionState error,', err.code, err.message);
    } else {
      console.info('setRetentionState success');
      console.info('res', JSON.stringify(res));
    }
  }); // Set the sandbox retention state.
} catch (err) {
  console.error('setRetentionState error,', (err as BusinessError).code, (err as BusinessError).message);
}

dlpPermission.cancelRetentionState

cancelRetentionState(docUris: Array<string>): Promise<void>

Cancels the sandbox retention state, that is, allows the sandbox application to be automatically uninstalled when the DLP file is closed. This API uses a promise to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp";
try {
  dlpPermission.cancelRetentionState([uri]); // Cancel the retention state for a sandbox application.
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

dlpPermission.cancelRetentionState

cancelRetentionState(docUris: Array<string>, callback: AsyncCallback<void>): void

Cancels the sandbox retention state, that is, allows the sandbox application to be automatically uninstalled when the DLP file is closed. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

let uri = "file://docs/storage/Users/currentUser/Desktop/test.txt.dlp";
try {
  dlpPermission.cancelRetentionState([uri], (err, res) => {
    if (err != undefined) {
      console.error('cancelRetentionState error,', err.code, err.message);
    } else {
      console.info('cancelRetentionState success');
    }
  }); // Cancel the sandbox retention state.
} catch (err) {
  console.error('cancelRetentionState error,', (err as BusinessError).code, (err as BusinessError).message);
}

dlpPermission.getRetentionSandboxList

getRetentionSandboxList(bundleName?: string): Promise<Array<RetentionSandboxInfo>>

Obtains the sandbox applications in the retention state of an application. This API uses a promise to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  let res: Promise<Array<dlpPermission.RetentionSandboxInfo>> = dlpPermission.getRetentionSandboxList(); // Obtain all the sandbox applications in the retention state.
  console.info('res', JSON.stringify(res))
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

dlpPermission.getRetentionSandboxList

getRetentionSandboxList(bundleName: string, callback: AsyncCallback<Array<RetentionSandboxInfo>>): void

Obtains the sandbox applications in the retention state of an application. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  dlpPermission.getRetentionSandboxList("bundleName", (err, res) => {
    if (err != undefined) {
      console.error('getRetentionSandboxList error,', err.code, err.message);
    } else {
      console.info('res', JSON.stringify(res));
    }
  }); // Obtain the sandbox retention information.
} catch (err) {
  console.error('getRetentionSandboxList error,', (err as BusinessError).code, (err as BusinessError).message);
}

dlpPermission.getRetentionSandboxList

getRetentionSandboxList(callback: AsyncCallback<Array<RetentionSandboxInfo>>): void

Obtains the sandbox applications in the retention state of this application. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  dlpPermission.getRetentionSandboxList((err, res) => {
    if (err != undefined) {
      console.error('getRetentionSandboxList error,', err.code, err.message);
    } else {
      console.info('res', JSON.stringify(res));
    }
  }); // Obtain the sandbox retention information.
} catch (err) {
  console.error('getRetentionSandboxList error,', (err as BusinessError).code, (err as BusinessError).message);
}

dlpPermission.getDLPFileAccessRecords

getDLPFileAccessRecords(): Promise<Array<AccessedDLPFileInfo>>

Obtains the list of DLP files that are accessed recently. This API uses a promise to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  let res: Promise<Array<dlpPermission.AccessedDLPFileInfo>> = dlpPermission.getDLPFileAccessRecords(); // Obtain the list of recently accessed DLP files.
  console.info('res', JSON.stringify(res))
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

dlpPermission.getDLPFileAccessRecords

getDLPFileAccessRecords(callback: AsyncCallback<Array<AccessedDLPFileInfo>>): void

Obtains the list of DLP files that are accessed recently. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  dlpPermission.getDLPFileAccessRecords((err, res) => {
    if (err != undefined) {
      console.error('getDLPFileAccessRecords error,', err.code, err.message);
    } else {
      console.info('res', JSON.stringify(res));
    }
  }); // Obtain the list of recently accessed DLP files.
} catch (err) {
  console.error('getDLPFileAccessRecords error,', (err as BusinessError).code, (err as BusinessError).message);
}

dlpPermission.startDLPManagerForResult¹¹⁺

startDLPManagerForResult(context: common.UIAbilityContext, want: Want): Promise<DLPManagerResult>

Starts the DLP manager application on the current UIAbility page in borderless mode. This API uses a promise to return the result.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import common from '@ohos.app.ability.common';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import UIAbility from '@ohos.app.ability.UIAbility'
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

try {
  let context = getContext () as common.UIAbilityContext; // Obtain the UIAbility context.
  let want: Want = {
    "uri": "file://docs/storage/Users/currentUser/Desktop/1.txt",
    "parameters": {
      "displayName": "1.txt"
    }
  }; // Request parameters.
  dlpPermission.startDLPManagerForResult(context, want).then((res) => {
    console.info('res.resultCode', res.resultCode);
    console.info('res.want', JSON.stringify(res.want));
  }); // Start the DLP manager application.
} catch (err) {
  console.error('error', err.code, err.message); // Error reported if the operation fails.
}

dlpPermission.setSandboxAppConfig¹¹⁺

setSandboxAppConfig(configInfo: string): Promise<void>

Sets sandbox application configuration. This API uses a promise to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Parameters

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  dlpPermission.setSandboxAppConfig('configInfo'); // Set sandbox application configuration.
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

dlpPermission.cleanSandboxAppConfig¹¹⁺

cleanSandboxAppConfig(): Promise<void>

Cleans sandbox application configuration. This API uses a promise to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  dlpPermission.cleanSandboxAppConfig(); // Clean sandbox application configuration.
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

dlpPermission.getSandboxAppConfig¹¹⁺

getSandboxAppConfig(): Promise<string>

Obtains sandbox application configuration. This API uses a promise to return the result.

System capability: SystemCapability.Security.DataLossPrevention

Return value

Error codes

For details about the error codes, see DLP Service Error Codes.

Example

import dlpPermission from '@ohos.dlpPermission';
import { BusinessError } from '@ohos.base';

try {
  dlpPermission.getSandboxAppConfig().then((res) => {
    console.info('res', JSON.stringify(res));
  }); // Obtain the sandbox application configuration.
} catch (err) {
  console.error('error', (err as BusinessError).code, (err as BusinessError).message); // Error reported if the operation fails.
}

ActionFlagType

Enumerates the operations that can be performed on a DLP file. For example, the DLP sandbox application can dim its button based on this parameter.

System capability: SystemCapability.Security.DataLossPrevention

DLPFileAccess

Enumerates the permissions on a DLP file.

System capability: SystemCapability.Security.DataLossPrevention

DLPPermissionInfo

Represents the permission information about a DLP file.

System capability: SystemCapability.Security.DataLossPrevention

AccessedDLPFileInfo

Represents the information about a DLP file opened.

System capability: SystemCapability.Security.DataLossPrevention

DLPManagerResult¹¹⁺

Represents information about the trigger of the DLP manager application.

Model restriction: This API can be used only in the stage model.

System capability: SystemCapability.Security.DataLossPrevention

RetentionSandboxInfo

Represents the sandbox retention information.

System capability: SystemCapability.Security.DataLossPrevention