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.
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
Name | Type | Description |
---|---|---|
options.overwrite (optional) | boolean | If 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.
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.
- 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.
link()
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;
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);
}
});