Skip to main content
Version: 8.1.0

fileSystem

Learn more about using this API here

The sos.fileSystem API groups together methods for low-level access to the file system. The File System API supports both internal and external storage.

warning

File System directory structure is PERSISTENT and is NOT automatically deleted through Applet Reload power action! Applet Reload only deletes /data directory which is reserved for simplified Offline Cache API. Use deleteFile() to clear the device storage file system.

Methods​

appendFile()​

The writeFile() method appends string content to the file specified by filePath. If the file does exist, it is created. If the directory does not exist, an error is thrown.

appendFile(filePath: IFilePath, contents: string): Promise<void>;

Possible errors​

The method throws an error if the parent directory does not exist or the filePath is a directory.

copyFile()​

The copyFile() method creates a copy of file at sourceFilePath to destinationFilePath.

copyFile(sourceFilePath: IFilePath, destinationFilePath: IFilePath, options?: ICopyFileOptions): Promise<void>;

Params​

NameTypeDescription
options.overwrite (optional)booleanIf not set or set to false, an error will be thrown if destinationFilePath already exists.

Possible errors​

The method throws an error if the source file does not exists or parent of the destination file path does not exists. It also throws if the options.overwrite is not set and the destination file path already exists.

createArchive()​

The createArchive() method creates an arch file at archiveFilePath from archiveEntries files.

warning

This function is available only on Tizen devices.

createArchive(archiveFilePath: IFilePath, archiveEntries: IFilePath[]): Promise<void>;

createDirectory()​

The createDirectory() method create a new directory at specified path.

createDirectory(directoryPath: IFilePath): Promise<void>;

Possible errors​

The method throws an error if the directory already exists or its parent directory does not exist.

deleteFile()​

The deleteFile() method deletes the file specified by filePath. To remove a directory set recursive to true.

deleteFile(filePath: IFilePath, recursive: boolean): Promise<void>;

Possible errors​

The method throws an error if the file does not exists or if recursive is set to false and the file path is a directory.

downloadFile()​

The downloadFile() method download a file from sourceUri and saves it to the specified path. If the file already exists it is overwritten. Optionally, headers for the download request may be specified. A HEAD request is always sent first to get content-length of the downloaded file.

warning
  • For every download request, our app makes HEAD request for content-length header on that downloaded file.
  • Windows platform can download only files smaller then 4GB.

Encoding​

All downloads respect a standard of Encoding with optional compression of files. See Mozilla standard Accept Encoding and Content Encoding.

Download file method is always sending optional following headers:

Accept-Encoding: gzip
Accept-Encoding: compress
Accept-Encoding: deflate
Accept-Encoding: br
Accept-Encoding: identity
Accept-Encoding: *

If the server understands the Encoding standard, it compresses files using gzip algorithm before the files are sent to the client. If so, the response will contain the following headers:

Content-Encoding: gzip
Content-Encoding: compress
Content-Encoding: deflate
Content-Encoding: br

So the data communication is compressed under the hood. The client will automatically decompress data before it's saved to a specified location path. So from JS API point of view, there is no requirement to decompress data by itself.

The standard is supported on all following platforms:

  • WebOS 3+
  • Tizen 2.4+
  • Brightsign
  • Raspberry Pi
  • Windows
downloadFile(filePath: IFilePath, sourceUri: string, headers?: IHeaders): Promise<void>;

Possible errors​

The method throws an error if the network request fails, parent directory does not exist, or the file path is a directory.

exists()​

The exists() method checks whether a file or directory exists.

exists(filePath: IFilePath): Promise<boolean>;

extractFile()​

The decompressFile() method decompresses the file at archiveFilePath into a new file specified by destinationDirectoryPath.

extractFile(archiveFilePath: IFilePath, destinationDirectoryPath: IFilePath, method: string): Promise<void>;

Possible errors​

The method throws an error if the archive file path does not exist, it is not a valid archive file or the destination directory does not exist.

getFile()​

The getFile() method returns runtime information about a file path, such as local url, last modified date or size.

getFile(filePath: IFilePath): Promise<IFile | null>;

getFileChecksum()​

The getChecksumFile() method computes a checksum of the file specified by filePath.

getFileChecksum(filePath: IFilePath, hashType: HashAlgorithm): Promise<string>;

Possible errors​

The method throws an error if the file does not exist or it is a directory.

isDirectory()​

The isDirectory() method checks whether the file path points to a directory.

isDirectory(filePath: IFilePath): Promise<boolean>;

Possible errors​

The method throws an error if the file path does not exist.

The link() method creates a symbolic link to sourceFilePath (existing path) from destinationFilePath (new path).

link(sourceFilePath: IFilePath, destinationFilePath: IFilePath): Promise<void>;

listFiles()​

The listFiles() method lists all files and directories in the specified path (nested files are not included).

listFiles(directoryPath: IFilePath): Promise<IFilePath[]>;

Possible errors​

The method throws an error if the path does not exist or it is a file.

listInternalStorageUnits()​

A shorthand method for listing only the internal storage units (i.e. those with the removable: false). The capacity values are in bytes.

listInternalStorageUnits(): Promise<IStorageUnit[]>;

listStorageUnits()​

The listStorageUnits() method lists all available storage units. All devices always have one internal storage device (with removable: false) and zero or more external devices. The capacity values are in bytes.

listStorageUnits(): Promise<IStorageUnit[]>;

moveFile()​

The moveFile() method moves a file from sourceFilePath to destinationFilePath.

moveFile(sourceFilePath: IFilePath, destinationFilePath: IFilePath, options?: IMoveFileOptions): Promise<void>;

Possible errors​

The method throws an error if the source file does not exists or parent of the destination file path does not exists. It also throws if the options.overwrite is not set and the destination file path already exists.

onStorageUnitsChanged()​

The onStorageUnitsChanged() method sets up a listener, which is called whenever the list of storage units changes.

onStorageUnitsChanged(listener: () => void): void;

readFile()​

The readFile() method returns content of the file specified by filePath. The file has to be a text file, otherwise the content will be mangled.

readFile(filePath: IFilePath): Promise<string>;

Possible errors​

The method throws an error if the file does not exist.

removeAllListeners()​

The removeAllListeners() method removes all listeners, previously added by removeAllListeners()

removeAllListeners(): void;

removeStorageUnitsChangedListener()​

The removeStorageUnitsChangedListener() method removes a listener, previously added by onStorageUnitsChanged()

removeStorageUnitsChangedListener(listener: () => void): void;

wipeout()​

The wipeout() method is used to wipe out all data from the file system, later when action is finished the device is rebooted.

danger
  • Ensure that function is called only once, otherwise it will wipe out the file system again on applet start!
  • This function is clearing internal file system storage, cache storage and cookies. Local storage will not be cleared.
wipeout(): Promise<void>;

writeFile()​

The writeFile() method writes string content to the file specified by filePath. If the file does exist, it is created. If the directory does not exist, an error is thrown.

writeFile(filePath: IFilePath, contents: string): Promise<void>;

Possible errors​

The method throws an error if the parent directory does not exist or the filePath is a directory.

API Example​

import { sos, fpath } from '@signageos/front-applet';
import { IFilePath } from '@signageos/front-applet/es6/FrontApplet/FileSystem/types';

void sos.onReady(async () => {
	const [internal] = await sos.fileSystem.listInternalStorageUnits();

	const root: IFilePath = {
		storageUnit: internal,
		filePath: '', // empty string points to root directory
	};

	// list files in the root directory
	const contents = await sos.fileSystem.listFiles(root);

	// print files from the root directory
	for (const entries of contents) {
		if (await sos.fileSystem.isDirectory(entries)) {
			console.log(`${entries.filePath} (directory)`);
		} else {
			console.log(`${entries.filePath} (file)`);
		}
	}

	// write data into a file
	const writePath = fpath.join(root, 'value.json');
	await sos.fileSystem.writeFile(writePath, JSON.stringify({ data: 'Lorem ipsum dolor sit amet' }));

	// download a file from the internet and play it
	const downloadPath = fpath.join(root, 'video.mp4');
	await sos.fileSystem.downloadFile(
		downloadPath,
		'https://static.signageos.io/assets/test-videos-03_AME/video-test-03_15s_1920x1080_2fe7b039750a134aeac1c0a515710007.mp4',
	);
	const file = await sos.fileSystem.getFile(downloadPath);

	if (file) {
		await sos.video.prepare(file.filePath, 0, 0, 1920, 1080);
		await sos.video.play(file.filePath, 0, 0, 1920, 1080);
	}
});