Skip to main content
Version: 6.4.2

File System

File System API allows low level manipulation with files and directories in the device internal storage. File System API works with both in internal and external storages (USB flash drives, etc.).

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.

Alternative file caching

All methods

MethodsDescriptionSupported since
listStorageUnits()Return list of storage units /internal, external/ from the device2.1.0
listFiles()Return list of files of existing directory2.1.0
getFile()Returns local uri of existing file2.1.0
exists()Returns true of existing directory or file2.1.0
downloadFile()Download file to path within existing directory or Overrides existing file in path when successfully downloaded2.1.0
deleteFile()Delete file from path within existing directory2.1.0
moveFile()Move file to destination path or Move directory to destination path2.1.0
getFileChecksum()Returns checksum of existing file in path2.1.0
extractFile()Extract ZIPed all files (recursively) to destination path and override existing files or merge existing directories2.1.0
createArchive()Creates archive in selected path5.12.0
createDirectory()Creates directory in path2.1.0
isDirectory()Returns true if existing path is directory2.1.0
copyFile()Copy file or directory to a new location3.3.0
writeFile()Write string to a file3.2.0
appendFile()Write string to a file4.13.0
readFile()Read a text file3.3.0

listStorageUnits()

Return list of storage units /internal, external/ from the device. Capacity values are in bytes.

info

This is a mandatory method that is required for all the other File System APIs. The other APIs require a storageUnit object that is retrieved from this method to manipulate with files on a correct storage location (internal/external).

warning

storageUnit is a dynamic object! It has to be always generated and retrieved by this JS API, as the values in type differ platform by platform. Never generate the object manually. {"type":"internal"} is for demonstration only.

Javascript Example

// Storage units are equivalent to disk volumes (C:, D: etc on Windows; /mnt/disc1, /mnt/disc2 on Unix)
const storageUnits = await sos.fileSystem.listStorageUnits();

// Every platform has at least one not removable storage unit (internal storage unit)
const internalStorageUnit = storageUnits.find((storageUnit) => !storageUnit.removable);

console.log(storageUnits);

Returns

[
{
"type":"internal",
"capacity":4124856000, // in bytes
"freeSpace":3764700000, // in bytes
"usableSpace":3764700000, // in bytes
"removable":false
},
{
"type":"external",
"capacity":2224856000, // in bytes
"freeSpace":764700000, // in bytes
"usableSpace":764700000, // in bytes
"removable":true
}
]

listFiles()

List files and folders located in the internal/external storage.

  • SUCCESS: Return list of files of existing directory
  • FAIL: When listing not existing directory
  • FAIL: When listing existing file (not a directory)

Javascript Example

// Storage units are equivalent to disk volumes (C:, D: etc on Windows; /mnt/disc1, /mnt/disc2 on Unix)
const storageUnits = await sos.fileSystem.listStorageUnits();

// Every platform has at least one not removable storage unit (internal storage unit)
const internalStorageUnit = storageUnits.find((storageUnit) => !storageUnit.removable);

// Empty string '' refers to root directory. Here is root directory of internal storage
const rootDirectoryFilePaths = await sos.fileSystem.listFiles({ filePath: '', storageUnit: internalStorageUnit });

console.log(rootDirectoryFilePaths);

// get files from directory 'test-dir'
const testDirDirectoryFilePaths = await sos.fileSystem.listFiles({ filePath: 'test-dir', storageUnit: internalStorageUnit });
console.log(testDirDirectoryFilePaths);

Returns

// there are 2 directories in the internal storage
[
{
"storageUnit":{
"type":"internal",
"capacity":4124856000,
"freeSpace":3336336000,
"usableSpace":3336336000,
"removable":false
},
"filePath":"data"
},
{
"storageUnit":{
"type":"internal",
"capacity":4124856000,
"freeSpace":3336336000,
"usableSpace":3336336000,
"removable":false
},
"filePath":"test-dir"
}
]

// there are 3 files in the 'test-dir' directory
[
{
"storageUnit":{
"type":"internal",
"capacity":4124856000,
"freeSpace":3764696000,
"usableSpace":3764696000,
"removable":false
},
"filePath":"test-dir/downloaded-file.png"
},
{
"storageUnit":{
"type":"internal",
"capacity":4124856000,
"freeSpace":3764696000,
"usableSpace":3764696000,
"removable":false
},
"filePath":"test-dir/log.1.txt"
},
{
"storageUnit":{
"type":"internal",
"capacity":4124856000,
"freeSpace":3764696000,
"usableSpace":3764696000,
"removable":false
},
"filePath":"test-dir/log.1.txt.backup"
}
]

getFile()

Return a file from an internal storage

  • OK: Returns local uri of existing file
  • OK: Returns NULL of not existing file

Parameters

ParamTypeRequiredDescription
filePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory

Javascript Example

// always pass storageUnit to tell the JS API where to look
// get properties of file (at least localUri) or null when not exist
const fileProperties = await sos.fileSystem.getFile({ storageUnit: internalStorageUnit, filePath: 'test-dir/downloaded-file.png' });

// Complete file details
console.log(fileProperties);

// To access file from HTML applet, use localUri
console.log(fileProperties.localUri);

Returns

warning

Return statement is a dynamic object! It has to be always generated and retrieved by this JS API, as the values in localUri differ platform by platform. Never generate the object manually. {"localUri":"file://internal/test-dir/downloaded-file.png"} is for demonstration only.

{
"localUri": "file://internal/test-dir/downloaded-file.png",
// Other optional properties when supported
"createdAt": "2019-05-03T12:00:00.000Z",
"lastModifiedAt": "2019-05-03T12:00:00.000Z",
"sizeBytes": 2048,
"mimeType": "image/png"
}

exists()

  • OK: Returns true of existing directory or file
  • OK: Returns false of not existing directory nor file

Parameters

ParamTypeRequiredDescription
filePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory

Javascript Example

// always pass storageUnit to tell the JS API where to look
// check if there is such a file
const fileExists = await sos.fileSystem.exists({ storageUnit: internalStorageUnit, filePath: 'test-dir/downloaded-file.png' });

console.log(fileExists);

Returns

Boolean value

downloadFile()

Download file to path within existing directory or overrides existing file in a path when successfully downloaded

  • OK: Download file to path within existing directory
  • OK: Overrides existing file in path when sucessfully downloaded
  • FAIL: When containing (parent) directory of destination path doesn't exist
  • FAIL: When destination path is directory

Parameters

ParamTypeRequiredDescription
filePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
uriString
Yes
Url address to retrieve the file from network
headersObject
No
Key, value pairs of HTTP headers to send along with the request. Used when the target file is protected by a password or if any
danger

For every download request, our app makes HEAD request for content-length header on that downloaded file.

warning

headers has to be a JSON object. If you are passing the value, make sure you use JSON.parse().

Javascript Example

// You can download file to specific existing directory
await sos.fileSystem.downloadFile(
{ storageUnit: internalStorageUnit, filePath: 'test-dir/downloaded-file.png' },
'https://2.signageos.io/assets/android-benq-amy_bbd9afbc0655ceb6da790a80fbd90290.png',
{ 'Authentication-Token': 'MySecretToken' }, // Optionally, you can use headers for download file
);

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

deleteFile()

Delete a file or directory from the path.

  • OK: (not recursive) Deletes an existing file or existing empty directory
  • OK: (recursive) Deletes an existing file or existing (non-empty) directory recursively
  • FAIL: (not recursive) When is deleting directory and is not empty
  • FAIL: (both) When deleting path doesn't exist

Parameters

ParamTypeRequiredDescription
filePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
recursiveboolean
No
TRUE for recursive delete of all content from a directory

Javascript Example

// Delete directory and all files inside
//// First check, if there is such a directory
if (await sos.fileSystem.exists({ storageUnit: internalStorageUnit, filePath: 'test-dir' })) {
// Delete the directory and all it's content recursively
await sos.fileSystem.deleteFile({ storageUnit: internalStorageUnit, filePath: 'test-dir' }, true);
}

// Delete file
//// First check, if there is such a file
if (await sos.fileSystem.exists({ storageUnit: internalStorageUnit, filePath: 'test-dir/downloaded-file.png' })) {
// Delete the file
await sos.fileSystem.deleteFile({ storageUnit: internalStorageUnit, filePath: 'test-dir/downloaded-file.png' }, false);
}

moveFile()

Move file OR directory to destination path or Move directory to destination path.

  • OK: Move file to destination path
  • OK: Move directory to destination path
  • FAIL: When destination path exists (is file or directory)
  • FAIL: When containing (parent) directory of destination path doesn't exist
  • FAIL: When source file (or directory) doesn't exist

Parameters

ParamTypeRequiredDescription
filePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory

Javascript Example

// Move file to a different directory
//// First check, if there is such a file and directory
if (await sos.fileSystem.exists({ storageUnit: internalStorageUnit, filePath: 'test-dir/log.txt' })
&& await sos.fileSystem.exists({ storageUnit: internalStorageUnit, filePath: 'new-dir' }) ) {

await sos.fileSystem.moveFile(
{ storageUnit: internalStorageUnit, filePath: 'test-dir/log.txt' },
{ storageUnit: internalStorageUnit, filePath: 'new-dir/log.txt' },
);
}

getFileChecksum()

Returns checksum of existing file in a path.

  • OK: Returns checksum of existing file in path
  • FAIL: When file path doesn't exist
  • FAIL: When file path is directory
info

Does not work on Samsung Tizen display - read more here

Parameters

ParamTypeRequiredDescription
filePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
hashFunctionstring
Yes
Available function is md5

Javascript Example

const md5Checksum = await sos.fileSystem.getFileChecksum({ storageUnit: internalStorageUnit, filePath: 'test-dir/log.1.txt.backup' }, 'md5');
console.log(md5Checksum);

Returns

"b3c6930b9306b8e35a978d342cf5a01e" // string

extractFile()

Extract ZIPed all files (recursively) to destination path and override existing files or merge existing directories.

  • OK: Extract ZIPed all files (recursively) to destination path
  • OK: Extract ZIPed all files (recursively) to destination path and override existing files or merge existing directories
  • OK: Auto create destination directory path if doesn't exist
  • FAIL: When extracting not existing ZIP archive file
  • FAIL: When extracting try override existing directory with file or existing file with directory
info

The directory/folder you are extracting your ZIP file into has to be created BEFORE you start extracting the ZIP.

Parameters

ParamTypeRequiredDescription
archiveFilePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
destinationFilePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
archiveMethodstring
Yes
Available method is zip

Javascript Example

// Create directory 'test-dir' in a root directory
await sos.fileSystem.createDirectory({ storageUnit: internalStorageUnit, filePath: 'test-dir' });

// Extract ZIP file into the test-extracted directory
await sos.fileSystem.extractFile(
{ storageUnit: internalStorageUnit, filePath: 'test-dir/test.zip' },
{ storageUnit: internalStorageUnit, filePath: 'test-dir/test-extracted' },
'zip',
);

createArchive()

Creates a archive in a path with all files from archiveEntries array.

  • OK: Creates directory in path
  • FAIL: When creating directory over existing file or directory
  • FAIL: When creating directory in not existing containing (parent) directory
warning
  • Never start OR end the filePath with a slash - /. It will cause error 50517
  • It is a good practice to check if file exists - exists() prior creating it
info
  • This function is available only on Tizen devices.
  • All files are added to the archive based on absolute path from root directory.

Parameters

ParamTypeRequiredDescription
archiveFilePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
archiveEntriesFilePath Array
Yes
Object contains storageUnit object returned by listStorageUnits() and array of all files which will be archived into newly created archive
// Create archive 'test.zip' in a root directory with selected files
await sos.fileSystem.createArchive(
{ storageUnit: internalStorageUnit, filePath: 'test.zip' },
[
{ storageUnit: internalStorageUnit, filePath: 'test-dir/log.txt' },
{ storageUnit: internalStorageUnit, filePath: 'test-dir/log.1.txt' },
],
);

// Example with listFiles() function if you want to archive all files from directory
const filesToArchive = await sos.fileSystem.listFiles({ storageUnit: internalStorageUnit, filePath: 'test-dir' });
await sos.fileSystem.createArchive(
{ storageUnit: internalStorageUnit, filePath: 'test.zip' },
filesToArchive,
);

createDirectory()

Creates a directory in a path.

  • OK: Creates directory in path
  • FAIL: When creating directory over existing file or directory
  • FAIL: When creating directory in not existing containing (parent) directory
warning
  • Never start OR end the filePath with a slash - /. It will cause error 50512
  • It is a good practice to check if directory exists - isDirectory() prior creating it

Parameters

ParamTypeRequiredDescription
filePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory

Javascript Example

// Create directory 'test-dir' in a root directory
await sos.fileSystem.createDirectory({ storageUnit: internalStorageUnit, filePath: 'test-dir' });
// Create multiple directories
const myDirs = [
'dir1',
'dir2',
'dir1/dir3',
];
await Promise.all(myDirs.map(async (dirname) => {
const fp = { storageUnit: internalStorageUnit, filePath: `uploads/${dirname}` };
if (!await sos.fileSystem.exists(fp)) {
await sos.fileSystem.createDirectory(fp);
}
});
// All dirs created

isDirectory()

Returns true if existing path is directory.

  • OK: Returns true if existing path is directory
  • OK: Returns false if existing path is file
  • FAIL: When path doesn't exist

Parameters

ParamTypeRequiredDescription
filePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory

Javascript Example

await sos.fileSystem.isDirectory({ storageUnit: internalStorageUnit, filePath: 'test-dir' });

copyFile()

Copy file OR directory to a new location.

Parameters

ParamTypeRequiredDescription
sourceFilePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
destinationFilePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory

Javascript Example

await sos.fileSystem.copyFile(
{ storageUnit: internalStorageUnit, filePath: 'test-dir/log.1.txt' },
{ storageUnit: internalStorageUnit, filePath: 'destination-dir/log.1.txt.backup' },
);

writeFile()

Write into file directly:

  • string support only
  • override only
  • no append

Parameters

ParamTypeRequiredDescription
filePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
contentString
Yes
Parsed content as string

Javascript Example

await sos.fileSystem.writeFile(
{ storageUnit: internalStorageUnit, filePath: 'test-dir/log.txt' },
'My awesome log line\n',
);

appendFile()

Append content into file directly:

  • string support only
  • append only

Parameters

ParamTypeRequiredDescription
filePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
contentString
Yes
Parsed content as string

Javascript Example

await sos.fileSystem.appendFile(
{ storageUnit: internalStorageUnit, filePath: 'test-dir/log.txt' },
'My awesome log line\n',
);

readFile()

Read a text file.

Parameters

ParamTypeRequiredDescription
filePathFilePath
Yes
Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory

Javascript Example

// Written file can be read (coming soon)
const logFileContent = await sos.fileSystem.readFile({ storageUnit: internalStorageUnit, filePath: 'test-dir/log.txt' });

Returns

"content of your text file" // string

Errors

Although we are doing our best, following errors may occur when working with the file system.

CodeTypeMessage
50501InternalFileSystemErrorUnexpected error occurred when listing storage units.
50502InternalFileSystemErrorUnexpected error occurred when listing files.
50503InternalFileSystemErrorUnexpected error occurred when checking for file existence.
50504InternalFileSystemErrorUnexpected error occurred when getting a file.
50505InternalFileSystemErrorUnexpected error occurred when writing a file.
50506InternalFileSystemErrorUnexpected error occurred when copying a file.
50507InternalFileSystemErrorUnexpected error occurred when moving a file.
50508InternalFileSystemErrorUnexpected error occurred when deleting a file.
50509InternalFileSystemErrorUnexpected error occurred when downloading a file.
50510InternalFileSystemErrorUnexpected error occurred when extracting a file.
50511InternalFileSystemErrorUnexpected error occurred when getting file checksum.
50512InternalFileSystemErrorUnexpected error occurred when creating directory.
50513InternalFileSystemErrorUnexpected error occurred when checking if a path is directory.
50514InternalFileSystemErrorUnexpected error occurred when reading a file.
50515InternalFileSystemErrorUnexpected error occurred when creating a link.
50516InternalFileSystemErrorLink is not supported on this platform.
50518InternalFileSystemErrorUnexpected error occurred when creating a archive file.