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.

GitHub Examples

Complete example of the File System API on our Github

Alternative file caching

Offline Cache for media files

All methods

Methods	Description	Supported since
listStorageUnits()	Return list of storage units /internal, external/ from the device	2.1.0
listFiles()	Return list of files of existing directory	2.1.0
getFile()	Returns local uri of existing file	2.1.0
exists()	Returns true of existing directory or file	2.1.0
downloadFile()	Download file to path within existing directory or Overrides existing file in path when successfully downloaded	2.1.0
deleteFile()	Delete file from path within existing directory	2.1.0
moveFile()	Move file to destination path or Move directory to destination path	2.1.0
getFileChecksum()	Returns checksum of existing file in path	2.1.0
extractFile()	Extract ZIPed all files (recursively) to destination path and override existing files or merge existing directories	2.1.0
createArchive()	Creates archive in selected path	5.12.0
createDirectory()	Creates directory in path	2.1.0
isDirectory()	Returns true if existing path is directory	2.1.0
copyFile()	Copy file or directory to a new location	3.3.0
writeFile()	Write string to a file	3.2.0
appendFile()	Write string to a file	4.13.0
readFile()	Read a text file	3.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

Param	Type	Required	Description
filePath	FilePath	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

Param	Type	Required	Description
filePath	FilePath	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

Param	Type	Required	Description
filePath	FilePath	Yes	Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
uri	String	Yes	Url address to retrieve the file from network
headers	Object	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().
• Windows platform can download only files smaller then 4GB.

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

Param	Type	Required	Description
filePath	FilePath	Yes	Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
recursive	boolean	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

Param	Type	Required	Description
filePath	FilePath	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

Param	Type	Required	Description
filePath	FilePath	Yes	Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
hashFunction	string	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

Param	Type	Required	Description
archiveFilePath	FilePath	Yes	Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
destinationFilePath	FilePath	Yes	Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
archiveMethod	string	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

Param	Type	Required	Description
archiveFilePath	FilePath	Yes	Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
archiveEntries	FilePath 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

Param	Type	Required	Description
filePath	FilePath	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

Param	Type	Required	Description
filePath	FilePath	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

Param	Type	Required	Description
sourceFilePath	FilePath	Yes	Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
destinationFilePath	FilePath	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

Param	Type	Required	Description
filePath	FilePath	Yes	Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
content	String	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

Param	Type	Required	Description
filePath	FilePath	Yes	Object contains storageUnit object returned by listStorageUnits() and filePath if the file or directory
content	String	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

Param	Type	Required	Description
filePath	FilePath	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.

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