HarmonyOS Distributed File System Development Guide

Mar 13, 2024

Overview of distributed file systems

The HarmonyOS Distributed File System (hmdfs) provides cross-device file access and is suitable for the following scenarios:

● Two devices are networked, users can use the editing software on one device to edit documents on the other device.
● Music saved on the tablet can be directly visible and playable by the car system.
● For photos taken outdoors, go home and open the tablet to directly access the photos taken by the original device.

Based on the dynamic networking of distributed soft bus, HMDFS provides a global and consistent access view for each device node on the network, and supports developers to read and write through the basic file system interface, which has the advantages of high performance and low latency.

Distributed file system architecture

● distributedfile_daemon: Mainly responsible for device online monitoring, establishing links through soft buses, and implementing different data flow policies according to the distributed device security level.

● HMDFS: Implement the network file system in the kernel, including cache management, file access, metadata management, and conflict management.

○ Cache management
■ After the device is distributed, HMDFS provides the ability to access files, but does not actively transfer and copy file data. If the application needs to save the data locally, it needs to actively copy it.

■ hmdfs ensures the consistency of Close-to-Open, that is, after one end writes closes, the other end can read the latest data, and does not ensure the real-time consistency of file content.

■ If the data is written to the remote end but is not flashed back in time due to network reasons, the file system will flash back to the local area the next time the network is connected, but if the remote end has been modified, it cannot be flashed back.

○ File access

■ The file access interface is the same as that of the local one (ohos.file.fs).

■ If the file is local, stack access to the local file system.

■ If the file is on another device, the network will be synchronized to access the file of the remote device.

illustrate

symlink: Not supported.

○ Metadata management
■ Under distributed networking, one end of the file can be created, deleted, and modified, and the other end can view the latest file "immediately", and the speed depends on the network situation.
■ After the remote device goes offline, the data of the remote device will no longer be displayed on the local device. However, due to the delay in the perception of the device being offline, some messages may time out in 4s, so developers need to consider the network timeout of the interface or the scenario where some files can be seen but the actual device may be offline.

○ Conflict handling

■ Local and remote conflicts, the remote file is renamed, the file with the same name is the local file with the same name, and the remote file is renamed.

■ If multiple devices conflict at the remote end, files with the same name with small device IDs will be displayed in the order of accessing the device ID, and other files will be renamed in turn.

■ If there is already a remote file in the directory tree, create a file with the same name to indicate that the file already exists.

■ The ID is added after the _conflict_dev of the conflicting file is displayed, and the ID is automatically incremented from 1.

■ There is no conflict between directories with the same name, files and remote directories have the same name, and the suffix of the remote directory is _remote_directory.

Set the distributed file data level

The security capabilities of different devices vary greatly, and the security capabilities of some small embedded devices are much weaker than those of device types such as tablets. Different files and applications have different security requirements, such as personal health information and bank card information, which are not expected to be read by weak devices. Therefore, HarmonyOS provides a complete set of data classification and device classification standards, and formulates different data transfer policies for different devices.

API description

For more information about the API, see ohos.file.securityLabel.

Table 1 Setting the file data level

The name of the interfacefunctionInterface typeSynchronization is supportedAsynchronous support is supportedsetSecurityLabelSet up file security labelsmethod√√getSecurityLabelGet a file security labelmethod√√

note

For files that don't meet the security level, you can still see the file across devices, but you don't have permission to open and access the file.
The data level of the distributed file system is S3 by default, and the application can actively set the security level of the file.

Development examples

Obtain the common file sandbox path and set the data level label. For details about how to obtain the context in this example, see Obtaining the Context of UIAbility.

import securityLabel from '@ohos.file.securityLabel';

// 获取需要设备数据等级的文件沙箱路径
let context = ...; // 获取UIAbilityContext信息
let pathDir = context.filesDir;
let filePath = pathDir + '/test.txt';

// 设置文件的数据等级为s0
securityLabel.setSecurityLabel(filePath, 's0').then(() => {
  console.info('Succeeded in setSecurityLabeling.');
}).catch((err) => {
  console.error(`Failed to setSecurityLabel. Code: ${err.code}, message: ${err.message}`);
});

Cross-device file access

When installing the same application on multiple devices, developers can read and write files under the distributed file path (/data/storage/el2/distributedfiles/) of other devices through the basic file interface. For example, in the scenario of multi-device data transfer, after the device is networked and interconnected, the application on device A can access the files under the distributed path of device B and the application.

Development steps

Complete distributed networking. First, connect the devices that need cross-device access to the same LAN and authenticate with the same account to complete the networking.
Access cross-device files. To achieve cross-device file access between different devices in the same application, you only need to place the corresponding files in the distributed file path of the application sandbox.

On device A, create a test file in the distributed path and write the content. For details on how to obtain the context in this example, see UIAbility.

import fs from '@ohos.file.fs';

let context = ...; // 获取设备A的UIAbilityContext信息
let pathDir = context.distributedFilesDir;
// 获取分布式目录的文件路径
let filePath = pathDir + '/test.txt';

try {
  // 在分布式目录下创建文件
  let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE | fs.OpenMode.CREATE);
  console.info('Succeeded in createing.');
  // 向文件中写入内容
  fs.writeSync(file.fd, 'content');
  // 关闭文件
  fs.closeSync(file.fd);
} catch (err) {
  console.error(`Failed to openSync / writeSync / closeSync. Code: ${err.code}, message: ${err.message}`);
}

The test file is read under a distributed path on device B.

import fs from '@ohos.file.fs';

let context = ...; // 获取设备B的UIAbilityContext信息
let pathDir = context.distributedFilesDir;
// 获取分布式目录的文件路径
let filePath = pathDir + '/test.txt';

try {
  // 打开分布式目录下的文件
  let file = fs.openSync(filePath, fs.OpenMode.READ_WRITE);
  // 定义接收读取数据的缓存
  let buffer = new ArrayBuffer(4096);
  // 读取文件的内容，返回值是读取到的字节个数
  let num = fs.readSync(file.fd, buffer, {
    offset: 0
  });
  // 打印读取到的文件数据
  console.info('read result: ' + String.fromCharCode.apply(null, new Uint8Array(buffer.slice(0, num))));
} catch (err) {
  console.error(`Failed to openSync / readSync. Code: ${err.code}, message: ${err.message}`);
}

In order to allow you to better learn Harmony OS development technology, here is a special compilation of the "Harmony OS Development Study Manual" (a total of 890 pages), I hope it will be helpful to you: https:// qr21.cn/FV7h05