Version: Next

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.

File System

All methods​

listStorageUnits()​

Javascript Example​

Returns​

listFiles()​

Javascript Example​

Returns​

getFile()​

Parameters​

Javascript Example​

Returns​

exists()​

Parameters​

Javascript Example​

Returns​

downloadFile()​

Parameters​

Javascript Example​

Encoding​

deleteFile()​

Parameters​

Javascript Example​

moveFile()​

Parameters​

Javascript Example​

getFileChecksum()​

Parameters​

Javascript Example​

Returns​

extractFile()​

Parameters​

Javascript Example​

createArchive()​

Parameters​

createDirectory()​

Parameters​

Javascript Example​

isDirectory()​

Parameters​

Javascript Example​

copyFile()​

Parameters​

Javascript Example​

writeFile()​

Parameters​

Javascript Example​

appendFile()​

Parameters​

Javascript Example​

readFile()​

Parameters​

Javascript Example​

Returns​

Errors​

All methods

listStorageUnits()

Javascript Example

Returns

listFiles()

Javascript Example

Returns

getFile()

Parameters

Javascript Example

Returns

exists()

Parameters

Javascript Example

Returns

downloadFile()

Parameters

Javascript Example

Encoding

deleteFile()

Parameters

Javascript Example

moveFile()

Parameters

Javascript Example

getFileChecksum()

Parameters

Javascript Example

Returns

extractFile()

Parameters

Javascript Example

createArchive()

Parameters

createDirectory()

Parameters

Javascript Example

isDirectory()

Parameters

Javascript Example

copyFile()

Parameters

Javascript Example

writeFile()

Parameters

Javascript Example

appendFile()

Parameters

Javascript Example

readFile()

Parameters

Javascript Example

Returns

Errors