目录

EnterpriseDataGuard

The file_guard service allows mobile device management (MDM) apps to identify enterprise key information asset (KIA) files and prevent their unauthorized outflow, ensuring enterprise-level data security. The service provides functions including scanning all directories for files, identifying KIA files, and preventing these files from being transmitted over the network to untrusted segments.

This service is available only for MDM apps that have obtained the service permission.

Start version: 4.0.0(10)

Module Import

import { fileGuard } from '@kit.EnterpriseDataGuardKit';

CommonDirScanType

Enumerates types of common directories that can be scanned.

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Enumeration

Value

Description

MEDIA_ONLY

0

Media library directory.

MEDIA_AND_SANDBOX

1

Media library directory and sandbox directory.

SecurityLevel

Enumerates file security levels.

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Enumeration

Value

Description

EXTERNAL

0

Public.

INTERNAL

1

Internal.

SECRET

2

Secret.

CONFIDENTIAL

3

Confidential.

TOP_SECRET

4

Top secret.

FilePathInfo

Defines file path information.

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameter

Type

Read-Only

Optional

Description

absolutePath

string

No

No

Absolute file path.

uri

string

No

No

File URI.

FileTagInfo

Defines file tag information.

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameter

Type

Read-Only

Optional

Description

securityLevel

number

No

No

Security level of a file. For details, please refer to SecurityLevel.

tag

string

No

No

File tag information.

ScanFileCallback

Provides the callback class of the scanning result.

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

[h2]onReceiveFileList

onReceiveFileList(files: Array<string>): void

Defines the callback function of the file directory scanning result.

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

files

Array<string>

Yes

List of absolute paths of files to be scanned.

Example:

let onReceiveFileList: (files: string[]) => void = (files: Array<string>) => {
  files.forEach((value: string, index: number) => {
    console.info(`Succeeded in getting file: ${value}.`);
  })
};

[h2]onTaskCompleted

onTaskCompleted(count: number): void

Callback function triggered when directory scanning is complete.

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

count

number

Yes

Number of scanned files. The value ranges from 1 to 200.

Example:

let onTaskCompleted: (count: number) => void = (count: number) => {
  console.info(`Succeeded in getting count: ${count}.`);
};

FileGuard

Provides APIs for hierarchical file management and control, including scanning file directories, setting file attributes, and delivering file control policies.

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

[h2]constructor

constructor()

Creates a FileGuard object.

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Example:
let guard: fileGuard.FileGuard = new fileGuard.FileGuard();

[h2]startFileScanTask

startFileScanTask(type: CommonDirScanType, callback: ScanFileCallback, batchNum?: number): void

Starts a file scanning task for a common directory.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

type

CommonDirScanType

Yes

Common directory to scan. The options are MEDIA_ONLY and MEDIA_AND_SANDBOX.

callback

ScanFileCallback

Yes

Callback used to return the file list and scanning completion notification.

batchNum

number

No

Number of scanned files returned in a batch. The value ranges from 1 to 200.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let onReceiveFileList: (files: string[]) => void = (files: Array<string>) => {
  files.forEach((value: string, index: number) => {
    console.info(`Succeeded in getting file: ${value}.`);
  })
};
let onCompleteScanTask: (count: number) => void = (count: number) => {
  console.info(`Succeeded in getting count: ${count}.`);
};
let scanFileCallback: fileGuard.ScanFileCallback = {
  onReceiveFileList: onReceiveFileList,
  onTaskCompleted: onCompleteScanTask
};
guard.startFileScanTask(fileGuard.CommonDirScanType.MEDIA_ONLY, scanFileCallback);

[h2]startFileScanTask

startFileScanTask(path: string, callback: ScanFileCallback, batchNum?: number): void

Starts a file scanning task for a specified directory under the common directory.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

path

string

Yes

Subset of directories in the default path range.

callback

ScanFileCallback

Yes

Callback used to return the file list and scanning completion notification.

batchNum

number

No

Number of scanned files returned in a batch. The value ranges from 1 to 200.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let path: string = '/data/service/el2/test';
let onReceiveFileList: (files: string[]) => void = (files: Array<string>) => {
  files.forEach((value: string, index: number) => {
    console.info(`Succeeded in getting file: ${value}.`);
  })
};
let onCompleteScanTask: (count: number) => void = (count: number) => {
  console.info(`Succeeded in getting count: ${count}.`);
};
let scanFileCallback: fileGuard.ScanFileCallback = {
  onReceiveFileList: onReceiveFileList,
  onTaskCompleted: onCompleteScanTask
};
guard.startFileScanTask(path, scanFileCallback);

[h2]openFile

openFile(path: string, callback: AsyncCallback<number>): void

Opens a file. This API returns the result asynchronously through a callback.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

path

string

Yes

Subset of absolute paths in the default path range.

callback

AsyncCallback<number>

Yes

Callback function. If the operation is successful, err is undefined and data is the obtained file descriptor (FD); otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:
import { BusinessError } from '@kit.BasicServicesKit';

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let path: string = '/data/service/el2/test/test.txt';
guard.openFile(path, (err: BusinessError, fd: number) => {
  if (err) {
    console.error(`Failed to open file. Code: ${err.code}, message: ${err.message}.`);
    return;
  }
  console.info(`Succeeded in opening file. path: ${path}, fd: ${fd}.`);
});

[h2]openFile

openFile(path: string): Promise<number>

Opens a file. This API returns the result asynchronously through a promise.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

path

string

Yes

Subset of absolute paths in the default path range.

Returns:

Type

Description

Promise<number>

Promise used to return the FD of the file opened.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

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

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let path: string = '/data/service/el2/test/test.txt';
guard.openFile(path).then((fd: number) => {
  console.info(`Succeeded in opening file. path: ${path}, fd: ${fd}.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to open file. Code: ${err.code}, message: ${err.message}.`);
});

[h2]setFileTag

setFileTag(path: string, level: SecurityLevel, tag: string, callback: AsyncCallback<void>): void

Sets file tags. This API returns the result asynchronously through a callback.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

path

string

Yes

Subset of absolute paths in the default path range.

level

SecurityLevel

Yes

File security level. The options are EXTERNAL, INTERNAL, SECRET, CONFIDENTIAL, and TOP SECRET.

tag

string

Yes

File tag, which cannot exceed 65536 bytes.

callback

AsyncCallback<void>

Yes

Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

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

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let path: string = '/data/service/el2/test/test.txt';
let tag: string = 'test';
guard.setFileTag(path, fileGuard.SecurityLevel.EXTERNAL, tag, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to set file tag. Code: ${err.code}, message: ${err.message}.`);
    return;
  }
  console.info(`Succeeded in setting file tag.`);
});

[h2]setFileTag

setFileTag(path: string, level: SecurityLevel, tag: string): Promise<void>

Sets file tags. This API returns the result asynchronously through a promise.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

path

string

Yes

Subset of absolute paths in the default path range.

level

SecurityLevel

Yes

File security level. The options are EXTERNAL, INTERNAL, SECRET, CONFIDENTIAL, and TOP SECRET.

tag

string

Yes

File tag, which cannot exceed 65536 bytes.

Returns:

Type

Description

Promise<void>

Promise object. No result is returned.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

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

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let path: string = '/data/service/el2/test/test.txt';
let tag: string = 'test';
guard.setFileTag(path, fileGuard.SecurityLevel.EXTERNAL, tag).then(() => {
  console.info(`Succeeded in setting file tag.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to set file tag. Code: ${err.code}, message: ${err.message}.`);
});

[h2]queryFileTag

queryFileTag(path: string, callback: AsyncCallback<FileTagInfo>): void

Obtains the file tags. This API returns the result asynchronously through a callback.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

path

string

Yes

Subset of absolute paths in the default path range.

callback

AsyncCallback<FileTagInfo>

Yes

Callback used to return the file tag information object.

If the operation is successful, err is undefined and data is the obtained FileTagInfo object; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

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

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let path: string = '/data/service/el2/test/test.txt';
guard.queryFileTag(path, (err: BusinessError, data: fileGuard.FileTagInfo) => {
  if (err) {
    console.error(`Failed to query file tag. Code: ${err.code}, message: ${err.message}.`);
    return;
  }
  console.info(`Succeeded in querying file tag.`);
});

[h2]queryFileTag

queryFileTag(path: string): Promise<FileTagInfo>

Obtains the file tags. This API returns the result asynchronously through a promise.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

path

string

Yes

Subset of absolute paths in the default path range.

Returns:

Type

Description

Promise<FileTagInfo>

Promise used to return the file tag information object.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

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

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let path: string = '/data/service/el2/test/test.txt';
guard.queryFileTag(path).then((data: fileGuard.FileTagInfo) => {
  console.info(`Succeeded in querying file tag.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to query file tag. Code: ${err.code}, message: ${err.message}.`);
});

[h2]getFileUri

getFileUri(path: string, callback: AsyncCallback<FilePathInfo>): void

Obtains the URI of a file. This API returns the result asynchronously through a callback.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

path

string

Yes

Subset of absolute paths in the personal directory of a user.

callback

AsyncCallback<FilePathInfo>

Yes

Callback function. If the operation is successful, err is undefined and data is the FilePathInfo obtained; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

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

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let path: string = '/data/service/el2/100/hmdfs/account/files/test/test.txt';
guard.getFileUri(path, (err: BusinessError, data: fileGuard.FilePathInfo) => {
  if (err) {
    console.error(`Failed to get file uri. Code: ${err.code}, message: ${err.message}.`);
  }else{
    console.info(`Succeeded in getting file uri.`);
  }
});

[h2]getFileUri

getFileUri(path: string): Promise<FilePathInfo>

Obtains the URI of a file. This API returns the result asynchronously through a promise.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

path

string

Yes

Subset of absolute paths in the personal directory of a user.

Returns:

Type

Description

Promise<FilePathInfo>

Promise used to return the absolute path and URI of a file.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

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

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let path: string = '/data/service/el2/100/hmdfs/account/files/test/test.txt';
guard.getFileUri(path).then((data: fileGuard.FilePathInfo) => {
  console.info(`Succeeded in getting file uri.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to get file uri. Code: ${err.code}, message: ${err.message}.`);
});

[h2]deleteFile

deleteFile(path: string, callback: AsyncCallback<void>): void

Deletes files in a specified directory. This API returns the result asynchronously through a callback.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

path

string

Yes

Subset of absolute paths in the personal directory of a user.

callback

AsyncCallback<void>

Yes

Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

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

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let path: string = '/data/service/el2/100/hmdfs/account/files/Docs/Documents/test.txt';
guard.deleteFile(path, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to delete file. Code: ${err.code}, message: ${err.message}.`);
  }else{
    console.info(`Succeeded in deleting file.`);
  }
});

[h2]deleteFile

deleteFile(path: string): Promise<void>

Deletes files in a specified directory. This API returns the result asynchronously through a promise.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

path

string

Yes

Subset of absolute paths in the personal directory of a user.

Returns:

Type

Description

Promise<void>

Promise object. No result is returned.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

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

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let path: string = '/data/service/el2/100/hmdfs/account/files/Docs/Documents/test.txt';
guard.deleteFile(path).then(() => {
  console.info(`Succeeded in deleting file.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to delete file. Code: ${err.code}, message: ${err.message}.`);
});

[h2]updatePolicy

updatePolicy(policy: string, callback: AsyncCallback<void>): void

Updates the security control policy. This API returns the result asynchronously through a callback.

Required permission: ohos.permission.SET_FILE_GUARD_POLICY

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

policy

string

Yes

Security control policy.

Fields in the policy are described as follows:

net_intercept_toggle: indicates whether to block unauthorized transfers. The options are 0 (no) and 1 (yes). The default value is 0.

boundary: list of public network segments.

netsegment_trustlist: list of trusted network segments.

netsegment_blocklist:: list of untrusted network segments.

default_policy: default network segment policy (for network segments other than trusted and untrusted network segments in the public network). The options are 0 (block) and 1 (not block). The default value is 0.

callback

AsyncCallback<void>

Yes

Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

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

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let policy: string = '{' +
  '"net_intercept_toggle":0,' +
  '"boundary":["10.10.0.0-10.10.255.255.255","0.0.0.0-1.1.1.1"],' +
  '"netsegment_trustlist":["10.10.0.0-10.10.255.255.255"],' +
  '"netsegment_blocklist":["0.0.0.0-1.1.1.1"],' +
  '"default_policy":0' +
  '}';
guard.updatePolicy(policy, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to update policy. Code: ${err.code}, message: ${err.message}.`);
  } else {
    console.info(`Succeeded in updating policy.`);
  }
});

[h2]updatePolicy

updatePolicy(policy: string): Promise<void>

Updates the security control policy. This API returns the result asynchronously through a promise.

Required permission: ohos.permission.SET_FILE_GUARD_POLICY

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

policy

string

Yes

Security control policy.

Fields in the policy are described as follows:

net_intercept_toggle: indicates whether to block unauthorized transfers. The options are 0 (no) and 1 (yes). The default value is 0.

boundary: list of public network segments.

netsegment_trustlist: list of trusted network segments.

netsegment_blocklist:: list of untrusted network segments.

default_policy: default network segment policy (for network segments other than trusted and untrusted network segments in the public network). The options are 0 (block) and 1 (not block). The default value is 0.

Returns:

Type

Description

Promise<void>

Promise object. No result is returned.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

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

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let policy: string = '{' +
  '"net_intercept_toggle":0,' +
  '"boundary":["10.10.0.0-10.10.255.255.255","0.0.0.0-1.1.1.1"],' +
  '"netsegment_trustlist":["10.10.0.0-10.10.255.255.255"],' +
  '"netsegment_blocklist":["0.0.0.0-1.1.1.1"],' +
  '"default_policy":0' +
  '}';
guard.updatePolicy(policy).then(() => {
  console.info(`Succeeded in updating policy.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to update policy. Code: ${err.code}, message: ${err.message}.`);
});

[h2]setKiaFilelist

setKiaFilelist(filelist: string, callback: AsyncCallback<void>): void

Sets the KIA file list. This API returns the result asynchronously through a callback.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

filelist

string

Yes

List of KIA file absolute paths in the default path range.

callback

AsyncCallback<void>

Yes

Callback used to return the result. If the operation is successful, err is undefined; otherwise, err is an error object.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

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

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let fileListStr: string = '{"kia_filelist":["/data/service/el2/100/hmdfs/account/files/Documents/Desktop/aaa.docx","/data/service/el2/100/hmdfs/account/files/Documents/Desktop/bbb.docx"]}';
guard.setKiaFilelist(fileListStr, (err: BusinessError) => {
  if (err) {
    console.error(`Failed to set the list of KIA file. Code: ${err.code}, message: ${err.message}.`);
  } else {
    console.info(`Succeeded in setting the list of KIA file.`);
  }
});

[h2]setKiaFilelist

setKiaFilelist(filelist: string): Promise<void>

Sets the KIA file list. This API returns the result asynchronously through a promise.

Required permission: ohos.permission.FILE_GUARD_MANAGER

System capability: SystemCapability.PCService.FileGuard

Start version: 4.0.0(10)

Parameters:

Parameter

Type

Mandatory

Description

filelist

string

Yes

List of KIA file absolute paths in the default path range.

Returns:

Type

Description

Promise<void>

Promise object. No result is returned.

Error codes:

For details about the error codes, please refer to Universal Error Codes.

Error Code

Error Message

201

Permission denied.

401

The parameter check failed.

Example:

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

let guard: fileGuard.FileGuard = new fileGuard.FileGuard();
let fileListStr: string = '{"kia_filelist":["/data/service/el2/100/hmdfs/account/files/Documents/Desktop/aaa.docx","/data/service/el2/100/hmdfs/account/files/Documents/Desktop/bbb.docx"]}';
guard.setKiaFilelist(fileListStr).then(() => {
  console.info(`Succeeded in setting the list of KIA file.`);
}).catch((err: BusinessError) => {
  console.error(`Failed to set the list of KIA file. Code: ${err.code}, message: ${err.message}.`);
});