File System

Note

With the introduction of Tizen version 5.0, the Filesystem API has undergone a major overhaul. Many of the existing methods are deprecated and new methods are introduced. For information on the previous versions of API, see Deprecated Filesystem Guide. This guide explains about the APIs for Tizen 5.0 and its newly introduced methods.

You can access the files and directories in the device file system.

The Filesystem API is mandatory for Tizen Mobile, Wearable, and TV profiles, which means that it is supported on all mobile, wearable, and TV devices. All mandatory APIs are supported on Tizen emulators.

The Filesystem API provides access to accessible parts of the file system, which are represented as virtual root locations.

The main features of the Filesystem API include:

• File storage management You can manage different storages on the device and retrieve additional information about the storages, which includes listing available storages and receiving storage change notifications.
• Files and directory management You can perform basic file and directory management tasks using the File interface:
  • You can create and delete directories in the file system.
  • You can delete files from the virtual file system.
  • You can retrieve a list of files in a directory, the URI of a file, or the file content as a DOMString .
  • You can read or write to a file.
  • You can copy and move files and directories within the virtual file system.

  File and directory access

  You can access the virtual file system using the FileSystemManager interface (in mobile, wearable, and TV applications):

  To access a file or directory within the virtual file system, you can use the fully qualified path, / , where is the name of the virtual root and is the relative path to the file or directory within the root. Alternatively, you can use the absolute path to a file located in the target device memory. Regardless of virtual root usage, rights to access file location as well as rights to read and write to a file are needed when applicable.

  Note When you use a path to access the device file system, ensure that the file path encoding uses the default encoding of the platform.

  Prerequisites

  To use the Filesystem API (in mobile, wearable, and TV applications), the application has to request permission by adding the following privileges to the config.xml file:

  name="http://tizen.org/privilege/filesystem.read"/> name="http://tizen.org/privilege/filesystem.write"/> 

  Manage file storages

  You can manage different storages on the device with the FileSystemManager interface (in mobile, wearable, and TV applications).

  You can retrieve additional information about the storages, including listing available storages and receiving storage change notifications with the listStorages() and addStorageStateChangeListener() methods provided by the FileSystemManager interface.

  To manage file storages:

  To list available storages, use the listStorages() method of the FileSystemManager interface to search for the storages available on the device. If the search is successful, the list of found FileSystemStorage objects (in mobile, wearable, and TV applications) is passed to the success event handler:

  /* Success event handler */ function checkCorruptedRemovableDrives(storages) < for (var i = 0; i < storages.length; i++) < if (storages[i].type != 'EXTERNAL') continue; if (storages[i].state == 'UNMOUNTABLE') console.log('External drive ' + storages[i].label + ' is corrupted.'); > > /* Search for the storages */ tizen.filesystem.listStorages(checkCorruptedRemovableDrives); 

  /* Success event handler */ function onStorage(storage) < console.log('Storage found:' + storage.label); > /* Retrieve a storage */ tizen.filesystem.getStorage('music', onStorage); 

  var watchID; /* Define the event handler */ function onStorageStateChanged(storage) < if (storage.state == 'MOUNTED') console.log('Storage ' + storage.label + ' was added!'); > /* Register the event handler */ watchID = tizen.filesystem.addStorageStateChangeListener(onStorageStateChanged); 

  tizen.filesystem.removeStorageStateChangeListener(watchID); 

  Create and delete directories

  You can create directories using the createDirectory() method. The directory is created at path specified in the parameter. You can delete directories using deleteDirectory() method. Target pointed by the path specified will be deleted from the file system:

  To create a directory within the file system, use the createDirectory() method. The directory is created, in destination pointed by path and successCallback function should be called. If directory can not be created for some reason, the errorCallback is called and an error message can be logged:

  var newPath = 'documents/subDir' var successCallback = function(newPath) < console.log('New directory has been created: ' + newPath); > var errorCallback = function(error) < console.log(error); >tizen.filesystem.createDirectory('documents/newDir',successCallback, errorCallback); 

  var fullPath = 'documents/subDir' var callback = function(modifiedDirectory) < console.log('deleteDirectory() is successfully done. Modified (parent) directory: ' + modifiedDirectory); > var errorCallback = function(error) < console.log(error); > tizen.filesystem.deleteDirectory(fullPath, true, callback, errorCallback); 

  Delete files

  You can create directories using the createDirectory() method. The directory is created at the path specified in the parameter. You can delete files using the deleteFile() method. Target pointed by the path specified will be deleted from the file system.

  To delete a file, use the deleteFile() method:

  var fullPath = 'documents/file_to_be_deleted.txt' var callback = function(modifiedDirectory) < console.log('deleteFile() is successfully done. Modified (parent) directory: ' + modifiedDirectory); > var errorCallback = function(error) < console.log(error); > tizen.filesystem.deleteFile(fullPath, callback, errorCallback); 

  Retrieve files and file details

  You can retrieve a list of files or file URIs using the listDirectory() and toURI() methods. The URI can be used to identify the file, for example, by using it as the src attribute on an HTML img element:

  To retrieve a list of all files and directories located in a specified directory, use the listDirectory() method of the filesystem object. The method returns an array of DOMString elements, each being a path with the name of the file inside a directory pointed by path :

  function onsuccess(files) < for (var i = 0; i < files.length; i++) < /* Display the file path with name */ console.log('File path and name is: ' + files[i]); > > function onerror(error) < console.log(error); > tizen.filesystem.listDirectory('documents/subDir', onsuccess, onerror); 

  function onsuccess(files) < for (var i = 0; i < files.length; i++) < /* Display the file URI */ console.log('File URI is: ' + toURI(files[i])); > > function onerror(error) < console.log(error); >tizen.filesystem.listDirectory('documents/subDir', onsuccess, onerror); 

  Firstly, open a file using the openFile() function with the mode parameter, allowing you to read its contents:

  /* Opening file for read - this code assumes that there is */ /* a file named 'file' in documents directory */ var fileHandleRead = tizen.filesystem.openFile('documents/file', 'r'); console.log('File opened for reading'); 

  var fileContents = fileHandleRead.readString(); console.log('File contents: ' + fileContents); 

  var fileContents = fileHandleRead.readData(); console.log('File binary contents in array:'); console.log(fileContents); 

  var fileContents = fileHandleRead.readBlob(); console.log('Blob object:'); console.log(fileContents); /* FileReader is a W3C API class, not related to webapi-plugins */ /* and is capable of extracting blob contents */ var reader = new FileReader(); /* Event fires after the blob has been read/loaded */ reader.addEventListener('loadend', function(contents) < const text = contents.srcElement.result; console.log('File contents: ' + text); >); /* Start reading the blob as text */ reader.readAsText(fileContentsInBlob); 

  fileHandleRead.close(); 

  Note When you use readString(), readData(), readBlob(), or one of their NonBlocking equivalents, FileHandle position is set right where the reading operation ended. To read the file again from the beginning, use seek() method on FileHandle object.

  Manage files and directories

  You can manage files and directories in many ways:

  • You can read and write to a file by first using the openFile() method to open the file. You can specify the file mode. The openFile() method returns a FileHandle object (in mobile, wearable, and TV applications), which is a handle to the opened file. All actual operations, such as read, write, or close, on the file are performed through the FileHandle object based on a current position, which can be obtained or modified through calling seek() operation on FileHandle object.

  To write to files:

  To open or create a file, use the openFile() method of the FileSystemManager interface (in mobile, wearable, and TV applications). The method returns a FileHandle object, which is a handle to the opened or newly created file.

  Note openFile() method used with mode ‘w’ creates a new file or opens an existing file and erases its contents. Any data contained in a file opened in that mode will be lost.

  Perform all actual operations, such as reading, writing, or closing on the file through the FileHandle object based on a current position, which can be obtained or modified through calling seek() operation on FileHandle object:

  /* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated */ var fileHandleWrite = tizen.filesystem.openFile('documents/file', 'w'); console.log('File opened for writing'); 

  • use writeString() or writeStringNonBlocking() to write DOMString to file:

  var stringToWrite = 'example string'; fileHandleWrite.writeString(stringToWrite); 

  var arrayToWrite = new Uint8Array([11,22,88,99]); fileHandleWrite.writeData(arrayToWrite); 

  var blobToWrite = new Blob(['example blob content']); fileHandleWrite.writeBlob(blobToWrite); 

  fileHandleWrite.close(); 

  You can copy, move and rename files and directories within the file system with the copyFile() , copyDirectory() , moveFile() , moveDirectory() and rename() methods. During copy or move operations, if a file or directory of the same name already exists in the target location, the overwrite input parameter of the method defines whether the existing file is overwritten:

  To copy a file, use the copyFile() method. The following example copies the file to the images directory. Since the third parameter is set to true , any existing file or directory with the same name in the target directory is overwritten:

  var filePathAndName = 'documents/exampleFile.jpg'; var destination = 'images/copyOfExampleFile.jpg'; function onSuccess( ) < console.log('success'); > var errorCallback = function(error) < console.log(error); > tizen.filesystem.copyFile(filePathAndName, destination, true, onSuccess, errorCallback); 

  var directoryPathAndName = 'downloads/exampleDirectory'; var destination = 'documents/copyOfExampleDirectory'; function onSuccess( ) < console.log('success'); > var errorCallback = function(error) < console.log(error); > tizen.filesystem.copyDirectory(directoryPathAndName, destination, true, onSuccess, errorCallback); 

  var filePathAndName = 'downloads/exampleFile.mp3'; var destination = 'music'; function onSuccess( ) < console.log('success'); > var errorCallback = function(error) < console.log(error); > tizen.filesystem.moveFile(filePathAndName, destination, true, onSuccess, errorCallback); 

  var directoryPathAndName = 'documents/exampleDirectory'; var destination = 'camera'; function onSuccess( ) < console.log('success'); > var errorCallback = function(error) < console.log(error); > tizen.filesystem.moveDirectory(directoryPathAndName, destination, true, onSuccess, errorCallback); 

  var filePathAndName = 'documents/exampleFile.txt'; var newName = 'newName.txt'; function onSuccess() < console.log('success'); > var errorCallback = function(error) < console.log(error); >tizen.filesystem.rename(filePathAndName, newName, onSuccess, errorCallback); 

  Supported virtual roots

  The virtual roots form a collection of locations that function as a single virtual device file system. The following table lists the supported virtual roots:

  Table: Filesystem virtual roots

  Virtual root	Description
  camera	Location for storing pictures and videos taken by a device (supported since Tizen 2.3).
  documents	Location for storing documents.
  downloads	Location for storing downloaded items.
  images	Location for storing images.
  music	Location for storing audio files.
  ringtones	Location for ringtones (read-only location). Note The ringtones virtual root is not supported on TV devices.
  videos	Location for storing videos.
  wgt-package	Location for storing web application packages (read-only location).
  wgt-private	Location for the web application private storage.
  wgt-private-tmp	Location for the web application private temporary storage.

  Related information

  • Dependencies
    • Tizen 2.4 and Higher for Mobile
    • Tizen 2.3.1 and Higher for Wearable
    • Tizen 3.0 and Higher for TV

    © 2024 Tizen Project, a Linux Foundation Project. All Rights Reserved. Linux is a registered trademark of Linus Torvalds.
    Tizen is a registered trademark of The Linux Foundation. * Other names and brands may be claimed as the property of others.
    Except as noted, this content is licensed under Creative Commons Attribution 3.0. For details, see the Content License.