Filesystem: Providing Access to the Device File System

This tutorial demonstrates how you can control files and directories on the device.

The Filesystem API is mandatory for both Tizen mobile and wearable profiles, which means that it is supported in all mobile and wearable devices. All mandatory APIs are supported on the Tizen Emulators.

Warm-up

Become familiar with the Filesystem API basics by learning about:

Managing File Storages
Retrieve file storages and storage details, and subscribe to notifications on storage state changes.
Creating and Deleting Files and Directories
Create and delete files and directories in the file system.
Retrieving Files and File Details
Retrieve a list of files in a directory, the URI of the file, or the file content as a DOMString.
Managing Files and Directories
Open, read, write, copy, move, and close files and directories.

Task

In the File Manager task, we will walk through how to manage files in your application.

Managing File Storages

Learning how to manage file storages is a basic data management skill:

To list available storages, use the listStorages() method of the FileSystemManager interface (in mobile and wearable applications) to search for the storages available on the device.

If the search is successful, a list of found FileSystemStorage objects (in mobile and wearable 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);

To get storage details based on the storage name (the label attribute), use the getStorage() method.

The success callback receives the FileSystemStorage object containing the storage details as an input parameter.
```
/* Success event handler */
function onStorage(storage) 
{ 
   console.log("Storage found:" + storage.label);
}

/* Retrieve a storage */
tizen.filesystem.getStorage("music", onStorage);
```

To receive notifications on the storage state changes, for example, additions and removals, register an event handler with the addStorageStateChangeListener() method.

An event is generated each time the storage state changes.

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);

To stop receiving the notifications, use the removeStorageStateChangeListener() method:
```
tizen.filesystem.removeStorageStateChangeListener(watchID);
```

Creating and Deleting Files and Directories

Learning how to create and delete files and directories is a basic data management skill:

To create a file in the current directory, use the createFile() method of the File interface (in mobile and wearable applications):

var documentsDir, newFile;
tizen.filesystem.resolve("documents", function(result) 
                         {
                            documentsDir = result;
                            newFile = documentsDir.createFile("newFilePath");
                         });

To create a directory within the file system, use the createDirectory() method.

The directory (and any sub-directories defined in the method parameter) is created relative to the current directory where the operation is performed on.
```
var newDir = documentsDir.createDirectory("newDir");
var anotherNewDir = documentsDir.createDirectory("newDir1/subNewDir1");
```

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

function onDelete()
{
   console.log("deletedFile() is successfully done.");
}

documentsDir.deleteFile(newFile.fullPath, onDelete);

To delete a directory, use the deleteDirectory() method.

The second parameter defines whether the deletion is performed recursively for the sub-directories as well. If the parameter is set to false, the directory is deleted only if it is empty.
```
documentsDir.deleteDirectory(newDir.fullPath, false, onDelete);
anotherNewDir.parent.deleteDirectory(anotherNewDir.fullPath, false, onDelete);
```

Retrieving Files and File Details

Learning how to get files and file details from the file system is a basic data management skill:

To access a specific file or directory within the file system, retrieve a file handle using the resolve() method of the FileSystemManager interface (in mobile and wearable applications):
```
tizen.filesystem.resolve('documents', onResolveSuccess, null, 'r');
```
The File object (in mobile and wearable applications) is returned in the success event handler.
To retrieve a list of all the files and their directories located in a specified directory, use the listFiles() method of the File object:
```
function onResolveSuccess(dir)
{  
   dir.listFiles(onsuccess);
}
```
The method returns an array of File objects.

To retrieve the file URI, use the toURI() method:

function onsuccess(files) 
{ 
   for (var i = 0; i < files.length; i++) 
   {
      /* Display the file name and URI */
      console.log("File name is " + files[i].name + ", URI is " + files[i].toURI());

To retrieve the file content as a DOMString, use the readAsText() method.

The encoding input parameter of the method defines the format in which the file content is returned.

      if (files[i].isDirectory == false) 
         files[i].readAsText(function(str) {console.log("File content: " + str);}, null, "UTF-8");
   }
}

Managing Files and Directories

Learning how to read and write to files, and move and copy files and directories, is a basic data management skill:

To open a file, use the openStream() method of the File interface (in mobile and wearable applications).

The method returns a FileStream object (in mobile and wearable applications), which is a handle to the opened file.

var documentsDir;

tizen.filesystem.resolve("documents", function(result) 
                         {
                            documentsDir = result;
                         });

var testFile = documentsDir.createFile("test.txt");
if (testFile != null) 
{
   testFile.openStream("w", onOpenSuccess, null, "UTF-8");
}

Perform all actual operations, such as reading, writing, or closing, on the file through the FileStream object based on a position attribute, which represents the current position in the file:

function onOpenSuccess(fs)
{
   /* Write HelloWorld to the file */
   fs.write("HelloWorld");

   /* Read the file content */
   fs.read(testFile.fileSize);

   /* Close the file */
   fs.close();
}

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

var files; /* Assume that this is an array of File objects */
function onSuccess()
{
   console.log("success");
}

for (var i = 0; i < files.length; i++) 
{
   documentsDir.copyTo(files[i].fullPath, "images/backup/"+files[i].name,
                       true, onSuccess);
}

To move a file or directory, use the moveTo() method. The following example moves the files to the images/newFolder/ directory. Since the third parameter is set to false, no existing files with the same name in the target directory are overwritten.

var files; /* Assume that this is an array of File objects */

for (var i = 0; i < files.length; i++) 
{
   documentsDir.moveTo(files[i].fullPath, "images/newFolder/"+files[i].name,
                       false, onSuccess);
}