Filesystem API
The filesystem is represented as an abstract collection of disjointed filesystem virtual root locations, each corresponding to a specific location in the device filesystem. The filesystem API exposes the hierarchies below these root locations as autonomous virtual filesystems.
Each virtual root has a string name. Each file or directory within the virtual filesystem is addressed using a fully-qualified path of the form: <root name>/<path> where <rootname> is the name of the virtual root and <path> is the path to the file or directory relative to that root.
The following virtual roots must be supported:
- images - the location for images
- videos - the location for videos
- music - the location for sounds
- documents - the location for documents
- downloads - the location for downloaded items
- camera - the location for the pictures and videos taken by a device (supported since Tizen 2.3)
- wgt-package - the location for widget package which is read-only
- wgt-private - the location for a widget's private storage
- wgt-private-tmp - the location for a widget's private volatile storage
- removable_... - the location for external storages. The "..." suffix is a unique identifier of an external storage. To obtain list of available external storages use listStorages.
The file URI path is also supported. To access paths out of virtual root, for example "file:///tmp" can be used as location parameter.
The implementation must support the use of the following characters in file names:
- Letters (a-z, A-Z)
- Digits (0-9)
- Blank space
- Underscore ("_")
- Hyphen ("-")
- Period (".")
The implementation may support additional characters in file names, depending on platform support.
The implementation may forbid the use of additional characters in file names, depending on the platform. The use of the path (component) separator "/" and null character "\x00" should not be allowed in file names.
Some other file name and path characteristics are platform-dependent, for example, maximum path length, file name length, case sensitivity, additional character support, etc. Therefore, it is recommended to avoid any dependency on aspects that cannot be supported across multiple platforms.
The encoding used for the file path should be UTF-16 (default for ECMAScript String).
Remark: In order to access files, a proper privilege has to be defined additionally:
- for accessing only internal storage using this API, a privilege http://tizen.org/privilege/mediastorage must be provided,
- for accessing only external storage using this API, a privilege http://tizen.org/privilege/externalstorage must be provided,
- for accessing internal and external storage using this API, privileges (http://tizen.org/privilege/mediastorage and http://tizen.org/privilege/externalstorage) must be provided.
Remark: Methods, which names end with NonBlocking are asynchronous and are executed in background in the order in which they were called. Corresponding methods without NonBlocking at the end are synchronous and will block further instructions execution, until they are finished.
For more information on the Filesystem features, see File System Guide.
Since: 1.0
Table of Contents
- 1. Type Definitions
- 1.1. Path
- 1.2. FileMode
- 1.3. FileSystemStorageType
- 1.4. FileSystemStorageState
- 1.5. Blob
- 1.6. BaseSeekPosition
- 2. Interfaces
- 2.1. FileSystemManagerObject
- 2.2. FileSystemManager
- 2.3. FileSystemStorage
- 2.4. FileHandle
- 2.5. FileFilter
- 2.6. FileSystemStorageArraySuccessCallback
- 2.7. FileSystemStorageSuccessCallback
- 2.8. PathSuccessCallback
- 2.9. SeekSuccessCallback
- 2.10. ReadStringSuccessCallback
- 2.11. WriteStringSuccessCallback
- 2.12. ReadBlobSuccessCallback
- 2.13. ReadDataSuccessCallback
- 2.14. ListDirectorySuccessCallback
- 3. Full WebIDL
Summary of Interfaces and Methods
Interface | Method |
---|---|
FileSystemManagerObject | |
FileSystemManager |
void createDirectory (Path path, optional boolean makeParents, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void deleteFile (Path path, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void deleteDirectory (Path path, optional boolean recursive, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void copyFile (Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void copyDirectory (Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void moveFile (Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void moveDirectory (Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void rename (Path path, DOMString newName, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback)
void listDirectory (Path path, ListDirectorySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional FileFilter? filter)
boolean isDirectory (Path path)
boolean pathExists (Path path)
DOMString getDirName (DOMString path)
void getStorage (DOMString label, FileSystemStorageSuccessCallback onsuccess, optional ErrorCallback? onerror)
void listStorages (FileSystemStorageArraySuccessCallback onsuccess, optional ErrorCallback? onerror)
long addStorageStateChangeListener (FileSystemStorageSuccessCallback onsuccess, optional ErrorCallback? onerror)
void removeStorageStateChangeListener (long watchId)
|
FileSystemStorage | |
FileHandle |
long long seek (long long offset, optional BaseSeekPosition whence)
void seekNonBlocking (long long offset, optional SeekSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional BaseSeekPosition whence)
DOMString readString (optional long long? count, optional DOMString inputEncoding)
void readStringNonBlocking (optional ReadStringSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional long long count, optional DOMString inputEncoding)
long long writeString (DOMString inputString, optional DOMString outputEncoding)
void writeStringNonBlocking (DOMString inputString, optional WriteStringSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional DOMString outputEncoding)
void readBlobNonBlocking (optional ReadBlobSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional long long? size)
void writeBlobNonBlocking (Blob blob, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror)
Uint8Array readData (optional long long size)
void readDataNonBlocking (optional ReadDataSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional long long? size)
void writeData (Uint8Array data)
void writeDataNonBlocking (Uint8Array data, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror)
void flush ()
void sync ()
void close ()
|
FileFilter | |
FileSystemStorageArraySuccessCallback | void onsuccess (FileSystemStorage[] storages) |
FileSystemStorageSuccessCallback | void onsuccess (FileSystemStorage storage) |
PathSuccessCallback | |
SeekSuccessCallback | void onsuccess (long long position) |
ReadStringSuccessCallback | void onsuccess (DOMString string) |
WriteStringSuccessCallback | void onsuccess (long long bytesCount) |
ReadBlobSuccessCallback | |
ReadDataSuccessCallback | void onsuccess (Uint8Array data) |
ListDirectorySuccessCallback |
1. Type Definitions
1.1. Path
typedef DOMString Path;
Since: 5.0
In methods available since Tizen 5.0, checking or accessing files or directories may be granted only through a valid path.
Paths may contain one of the supported virtual roots. The valid path pattern is explained on the top of the page.
1.2. FileMode
enum FileMode { "a", "r", "rw", "rwo", "w" };
Since: 1.0
The file modes defined by this enumerator are:
- a - append access.
- r - read-only access.
- rw - read and write access.
- rwo - read and write access. Original file content are deleted.
- w - write access.
Remark: rwo mode is supported since Tizen 5.0. It will not be recognized by deprecated functions.
1.3. FileSystemStorageType
enum FileSystemStorageType { "INTERNAL", "EXTERNAL" };
Since: 1.0
- INTERNAL - Internal storage is a storage that cannot be removed, such as a flash memory.
- EXTERNAL - External storage is removable storage, such as a USB drive or a memory card.
1.4. FileSystemStorageState
enum FileSystemStorageState { "MOUNTED", "REMOVED", "UNMOUNTABLE" };
Since: 1.0
- MOUNTED - The device is mounted and can be browsed.
- REMOVED - The device has been removed. This states applies only to external drives.
- UNMOUNTABLE - The device cannot be mounted due to an error.
1.5. Blob
typedef Blob Blob;
Since: 5.0
2. Interfaces
2.1. FileSystemManagerObject
[NoInterfaceObject] interface FileSystemManagerObject { readonly attribute FileSystemManager filesystem; };
Tizen implements FileSystemManagerObject;
Since: 1.0
There is a tizen.filesystem object that allows accessing the functionality of the Filesystem API.
Attributes
-
readonly
FileSystemManager filesystemObject representing a filesystem.
Since: 1.0
2.2. FileSystemManager
[NoInterfaceObject] interface FileSystemManager { readonly attribute long maxNameLength; readonly attribute long maxPathLength; FileHandle openFile(Path path, FileMode openMode, optional boolean makeParents) raises(WebAPIException); void createDirectory(Path path, optional boolean makeParents, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void deleteFile(Path path, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void deleteDirectory(Path path, optional boolean recursive, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void copyFile(Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void copyDirectory(Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void moveFile(Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void moveDirectory(Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void rename(Path path, DOMString newName, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void listDirectory(Path path, ListDirectorySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional FileFilter? filter) raises(WebAPIException); DOMString toURI(Path path) raises(WebAPIException); boolean isFile(Path path) raises(WebAPIException); boolean isDirectory(Path path) raises(WebAPIException); boolean pathExists(Path path) raises(WebAPIException); DOMString getDirName(DOMString path); void getStorage(DOMString label, FileSystemStorageSuccessCallback onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void listStorages(FileSystemStorageArraySuccessCallback onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); long addStorageStateChangeListener(FileSystemStorageSuccessCallback onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void removeStorageStateChangeListener(long watchId) raises(WebAPIException); };
Since: 1.0
This manager interface exposes the Filesystem base API and provides functionalities, such as determining root and default locations, resolving a given location into a file handle and registering filesystem listeners for filesystem events.
Attributes
-
readonly
long maxNameLengthThe maximum file or directory name length for the current platform.
Since: 5.0
Code example:
console.log("The maximum name length is " + tizen.filesystem.maxNameLength);
Output example:
The maximum name length is 255
-
readonly
long maxPathLengthThe maximum path length limit for the current platform.
Since: 1.0
Code example:
console.log("The maximum path length is " + tizen.filesystem.maxPathLength);
Output example:
The maximum path length is 4096
Methods
-
openFile
-
Opens a file or creates a file pointed by path.
FileHandle openFile(Path path, FileMode openMode, optional boolean makeParents);
Since: 5.0
If the operation succeeds, a file handle to the newly created or opened file is returned, otherwise an exception is thrown.
Following file open modes are supported:
- a - append mode. File position indicator is always set to the first position after the last character of the file and cannot be modified with seek operations. Write operations always append content to the end of the file. Original file content are not modified. Read operations cannot be performed. If the file does not exist, it is created.
- r - read mode. File position indicator is initially set to the beginning of the file and may be changed with seek operations. Write operations cannot be performed. Original file content may be read in this mode. If the file does not exist, NotFoundError is thrown.
- rw - read and write mode. File position indicator is initially set to the beginning of the file and may be changed with seek operations. Original file content may be read or modified in this mode. If the file does not exist, NotFoundError will be thrown.
- rwo - read and write mode, overwriting existing file content. File position indicator is initially set to the beginning of the file. Read and write operations may be performed. Original file content are deleted before opening the file. If the file does not exist, it is created.
- w - write mode. File position indicator is initially set to the beginning of the file and may be changed with seek operations. Read operations cannot be performed. Original file content are deleted before opening the file. If the file does not exist, it is created.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Privilege: http://tizen.org/privilege/filesystem.write
Remark: Write permission is needed, when file is opened in modes: a, rw, rwo and w. Read permission is needed, when file is opened in modes: r, rw and rwo.
Parameters:
- path: Path to the file.
- openMode: Mode in which the file is to be opened.
- makeParents [optional]: Flag indicating whether lacking directories should be created. For instance, if method is invoked with parameter path equal to documents/path/to/dir/file.ext and there is no directory "path" in "documents" virtual root, directories "path", "to" and "dir" will be created, as well as the new file "file.ext". By default, makeParents is equal to true. Its value is ignored, when openMode is r or rw.
Return value:
-
FileHandle:
Object representing open file.
Exceptions:
- WebAPIException
with error type IOError, if a file is not available for open or any other IO error occurs.
with error type NotFoundError, if the path does not point to an existing file.
with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.
with error type TypeMismatchError, if any of the input parameters is not compatible with the expected type for that parameter.
Code example:
/* 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"); fileHandleWrite.writeString("Lorem ipsum dolor sit amet..."); console.log("String has been written to the file"); fileHandleWrite.close(); /* 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 fileContent = fileHandleRead.readString(); console.log("File content: " + fileContent); fileHandleRead.close();
Output example:
File opened for writing String has been written to the file File opened for reading File content: Lorem ipsum dolor sit amet...
-
createDirectory
-
Creates directory pointed by path.
void createDirectory(Path path, optional boolean makeParents, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 5.0
Successful directory creation invokes successCallback function, if specified. In case of failure errorCallback function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if any of the input/output error occurs.
- NotFoundError, if directory given in path does not exist and makeParents is set to false.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- path: Path to directory to create.
- makeParents [optional]: Flag indicating whether lacking directories should be created. For instance, if method is invoked with parameter path equal to documents/path/to/dir and there is no directory "path" in "documents" virtual root, directories "path", "to" and "dir" will be created. By default, makeParents is equal to true.
- successCallback [optional] [nullable]: Callback function to be invoked on success.
- errorCallback [optional] [nullable]: Callback function to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if the path is invalid.
with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.
with error type TypeMismatchError, if any of the input parameters is not compatible with the expected type for that parameter.
Code example:
function errorCallback(error) { console.log("An error occurred, during directory creation: " + error.message); } function successCallback(path) { console.log("The directory has been created, path to created directory: " + path); /* Directory can now be accessed. */ } try { tizen.filesystem.createDirectory( "documents/foo_dir/bar_dir", true, successCallback, errorCallback); } catch (error) { console.log("Directory cannot be created: " + error.message); }
Output example:
The directory has been created, path to created directory: documents/foo_dir/bar_dir
-
deleteFile
-
Deletes file pointed by path.
void deleteFile(Path path, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 5.0
Successful file deletion invokes successCallback function, if specified. In case of failure errorCallback function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if any of the input/output error occurs.
- NotFoundError, if the path does not point to an existing file.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- path: Path to file.
- successCallback [optional] [nullable]: Callback function to be invoked on success.
- errorCallback [optional] [nullable]: Callback function to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if the path is invalid.
with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.
with error type TypeMismatchError, if any of the input parameters is not compatible with the expected type for that parameter.
Code example:
function errorCallback(error) { console.log("An error occurred, during file deletion: " + error.message); } function successCallback(path) { console.log("The file has been deleted, path to the parent of deleted file: " + path); } try { tizen.filesystem.deleteFile("documents/foo", successCallback, errorCallback); } catch (error) { console.log("File cannot be deleted: " + error.message); }
Output example:
The file has been deleted, path to the parent of deleted file: documents
-
deleteDirectory
-
Deletes directory or directory tree under the current directory pointed by path.
void deleteDirectory(Path path, optional boolean recursive, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 5.0
Successful directory deletion invokes successCallback function, if specified. In case of failure errorCallback function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if a directory is not empty and recursive is equal to false.
- NotFoundError, if the path does not point to an existing directory.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- path: A path to directory.
- recursive [optional]: Flag indicating whether the deletion is recursive or not. If recursive is set to true the method will delete content of a given directory recursively. Otherwise, the method succeeds only if the directory is empty, on other cases errorCallback is called. By default, recursive is equal to true.
- successCallback [optional] [nullable]: Callback function to be invoked on success.
- errorCallback [optional] [nullable]: Callback function to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if the path is invalid.
with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.
with error type TypeMismatchError, if any of the input parameters is not compatible with the expected type for that parameter.
Code example:
function errorCallback(error) { console.log("An error occurred, during directory deletion: " + error.message); } function successCallback(path) { console.log("The directory has been deleted, path to the parent of deleted directory: " + path); } try { tizen.filesystem.deleteDirectory("documents/foo_dir", true, successCallback, errorCallback); } catch (error) { console.log("Directory cannot be deleted: " + error.message); }
Output example:
The directory has been deleted, path to the parent of deleted directory: documents
-
copyFile
-
Copies file from location pointed by sourcePath to destinationPath.
void copyFile(Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 5.0
Successful file copying invokes successCallback function, if specified. In case of failure errorCallback function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if any of the input/output error occurs.
- NotFoundError, if the sourcePath does not point to an existing file.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- sourcePath: Path to file.
- destinationPath: Path for copied file. The path must consist of path to an existing directory concatenated with '/' and the name of new file.
- overwrite [optional]: Flag indicating whether to overwrite an existing file. If overwrite is set to true and file pointed by destinationPath already exists, the method will overwrite the file. Otherwise, if a file with conflicting name already exists errorCallback is called. By default, overwrite is equal to false.
- successCallback [optional] [nullable]: Callback function to be invoked on success.
- errorCallback [optional] [nullable]: Callback function to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if any of the input parameters contains an invalid value. For example, the sourcePath or the destinationPath is invalid.
with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.
with error type TypeMismatchError, if any of the input parameters is not compatible with the expected type for that parameter.
Code example:
function errorCallback(error) { console.log("An error occurred, during copy operation: " + error.message); } function successCallback(path) { console.log("The file has been copied, path to copied file: " + path); /* File copy can now be accessed. */ } try { tizen.filesystem.copyFile("documents/foo", "documents/bar", true, successCallback, errorCallback); } catch (error) { console.log("Copy operation cannot be performed: " + error.message); }
Output example:
The file has been copied, path to copied file: documents/bar
-
copyDirectory
-
Recursively copies directory pointed by sourcePath to destinationPath.
void copyDirectory(Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 5.0
The method merges content of the directory pointed by sourcePath with content of the directory pointed by destinationPath, if exists. If the directory pointed by destinationPath does not exist, it is created.
Successful directory copying invokes successCallback function, if specified. In case of failure errorCallback function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if a directory with conflicting name already exists and overwrite is equal to false or any of the input/output error occurs.
- NotFoundError, if the sourcePath does not point to an existing directory.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- sourcePath: Path to directory.
- destinationPath: Path for copied directory. The path must consist of path to an existing directory concatenated with '/' and the name of destination directory.
- overwrite [optional]: Flag indicating whether to overwrite existing content. If overwrite is equal to true, the file or directory with conflicting name will be overwritten. Otherwise, errorCallback will be called with IOError. By default, overwrite is equal to false.
- successCallback [optional] [nullable]: Callback function to be invoked on success.
- errorCallback [optional] [nullable]: Callback function to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if any of the input parameters contains an invalid value. For example, the sourcePath or the destinationPath is invalid.
with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.
with error type TypeMismatchError, if any of the input parameters is not compatible with the expected type for that parameter.
Code example:
function errorCallback(error) { console.log("An error occurred, during copy operation: " + error.message); } function successCallback(path) { console.log("The directory has been copied, path to copied directory: " + path); /* Directory copy can now be accessed. */ } try { tizen.filesystem.copyDirectory( "documents/foo_dir", "documents/bar_dir", true, successCallback, errorCallback); } catch (error) { console.log("Copy operation cannot be performed: " + error.message); }
Output example:
The directory has been copied, path to copied directory: documents/bar_dir
Code example:
function errorCallback(error) { console.log("An error occurred: " + error.message); } function createFooDirCallback() { tizen.filesystem.createDirectory( "documents/foo_dir/dir_2", true, createFileCallback, errorCallback); } function listCallback(files, path) { console.log("Found inside " + path + " directory:"); for (var i = 0; i < files.length; i++) { console.log(files[i]); } } function successCallback(path) { console.log("The directory has been created and copied, path to directory: " + path); /* Directory 'documents/bar_dir' content is as below: */ /* documents/bar_dir/dir_1 */ /* documents/bar_dir/dir_2 */ /* documents/bar_dir/dir_1/file */ tizen.filesystem.listDirectory("documents/bar_dir", listCallback, errorCallback); tizen.filesystem.listDirectory("documents/bar_dir/dir_1", listCallback, errorCallback); } function createFileCallback() { tizen.filesystem.openFile("documents/foo_dir/dir_1/file", "w").close(); try { tizen.filesystem.copyDirectory( "documents/foo_dir", "documents/bar_dir", true, successCallback, errorCallback); } catch (error) { console.log("Copy operation cannot be performed: " + error.message); } } tizen.filesystem.createDirectory( "documents/foo_dir/dir_1", true, createFooDirCallback, errorCallback);
Output example:
The directory has been created and copied, path to directory: documents/bar_dir Found inside documents/bar_dir directory: dir_1 dir_2 Found inside documents/bar_dir/dir_1 directory: file
-
moveFile
-
Moves file pointed by sourcePath to destinationPath.
void moveFile(Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 5.0
Successful file moving invokes successCallback function, if specified. In case of failure errorCallback function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if a file with conflicting name already exists and overwrite is equal to false or any of the input/output error occurs.
- NotFoundError, if the sourcePath or destinationPath does not point to an existing file or directory.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- sourcePath: Path to file.
- destinationPath: A destination directory path to move the file to.
- overwrite [optional]: Flag indicating whether to overwrite an existing file. If overwrite is set to true and file with the same name in destinationPath already exists, the method will overwrite the file. Otherwise, if a file with conflicting name already exists errorCallback is called. By default, overwrite is equal to false.
- successCallback [optional] [nullable]: Callback function to be invoked on success.
- errorCallback [optional] [nullable]: Callback function to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if any of the input parameters contains an invalid value. For example, the sourcePath or the destinationPath is invalid.
with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.
with error type TypeMismatchError, if any of the input parameters is not compatible with the expected type for that parameter.
Code example:
function errorCallback(error) { console.log("An error occurred, during move operation: " + error.message); } function successCallback(path) { console.log("The file has been moved, path to moved file: " + path); /* Moved file can now be accessed. */ } try { tizen.filesystem.moveFile( "documents/foo", "documents/foo_dir/", false, successCallback, errorCallback); } catch (error) { console.log("Move operation cannot be performed: " + error.message); }
Output example:
The file has been moved, path to moved file: documents/foo_dir/foo
-
moveDirectory
-
Recursively moves directory pointed by sourcePath to destinationPath.
void moveDirectory(Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 5.0
The method merges content of the directory pointed by sourcePath with content of the directory with the same name in destinationPath, if exists.
Successful directory moving invokes successCallback function, if specified. In case of failure errorCallback function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if a directory with conflicting name already exists and overwrite is equal to false or any of the input/output error occurs.
- NotFoundError, if the sourcePath or destinationPath does not point to an existing directory.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- sourcePath: A path to directory.
- destinationPath: A destination directory path to move the directory to.
- overwrite [optional]: Flag indicating whether to overwrite existing content. If overwrite is equal to true, the file or directory with conflicting name will be overwritten. Otherwise, errorCallback will be called with IOError. By default, overwrite is equal to false.
- successCallback [optional] [nullable]: Callback function to be invoked on success.
- errorCallback [optional] [nullable]: Callback function to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if any of the input parameters contains an invalid value. For example, the sourcePath or the destinationPath is invalid.
with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.
with error type TypeMismatchError, if any of the input parameters is not compatible with the expected type for that parameter.
Code example:
function errorCallback(error) { console.log("An error occurred, during move operation: " + error.message); } function successCallback(path) { console.log("The directory has been moved, path to moved directory: " + path); /* Moved directory can now be accessed. */ } try { tizen.filesystem.moveDirectory( "documents/foo_dir", "documents/bar_dir/", false, successCallback, errorCallback); } catch (error) { console.log("Move operation cannot be performed: " + error.message); }
Output example:
The directory has been moved, path to moved directory: documents/bar_dir/foo_dir
-
rename
-
Renames file or directory located in path to name newName.
void rename(Path path, DOMString newName, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback);
Since: 5.0
Successful renaming invokes successCallback function, if specified. In case of failure errorCallback function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if a file or a directory with conflicting name already exists or any of the input/output error occurs.
- NotFoundError, if the path does not point to an existing file or directory.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- path: A path to directory or file.
- newName: A new name of directory or file.
- successCallback [optional] [nullable]: Callback function to be invoked on success.
- errorCallback [optional] [nullable]: Callback function to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if the path or newName is invalid.
with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.
with error type TypeMismatchError, if any of the input parameters is not compatible with the expected type for that parameter.
Code example:
function errorCallback(error) { console.log("An error occurred, during rename operation: " + error.message); } function successCallback(path) { console.log("The file has been renamed, path to renamed file or directory: " + path); } try { tizen.filesystem.rename("documents/foo", "bar", successCallback, errorCallback); } catch (error) { console.log("Rename operation cannot be performed: " + error.message); }
Output example:
The file has been renamed, path to renamed file or directory: documents/bar
-
listDirectory
-
Lists directory content located in path.
void listDirectory(Path path, ListDirectorySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional FileFilter? filter);
Since: 5.0
Successful listing of directory content invokes successCallback function, if specified. In case of failure errorCallback function is invoked, if specified.
If the filter is passed and contains valid values, only those directories or files in the directory that match the filter criteria specified in the FileFilter interface are returned in successCallback method. If the filter is null or undefined the implementation must return the full list of files in the directory.
If the directory does not contain any files or directories, or the filter criteria do not match with any files or directories, the successCallback is invoked with an empty array.
The ErrorCallback is launched with these error types:
- IOError, if any of the input/output error occurs.
- NotFoundError, if the path does not point to an existing directory.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Parameters:
- path: A path to directory.
- successCallback: Callback function to be invoked on success.
- errorCallback [optional] [nullable]: Callback function to be invoked when an error occurs.
- filter [optional] [nullable]: Filter to restrict the listed files.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if any of the input parameters contains an invalid value. For example, the path is invalid.
with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.
with error type TypeMismatchError, if any of the input parameters is not compatible with the expected type for that parameter.
Code example:
function errorCallback(error) { console.log("An error occurred, during directory listing: " + error.message); } function successCallback(files, path) { console.log("Found directories in " + path + " directory:"); for (var i = 0; i < files.length; i++) { console.log(files[i]); } } try { var start = new Date("Jan 01 2018 00:00:00"); tizen.filesystem.listDirectory("documents/", successCallback, errorCallback, {name: "foo_%", isDirectory: true, startModified: start}); } catch (error) { console.log("Directory listing cannot be performed: " + error.message); }
Output example:
Found directories in documents/ directory: foo_dir_c foo_dir_b foo_dir_d foo_dir_a
-
toURI
-
Converts path to file URI.
DOMString toURI(Path path);
Since: 5.0
Remark: The function does not check if path exists in filesystem.
Parameters:
- path: A path to a file or a directory.
Return value:
-
DOMString:
File URI for given path.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if the path is invalid.
Code example:
var path1 = tizen.filesystem.toURI("documents/directory/file.ext"); var path2 = tizen.filesystem.toURI("/opt/usr/home/owner/content/Documents/directory/file.ext"); var path3 = tizen.filesystem.toURI("file:///opt/usr/home/owner/content/Documents/directory/file.ext"); /* All above paths point to the same file. */ console.log(path1); console.log(path2); console.log(path3); var mmcPath = tizen.filesystem.toURI("removable_sda1/Documents/directory/file"); console.log(mmcPath);
Output example:
file:///opt/usr/home/owner/content/Documents/directory/file.ext file:///opt/usr/home/owner/content/Documents/directory/file.ext file:///opt/usr/home/owner/content/Documents/directory/file.ext file:///opt/media/USBDriveA1/Documents/directory/file
-
isFile
-
Checks if given path points to a file.
boolean isFile(Path path);
Since: 5.0
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Parameters:
- path: A path to be tested.
Return value:
-
boolean:
true if path points to a file, false otherwise.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if the path is invalid.
with error type IOError, if any of the input/output error occurs.
with error type NotFoundError, if the path does not point to an existing file or directory.
with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.
Code example:
console.log("documents/foo_file is " + (tizen.filesystem.isFile("documents/foo_file") ? "file" : "directory"));
Output example:
documents/foo_file is file
-
isDirectory
-
Checks if given path points to a directory.
boolean isDirectory(Path path);
Since: 5.0
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Parameters:
- path: A path to be tested.
Return value:
-
boolean:
true if path points to a directory, false otherwise.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if the path is invalid.
with error type IOError, if any of the input/output error occurs.
with error type NotFoundError, if the path does not point to an existing file or directory.
with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.
Code example:
console.log("documents/foo_dir is " + (tizen.filesystem.isDirectory("documents/foo_dir") ? "directory" : "file"));
Output example:
documents/foo_dir is directory
-
pathExists
-
Checks if given path exists.
boolean pathExists(Path path);
Since: 5.0
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Parameters:
- path: A path to be tested.
Return value:
-
boolean:
true if path points to a existing element, false otherwise.
Exceptions:
- WebAPIException
with error type InvalidValuesError, if the path is invalid.
with error type IOError, if input/output error occurs.
with error type SecurityError, if the application does not have the privilege to call this method or the application does not have privilege to access the storage. For more information, see Storage privileges.
Code example:
console.log("documents/foo " + (tizen.filesystem.pathExists("documents/foo") ? "exists" : "does not exist"));
Output example:
documents/foo does not exist
-
getDirName
-
Returns path to directory for given path.
DOMString getDirName(DOMString path);
Since: 5.0
Strips trailing '/', then breaks path into two components by last path separator, returns first component.
Remark: This function does not check if path is valid or exists in filesystem.
Parameters:
- path: Path to file or directory.
Return value:
-
DOMString:
Path to directory for given path.
Code example:
console.log(tizen.filesystem.getDirName("/home/owner/media/Documents"));
Output example:
"/home/owner/media"
-
getStorage
-
Gets information about a storage based on its label.
For example: "MyThumbDrive", "InternalFlash".void getStorage(DOMString label, FileSystemStorageSuccessCallback onsuccess, optional ErrorCallback? onerror);
Since: 1.0
The onsuccess method receives the data structure as an input argument containing additional information about the drive.
The ErrorCallback is launched with these error types:
- InvalidValuesError - If any of the input parameters contains an invalid value.
- NotFoundError - If no drive was found with the given label.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Parameters:
- label: Storage label.
- onsuccess: Callback method to be invoked when the list of storages is available, passing the storage list to the callback.
- onerror [optional] [nullable]: Callback method to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method. For more information, see Storage privileges.
Code example:
function onStorage(storage) { /* Do something. */ } function onStorageError(e) { console.log("Storage not found: " + e.message); } tizen.filesystem.getStorage("music", onStorage, onStorageError);
-
listStorages
-
Lists the available storages (both internal and external) on a device. The onsuccess method receives a list of the data structures as input argument containing additional information about each drive found. It can get storages that would have a label named as "internal0", virtual roots (images, documents, ...), "removable1", "removable2". "removable1" label is used to resolve sdcard and "removable2" label is used to resolve USB host, if supported. The vfat filesystem used to sdcard filesystem widely is not case-sensitive. If you want to handle the file on sdcard, you need to consider case-sensitive filenames are regarded as same name.
void listStorages(FileSystemStorageArraySuccessCallback onsuccess, optional ErrorCallback? onerror);
Since: 1.0
Labels can differ depending on platform implementation.
The ErrorCallback is launched with these error types:
- InvalidValuesError - If any of the input parameters contains an invalid value.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Parameters:
- onsuccess: Callback method to be invoked when a list of storage is available and passing the storage list to the callback.
- onerror [optional] [nullable]: Callback method to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type SecurityError, if the application does not have the privilege to call this method. For more information, see Storage privileges.
Code example:
function alertForCorruptedRemovableDrives(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"); } } tizen.filesystem.listStorages(alertForCorruptedRemovableDrives);
-
addStorageStateChangeListener
-
Adds a listener to subscribe to notifications when a change in storage state occurs.
long addStorageStateChangeListener(FileSystemStorageSuccessCallback onsuccess, optional ErrorCallback? onerror);
Since: 1.0
The most common usage for this method is to watch for any additions and removals of external storages.
When executed, it returns a subscription identifier that identifies the watch operation. After returning the identifier, the watch operation is started asynchronously. The onsuccess method will be invoked every time a storage state changes. If the attempt fails, the onerror if present will be invoked with the relevant error type.
The watch operation must continue until the removeStorageStateChangeListener() method is called with the corresponding subscription identifier.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- onsuccess: Callback method to be invoked when any change is made to storage state.
- onerror [optional] [nullable]: Callback method to be invoked when an error occurs during the watch process.
Return value:
-
long:
Subscription identifier.
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method. For more information, see Storage privileges.
with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.
with error type UnknownError, if any other error occurs.
Code example:
var watchID; function onStorageStateChanged(storage) { if (storage.state == "MOUNTED") console.log("Storage " + storage.label + " was added!"); } watchID = tizen.filesystem.addStorageStateChangeListener(onStorageStateChanged);
-
removeStorageStateChangeListener
-
Removes a listener to unsubscribe from a storage watch operation.
void removeStorageStateChangeListener(long watchId);
Since: 1.0
If the watchId argument is valid and corresponds to a subscription already in place, the watch process will be stopped and no further callbacks will be invoked. Otherwise, the method call has no effect.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- watchId: Subscription identifier.
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method. For more information, see Storage privileges.
with error type UnknownError, if any other error occurs.
Code example:
var watchID; function onStorageStateChanged(storage) { if (storage.state == "MOUNTED") console.log("Storage " + storage.label + " was added!"); tizen.filesystem.removeStorageStateChangeListener(watchID); } watchID = tizen.filesystem.addStorageStateChangeListener(onStorageStateChanged);
2.3. FileSystemStorage
[NoInterfaceObject] interface FileSystemStorage { readonly attribute DOMString label; readonly attribute FileSystemStorageType type; readonly attribute FileSystemStorageState state; };
Since: 1.0
To retrieve the mount point, the resolve() method should be used using the label as argument.
Attributes
-
readonly
DOMString labelThe storage name.
This attribute is used as an input for methods such as getStorage() and also used as location parameter for File.resolve() and FileSystemManager.resolve().
Since: 1.0
-
readonly
FileSystemStorageType typeThe storage type as internal or external.
Since: 1.0
-
readonly
FileSystemStorageState stateThe storage state as mounted or not.
Since: 1.0
2.4. FileHandle
[NoInterfaceObject] interface FileHandle { readonly attribute Path path; long long seek(long long offset, optional BaseSeekPosition whence) raises(WebAPIException); void seekNonBlocking(long long offset, optional SeekSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional BaseSeekPosition whence) raises(WebAPIException); DOMString readString(optional long long? count, optional DOMString inputEncoding) raises(WebAPIException); void readStringNonBlocking(optional ReadStringSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional long long count, optional DOMString inputEncoding) raises(WebAPIException); long long writeString(DOMString inputString, optional DOMString outputEncoding) raises(WebAPIException); void writeStringNonBlocking(DOMString inputString, optional WriteStringSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional DOMString outputEncoding) raises(WebAPIException); Blob readBlob(optional long long size) raises(WebAPIException); void readBlobNonBlocking(optional ReadBlobSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional long long? size) raises(WebAPIException); void writeBlob(Blob blob) raises(WebAPIException); void writeBlobNonBlocking(Blob blob, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); Uint8Array readData(optional long long size) raises(WebAPIException); void readDataNonBlocking(optional ReadDataSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional long long? size) raises(WebAPIException); void writeData(Uint8Array data) raises(WebAPIException); void writeDataNonBlocking(Uint8Array data, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void flush() raises(WebAPIException); void flushNonBlocking(optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void sync() raises(WebAPIException); void syncNonBlocking(optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void close() raises(WebAPIException); void closeNonBlocking(optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); };
Since: 5.0
Each read or write operation moves position in file forwards to the end of read/written data (there is an underlying file position's indicator).
Remark: Due to multibyte UTF-8 encoding, if current file's pointer does not point to beginning of multibyte sequence (see: UTF-16, emoji), using seek() combined with UTF-8 readString() will result in string starting from valid character. Incomplete byte sequence at the beginning may be omitted. Be aware about using seek and write methods together. It can result in writing in the middle of multibyte sequence, which can lead to file with corrupted content.
Attributes
-
readonly
Path pathPath, as passed to openFile.
Since: 5.0
Methods
-
seek
-
Sets position indicator in file stream to offset.
long long seek(long long offset, optional BaseSeekPosition whence);
Since: 5.0
Note, that current position indicator value, can be obtained by calling seek(0, "CURRENT").
Parameters:
- offset: Number of bytes to shift the position relative to whence.
- whence [optional]: Determines position in file stream to which offset is added. Default value: "BEGIN".
Return value:
-
long long:
File position indicator.
Exceptions:
- WebAPIException
with error type IOError, if seek fails or any error related to file handle occurs.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
var dataToWrite = new Uint8Array([11, 21, 31, 44, 55, 66, 71, 81, 91]); /* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); fileHandleWrite.writeData(dataToWrite); fileHandleWrite.close(); console.log("Data has been written"); /* 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"); var firstThreeBytes = fileHandleRead.readData(3); console.log("First three bytes: " + firstThreeBytes); var position = fileHandleRead.seek(-3, "END"); /* Moving to position three bytes to the end of file. */ var lastThreeBytes = fileHandleRead.readData(3); console.log("Last three bytes: " + lastThreeBytes); fileHandleRead.seek(3, "BEGIN"); /* Moving to position at third byte. */ var bytesBetween = fileHandleRead.readData(position - 3); console.log("Bytes between: " + bytesBetween); fileHandleRead.close();
Output example:
Data has been written First three bytes: 11,21,31 Last three bytes: 71,81,91 Bytes between: 44,55,66
-
seekNonBlocking
-
Sets position indicator in file stream to offset.
void seekNonBlocking(long long offset, optional SeekSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional BaseSeekPosition whence);
Since: 5.0
Successful seek operation invokes onsuccess function, if specified. In case of failure onerror function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if any error related to file handle occurs.
Note, that current position indicator value, can be obtained in SeekSuccessCallback by calling seekNonBlocking(0, "CURRENT"). seekNonBlocking is executed in background and does not block further instructions.
Parameters:
- offset: Number of bytes to shift the position relative to whence.
- onsuccess [optional] [nullable]: Callback function to be invoked on success.
- onerror [optional] [nullable]: Callback function to be invoked when an error occurs.
- whence [optional]: Determines position in file stream to which offset is added. Default value: "BEGIN".
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
/* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); fileHandleWrite.writeStringNonBlocking("Lorem ipsum dolor sit amet...", function(bytesCount) { console.log("Number of bytes written: " + bytesCount); }, function(error) { console.log(error); }); /* Moving to position 3 bytes to the end of file to alter three dots ("..."). */ fileHandleWrite.seekNonBlocking(-3, function(new_position) { console.log("Moved to position: " + new_position); }, function(error) { console.log(error); }, "END"); fileHandleWrite.writeStringNonBlocking(", consectetur adipiscing elit...", function(bytesCount) { console.log("Number of bytes written: " + bytesCount); }, function(error) { console.log(error); }); /* Moving to position 3 bytes to the end of file to alter three dots ("..."). */ fileHandleWrite.seekNonBlocking(-3, function(new_position) { console.log("Moved to position: " + new_position); }, function(error) { console.log(error); }, "END"); fileHandleWrite.writeStringNonBlocking(", sed do eiusmod...", function(bytesCount) { console.log("Number of bytes written: " + bytesCount); }, function(error) { console.log(error); }); fileHandleWrite.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); }); /* 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"); /* ReadStringSuccessCallback should be executed. */ fileHandleRead.readStringNonBlocking( function(output) { console.log("File content: " + output); }, function(error) { console.log(error); }); fileHandleRead.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); });
Output example:
Number of bytes written: 29 Moved to position: 26 Number of bytes written: 32 Moved to position: 55 Number of bytes written: 19 File handle closed File content: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod... File handle closed
-
readString
-
Reads file content as string.
DOMString readString(optional long long? count, optional DOMString inputEncoding);
Since: 5.0
Sets file handle position indicator at the end of read data. Reads given number of characters.
Remark: Resulting string can have length larger than count, due to possible UTF-16 surrogate pairs in it. String length in JavaScript is counted in UTF-16 encoding, so for example string containing one emoji (surrogate of two UTF-16) character will have length of two.
Parameters:
- count [optional] [nullable]: Number of characters to read from file. If none is given, method attempts to read whole file.
-
inputEncoding [optional]:
Default value: "UTF-8". Encoding to use for read operation on the file, at least the following encodings must be supported:
"UTF-8" default encoding
"ISO-8859-1" Latin-1 encoding
Return value:
-
DOMString:
String with data read from file.
Exceptions:
- WebAPIException
with error type InvalidValuesError if given count exceeds maximum value supported by the device.
with error type IOError, if read fails or any error related to file handle occurs.
with error type NotSupportedError, if the given encoding is not supported.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
/* 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"); fileHandleWrite.writeString("Lorem ipsum dolor sit amet..."); console.log("String has been written to the file"); fileHandleWrite.close(); /* 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 fileContent = fileHandleRead.readString(); console.log("File content: " + fileContent); fileHandleRead.close();
Output example:
File opened for writing String has been written to the file File opened for reading File content: Lorem ipsum dolor sit amet...
-
readStringNonBlocking
-
Reads file content as string.
void readStringNonBlocking(optional ReadStringSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional long long count, optional DOMString inputEncoding);
Since: 5.0
Reads given number of characters. Sets file handle position indicator at the end of read data. readStringNonBlocking is executed in background and does not block further instructions.
Successful read operation invokes onsuccess function, if specified. In case of failure onerror function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if read fails or any error related to file handle occurs.
Parameters:
- onsuccess [optional] [nullable]: Callback function with read data from file to be invoked on success.
- onerror [optional] [nullable]: Callback function to be invoked when an error occurs.
- count [optional]: Number of characters to read from file. If none is given, method attempts to read whole file.
-
inputEncoding [optional]:
Default value: "UTF-8". Encoding to use for read operation on the file, at least the following encodings must be supported:
"UTF-8" default encoding
"ISO-8859-1" Latin-1 encoding
Exceptions:
- WebAPIException
with error type InvalidValuesError if given count exceeds maximum value supported by the device.
with error type NotSupportedError, if the given encoding is not supported.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
/* 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"); fileHandleWrite.writeStringNonBlocking("Lorem ipsum dolor sit amet...", function(bytesCount) { console.log("Number of bytes written: " + bytesCount); }, function(error) { console.log(error); }); fileHandleWrite.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); }); /* Opening file for read - below code assumes that there is */ /* a file named "file" in documents directory. */ var fileHandleRead = tizen.filesystem.openFile("documents/file", "r"); /* ReadStringSuccessCallback should be executed. */ fileHandleRead.readStringNonBlocking( function(output) { console.log("File content: " + output); }, function(error) { console.log(error); }); fileHandleRead.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); });
Output example:
File opened for writing Number of bytes written: 29 File handle closed File content: Lorem ipsum dolor sit amet... File handle closed
-
writeString
-
Writes inputString content to a file.
long long writeString(DOMString inputString, optional DOMString outputEncoding);
Since: 5.0
Sets file handle position indicator at the end of written data.
Parameters:
- inputString: String value to be written to a file.
-
outputEncoding [optional]:
Default value: UTF-8. Encoding to use for write operation on the file, at least the following encodings must be supported:
"UTF-8" default encoding
"ISO-8859-1" Latin-1 encoding
Return value:
-
long long:
Number of bytes written (can be more than inputString length for multibyte encodings and will never be less)
Exceptions:
- WebAPIException
with error type IOError, if input/output error occurs.
with error type NotSupportedError, if the given encoding is not supported.
Code example:
/* 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"); fileHandleWrite.writeString("Lorem ipsum dolor sit amet..."); console.log("String has been written to the file"); fileHandleWrite.close(); /* 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 fileContent = fileHandleRead.readString(); console.log("File content: " + fileContent); fileHandleRead.close();
Output example:
File opened for writing String has been written to the file File opened for reading File content: Lorem ipsum dolor sit amet...
-
writeStringNonBlocking
-
Writes inputString content to a file.
void writeStringNonBlocking(DOMString inputString, optional WriteStringSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional DOMString outputEncoding);
Since: 5.0
Sets file handle position indicator at the end of written data. writeStringNonBlocking is executed in background and does not block further instructions.
Successful write operation invokes successCallback function, if specified. In case of failure onerror function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if write fails or any error related to file handle occurs.
Parameters:
- inputString: String value to be written to a file.
- onsuccess [optional] [nullable]: Callback function with a number of bytes written as parameter to be invoked on success.
- onerror [optional] [nullable]: Callback function to be invoked when an error occurs.
-
outputEncoding [optional]:
Default value: "UTF-8". Encoding to use for write operation on the file, at least the following encodings must be supported:
"UTF-8" default encoding
"ISO-8859-1" Latin-1 encoding
Exceptions:
- WebAPIException
with error type NotSupportedError, if the given encoding is not supported.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
/* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); fileHandleWrite.writeStringNonBlocking("Lorem ipsum dolor sit amet...", function(bytesCount) { console.log("Number of bytes written: " + bytesCount); }, function(error) { console.log(error); }); fileHandleWrite.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); }); /* Opening file for read - below code assumes that there is */ /* a file named "file" in documents directory. */ var fileHandleRead = tizen.filesystem.openFile("documents/file", "r"); /* ReadStringSuccessCallback should be executed. */ fileHandleRead.readStringNonBlocking( function(output) { console.log("File content: " + output); }, function(error) { console.log(error); }); fileHandleRead.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); });
Output example:
Number of bytes written: 29 File handle closed File content: Lorem ipsum dolor sit amet... File handle closed
-
readBlob
-
Reads file content as Blob.
Blob readBlob(optional long long size);
Since: 5.0
Sets file handle position indicator at the end of read data.
Parameters:
- size [optional]: Size in bytes of data to read from file. If none is given, method attempts to read whole file.
Return value:
-
Blob:
Blob object with file content.
Exceptions:
- WebAPIException
with error type InvalidValuesError if given size exceeds maximum value supported by the device.
with error type IOError, if read fails or any error related to file handle occurs.
Code example:
/* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); var b = new Blob(["Lorem ipsum dolor sit amet..."], {type: "text/plain"}); fileHandleWrite.writeBlob(b); fileHandleWrite.close(); console.log("Blob content has been written to file"); /* 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"); var fileContentInBlob = fileHandleRead.readBlob(); fileHandleRead.close(); const reader = new FileReader(); /* Event fires after the blob has been read/loaded. */ reader.onloadend = function(content) { const text = content.srcElement.result; console.log("File content: " + text); }; /* Starts reading the blob as text. */ reader.readAsText(fileContentInBlob);
Output example:
Blob content has been written to file File content: Lorem ipsum dolor sit amet...
-
readBlobNonBlocking
-
Reads file content as Blob.
void readBlobNonBlocking(optional ReadBlobSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional long long? size);
Since: 5.0
Sets file handle position indicator at the end of read data. readBlobNonBlocking is executed in background and does not block further instructions.
Successful read operation invokes onsuccess function, if specified. In case of failure onerror function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if read fails or any error related to file handle occurs.
Parameters:
- onsuccess [optional] [nullable]: Callback function with Blob object to be invoked on success.
- onerror [optional] [nullable]: Callback function to be invoked when an error occurs.
- size [optional] [nullable]: Size in bytes of data to read from file. If none is given, method attempts to read whole file.
Exceptions:
- WebAPIException
with error type InvalidValuesError if given size exceeds maximum value supported by the device.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
/* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); var b = new Blob(["Lorem ipsum dolor sit amet..."], {type: "text/plain"}); fileHandleWrite.writeBlobNonBlocking(b, function() { console.log("Blob content has been written to file"); }, function(error) { console.log(error); }); fileHandleWrite.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); }); /* 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"); /* Creation of a reader capable of extracting Blob content. */ const reader = new FileReader(); /* Event fires after the blob has been read/loaded. */ reader.onloadend = function(content) { const text = content.srcElement.result; console.log("File content: " + text); }; function readBlobCallback(fileContentInBlob) { reader.readAsText(fileContentInBlob); } /* readBlobCallback should be executed. */ fileHandleRead.readBlobNonBlocking(readBlobCallback, function(error) { console.log(error); }); fileHandleRead.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); });
Output example:
Blob content has been written to file File handle closed File handle closed File content: Lorem ipsum dolor sit amet...
-
writeBlob
-
Writes Blob to file.
void writeBlob(Blob blob);
Since: 5.0
Sets file handle position indicator at the end of written data.
Parameters:
- blob: Object of type Blob, which content will be written to a file.
Exceptions:
- WebAPIException
with error type IOError, if write fails or any error related to file handle occurs.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
/* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); var b = new Blob(["Lorem ipsum dolor sit amet..."], {type: "text/plain"}); fileHandleWrite.writeBlob(b); fileHandleWrite.close(); console.log("Blob content has been written to file"); /* 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"); var fileContentInBlob = fileHandleRead.readBlob(); fileHandleRead.close(); console.log("File content has been read from file"); const reader = new FileReader(); /* Event fires after the blob has been read/loaded. */ reader.onloadend = function(content) { const text = content.srcElement.result; console.log("File content: " + text); }; /* Starts reading the blob as text. */ reader.readAsText(fileContentInBlob);
Output example:
Blob content has been written to file File content has been read from file File content: Lorem ipsum dolor sit amet...
-
writeBlobNonBlocking
-
Writes Blob to file.
void writeBlobNonBlocking(Blob blob, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);
Since: 5.0
Sets file handle position indicator at the end of written data. writeBlobNonBlocking is executed in background and does not block further instructions.
Successful write operation invokes onsuccess function, if specified. In case of failure onerror function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if write fails or any error related to file handle occurs.
Parameters:
- blob: Object of type Blob, which content will be written to a file.
- onsuccess [optional] [nullable]: Callback function to be invoked on success.
- onerror [optional] [nullable]: Callback function to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
/* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); var b = new Blob(["Lorem ipsum dolor sit amet..."], {type: "text/plain"}); fileHandleWrite.writeBlobNonBlocking(b, function() { console.log("Blob content has been written to file"); }, function(error) { console.log(error); }); fileHandleWrite.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); }); /* 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"); /* Creation of a reader capable of extracting Blob content. */ const reader = new FileReader(); /* Event fires after the blob has been read/loaded. */ reader.onloadend = function(content) { const text = content.srcElement.result; console.log("File content: " + text); }; function readBlobCallback(fileContentInBlob) { reader.readAsText(fileContentInBlob); } /* readBlobCallback should be executed. */ fileHandleRead.readBlobNonBlocking(readBlobCallback); fileHandleRead.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); });
Output example:
Blob content has been written to file File handle closed File handle closed File content: Lorem ipsum dolor sit amet...
-
readData
-
Reads file content as binary data.
Uint8Array readData(optional long long size);
Since: 5.0
Can be used in combination with atob() or btoa() functions. Sets file handle position indicator at the end of read data.
Parameters:
- size [optional]: Size in bytes of data to read from file. If none is given, method attempts to read whole file.
Return value:
-
Uint8Array:
Read data as Uint8Array.
Exceptions:
- WebAPIException
with error type InvalidValuesError if given size exceeds maximum value supported by the device.
with error type IOError, if read fails or any error related to file handle occurs.
Code example:
var dataToWrite = new Uint8Array([11, 21, 31, 71, 81, 91]); /* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); fileHandleWrite.writeData(dataToWrite); fileHandleWrite.close(); console.log("Data has been written"); /* Opening file for read - below code assumes that there is */ /* a file named "file" in documents directory. */ var fileHandleRead = tizen.filesystem.openFile("documents/file", "r"); var fileContentInUint8Array = fileHandleRead.readData(); fileHandleRead.close(); console.log("Data read from file: " + fileContentInUint8Array);
Output example:
Data has been written Data read from file: 11,21,31,71,81,91
-
readDataNonBlocking
-
Reads file content as binary data.
void readDataNonBlocking(optional ReadDataSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional long long? size);
Since: 5.0
Can be used in combination with atob() or btoa() functions. Sets file handle position indicator at the end of read data. readDataNonBlocking is executed in background and does not block further instructions.
Successful read operation invokes onsuccess function, if specified. In case of failure onerror function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if read fails or any error related to file handle occurs.
Parameters:
- onsuccess [optional] [nullable]: Callback function with read data from file to be invoked on success.
- onerror [optional] [nullable]: Callback function to be invoked when an error occurs.
- size [optional] [nullable]: Size in bytes of data to read from file. If none is given, method attempts to read whole file.
Exceptions:
- WebAPIException
with error type InvalidValuesError if given size exceeds maximum value supported by the device.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
var dataToWrite = new Uint8Array([11, 21, 31, 71, 81, 91]); /* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); fileHandleWrite.writeDataNonBlocking(dataToWrite, function(dataRead) { console.log("Write done"); }, function(error) { console.log(error); }); fileHandleWrite.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); }); /* Opening file for read - below code assumes that there is */ /* a file named "file" in documents directory. */ var fileHandleRead = tizen.filesystem.openFile("documents/file", "r"); fileHandleRead.readDataNonBlocking( function(dataRead) { console.log("Data read from file: " + dataRead); }, function(error) { console.log(error); }); fileHandleRead.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); });
Output example:
Write done File handle closed Data read from file: 11,21,31,71,81,91 File handle closed
-
writeData
-
Writes binary data to file.
void writeData(Uint8Array data);
Since: 5.0
Can be used in combination with atob() or btoa() functions. Sets file handle position indicator at the end of written data.
Parameters:
- data: An array of type Uint8Array, which content will be written to file as binary data.
Exceptions:
- WebAPIException
with error type IOError, if write fails or any error related to file handle occurs.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
var dataToWrite = new Uint8Array([11, 21, 31, 71, 81, 91]); /* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); fileHandleWrite.writeData(dataToWrite); fileHandleWrite.close(); console.log("Data has been written"); /* Opening file for read - below code assumes that there is */ /* a file named "file" in documents directory. */ var fileHandleRead = tizen.filesystem.openFile("documents/file", "r"); var fileContentInUint8Array = fileHandleRead.readData(); fileHandleRead.close(); console.log("Data read from file: " + fileContentInUint8Array);
Output example:
Data has been written Data read from file: 11,21,31,71,81,91
-
writeDataNonBlocking
-
Writes binary data to file.
void writeDataNonBlocking(Uint8Array data, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);
Since: 5.0
Can be used in combination with atob() or btoa() functions. Sets file handle position indicator at the end of written data. writeDataNonBlocking is executed in background and does not block further instructions.
Successful write operation invokes onsuccess function, if specified. In case of failure onerror function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if write fails or any error related to file handle occurs.
Parameters:
- data: An array of type Uint8Array, which content will be written to file as binary data.
- onsuccess [optional] [nullable]: Callback function to be invoked on success.
- onerror [optional] [nullable]: Callback function to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
var dataToWrite = new Uint8Array([11, 21, 31, 71, 81, 91]); /* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); fileHandleWrite.writeDataNonBlocking(dataToWrite, function(dataRead) { console.log("Write done"); }, function(error) { console.log(error); }); fileHandleWrite.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); }); /* Opening file for read - below code assumes that there is */ /* a file named "file" in documents directory. */ var fileHandleRead = tizen.filesystem.openFile("documents/file", "r"); fileHandleRead.readDataNonBlocking( function(dataRead) { console.log("Data read from file: " + dataRead); }, function(error) { console.log(error); }); fileHandleRead.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); });
Output example:
Write done File handle closed Data read from file: 11,21,31,71,81,91 File handle closed
-
flush
-
Flushes data.
void flush();
Since: 5.0
For file handles with permission to write, flush writes any changes made to file content to underlying buffer.
Flush does not ensure that data is written on storage device, it only synchronizes RAM with file descriptor. To ensure storage synchronization use sync, close or their asynchronous equivalent methods, which guarantee such synchronization.
Exceptions:
- WebAPIException
with error type IOError, if flush fails or any error related to file handle occurs.
Code example:
/* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); var fileHandleRead = tizen.filesystem.openFile("documents/file", "r"); fileHandleWrite.writeString("Lorem ipsum dolor sit amet..."); console.log("Data has been written to file"); /* Calling flush() ensures that content has been written to file descriptor and can be read by any */ /* process. */ fileHandleWrite.flush(); console.log("Data has been flushed to system file buffer and now can be read"); var fileContent = fileHandleRead.readString(); console.log("Read data: " + fileContent); fileHandleWrite.close(); fileHandleRead.close();
Output example:
Data has been written to file Data has been flushed to system file buffer and now can be read Read data: Lorem ipsum dolor sit amet...
- WebAPIException
-
flushNonBlocking
-
Flushes data.
void flushNonBlocking(optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);
Since: 5.0
For file handles with permission to write, flush writes any changes made to file content to underlying buffer.
Flush does not ensure that data is written on storage device, it only synchronizes RAM with file descriptor. To ensure storage synchronization use sync, close or their asynchronous equivalent methods, which guarantee such synchronization.
Successful flushing invokes onsuccess function, if specified. In case of failure onerror function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if flush fails or any error related to file handle occurs.
This method is asynchronous. Its execution will occur in background and after all previously commissioned background jobs will finish.
Parameters:
- onsuccess [optional] [nullable]: Callback function to be invoked on success.
- onerror [optional] [nullable]: Callback function to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
/* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); fileHandleWrite.writeStringNonBlocking("Lorem ipsum dolor sit amet...", function(bytesCount) { console.log("Number of bytes written: " + bytesCount); }, function(error) { console.log(error); }); /* Calling flushNonBlocking() ensures that content will be written to file descriptor */ /* and can be read by any process. */ fileHandleWrite.flushNonBlocking( function() { console.log("Data has been flushed to system file buffer and now can be read"); }, function(error) { console.log(error); }); /* 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"); fileHandleRead.readStringNonBlocking( function(output) { console.log("File content: " + output); }, function(error) { console.log(error); }); fileHandleWrite.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); }); fileHandleRead.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); });
Output example:
Number of bytes written: 29 Data has been flushed to system file buffer and now can be read File content: Lorem ipsum dolor sit amet... File handle closed File handle closed
-
sync
-
Synchronizes data to storage device.
void sync();
Since: 5.0
The sync function is intended to force a physical write of data from the buffer cache and to assure that after a system crash or other failure that all data up to the time of the sync() call is recorded on the disk.
Exceptions:
- WebAPIException
with error type IOError, if sync fails or any error related to file handle occurs.
Code example:
var dataToWrite = new Uint8Array([11, 21, 31, 71, 81, 91]); /* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); fileHandleWrite.writeData(dataToWrite); /* Calling sync() forces a physical write of data, so it is safe */ /* even after system crash or power shut down. */ fileHandleWrite.sync(); console.log("Data has been synced"); /* close() method provides the same functionality as sync() and ends access to file. */ fileHandleWrite.close();
Output example:
Data has been synced
- WebAPIException
-
syncNonBlocking
-
Synchronizes data to storage device.
void syncNonBlocking(optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);
Since: 5.0
The syncNonBlocking function is intended to force a physical write of data from the buffer cache and to assure that after a system crash or other failure that all data up to the time of the syncNonBlocking() execution is recorded on the disk.
Successful syncing invokes onsuccess function, if specified. In case of failure onerror function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if sync fails or any error related to file handle occurs.
This method is asynchronous. Its execution will occur in background and after all previously commissioned background jobs will finish.
Parameters:
- onsuccess [optional] [nullable]: Callback function to be invoked on success.
- onerror [optional] [nullable]: Callback function to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
var dataToWrite = new Uint8Array([11, 21, 31, 71, 81, 91]); /* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); fileHandleWrite.writeDataNonBlocking(dataToWrite, function(dataRead) { console.log("Write done"); }, function(error) { console.log(error); }); /* Calling syncNonBlocking() will force a physical write of data, so it will be safe */ /* even after system crash or power shut down. */ fileHandleWrite.syncNonBlocking( function() { console.log("Data has been synced"); }, function(error) { console.log(error); }); /* close() method provides the same functionality as sync() and ends access to file. */ fileHandleWrite.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); });
Output example:
Write done Data has been synced File handle closed
-
close
-
Closes file handle.
void close();
Since: 5.0
Closes the given file stream. Closing file guarantees writing changes made to FileHandle to the storage device. Further operations on this file handle are not allowed.
Remark: This method is synchronous. If any asynchronous method was called before close, close will block further instructions until all background jobs finish execution. Note, that if file handle functions are put into any callbacks and this callback was not yet called, synchronous close will wait only for already ordered background jobs to finish, preventing successful execution of any further operations on closed file handle.
Exceptions:
- WebAPIException
with error type IOError, if close fails or any error related to file handle occurs.
Code example:
/* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); fileHandleWrite.writeString("Lorem ipsum dolor sit amet..."); fileHandleWrite.close(); console.log("String has been written to the file"); /* 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"); var positionOfFileEnd = fileHandleRead.seek(0, "END"); console.log("Seek operation done. Position of file end: " + positionOfFileEnd); fileHandleRead.close(); console.log("File is now closed");
Output example:
String has been written to the file Seek operation done. Position of file end: 29 File is now closed
- WebAPIException
-
closeNonBlocking
-
Closes file handle.
void closeNonBlocking(optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);
Since: 5.0
Closes the given file stream. Closing file guarantees writing changes made to FileHandle to the storage device. Further operations on this file handle are not allowed.
Successful closing invokes onsuccess function, if specified. In case of failure onerror function is invoked, if specified.
The ErrorCallback is launched with these error types:
- IOError, if close fails or any error related to file handle occurs.
This method is asynchronous. Its execution will occur in background and after all previously commissioned background jobs will finish.
Parameters:
- onsuccess [optional] [nullable]: Callback function to be invoked on success.
- onerror [optional] [nullable]: Callback function to be invoked when an error occurs.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
Code example:
/* Opening file for write - file is created if not exists, */ /* otherwise existing file is truncated. */ var fileHandleWrite = tizen.filesystem.openFile("documents/file", "w"); fileHandleWrite.writeStringNonBlocking("Lorem ipsum dolor sit amet...", function(bytesCount) { console.log("Number of bytes written: " + bytesCount); }, function(error) { console.log(error); }); fileHandleWrite.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); }); /* 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"); var positionOfFileEnd = fileHandleRead.seekNonBlocking(0, function(new_position) { console.log("Moved to position: " + new_position); }, function(error) { console.log(error); }, "END"); fileHandleRead.closeNonBlocking( function() { console.log("File handle closed"); }, function(error) { console.log(error); });
Output example:
Number of bytes written: 29 File handle closed Moved to position: 29 File handle closed
2.5. FileFilter
dictionary FileFilter { DOMString name; boolean isFile; boolean isDirectory; Date startModified; Date endModified; Date startCreated; Date endCreated; };
Since: 1.0
When this dictionary is passed to a method, the result-set of the method will only contain file item entries that match the attribute values of the filter.
A file item only matches the FileFilter object if all of the defined filter's attribute values match all of the file item's attributes (only matching values other than undefined or null). This is similar to a SQL's "AND" operation.
An attribute of the file entry matches the FileFilter attribute value in accordance with the following rules:
- For FileFilter attributes of type DOMString, an entry matches this value only if its corresponding attribute is an exact match. If the filter contains U+0025 "PERCENT SIGN" it is interpreted as a wildcard character and "%" matches any string of any length, including no length. If wildcards are used, the behavior is similar to the LIKE condition in SQL. To specify that a "PERCENT SIGN" character is to be considered literally instead of interpreting it as a wildcard, developers can escape it with the backslash character (\). Please, remember that the backslash character has to be escaped itself, to not to be removed from the string - proper escaping of the "PERCENT SIGN" in JavaScript string requires preceding it with double backslash ("\\%"). The matching is not case sensitive, such as "FOO" matches a "foo" or an "f%" filter.
-
For File entry attributes of type Date, attributes start and end are included to allow filtering of File entries between two supplied dates. If either or both of these attributes are specified, the following rules apply:
A) If both start and end dates are specified (that is, other than null), a File entry matches the filter if its corresponding attribute is the same as either start or end or between the two supplied dates (that is, after start and before end).
B) If only the start attribute contains a value (other than null), a File entry matches the filter if its corresponding attribute is later than or equal to the start one.
C) If only the end date contains a value (other than null), a file matches the filter if its corresponding attribute is earlier than or equal to the end date.
Dictionary members
- DOMString name
-
The File name attribute filter.
Files that have a name that corresponds with this attribute (either exactly or with the specified wildcards) match this filtering criteria.
Since: 1.0
- boolean isFile
-
If true match only files. If false do not match files. May be undefined.
Since: 5.0
- boolean isDirectory
-
If true match only directories, If false do not match directories. May be undefined.
Since: 5.0
- Date startModified
-
The File modified attribute filter.
Files with modified date later than this attribute or equal to it match the filtering criteria.
Since: 1.0
- Date endModified
-
The File modified attribute filter.
Files with modified date earlier than this attribute or equal to it match the filtering criteria.
Since: 1.0
- Date startCreated
-
The File created attribute filter.
Files with created date later than this attribute or equal to it match the filtering criteria.
Since: 1.0
- Date endCreated
-
The File created attribute filter.
Files with created date earlier than this attribute or equal to it match the filtering criteria.
Since: 1.0
2.6. FileSystemStorageArraySuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface FileSystemStorageArraySuccessCallback { void onsuccess(FileSystemStorage[] storages); };
Since: 1.0
It is used in asynchronous operations, such as FileSystemManager.listStorages().
Methods
-
onsuccess
-
Called when the asynchronous call completes successfully.
void onsuccess(FileSystemStorage[] storages);
Since: 1.0
Parameters:
- storages: List of available storage devices.
2.7. FileSystemStorageSuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface FileSystemStorageSuccessCallback { void onsuccess(FileSystemStorage storage); };
Since: 1.0
It is used in asynchronous operations, such as FileSystemManager.getStorage() and FileSystemManager.addStorageStateChangeListener().
Methods
-
onsuccess
-
Called when the asynchronous call completes successfully.
void onsuccess(FileSystemStorage storage);
Since: 1.0
Parameters:
- storage: Storage device structure.
2.8. PathSuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface PathSuccessCallback { void onsuccess(Path path); };
Since: 5.0
It is used in asynchronous operations of the FileSystemManager interface.
Methods
-
onsuccess
-
Called when the asynchronous call completes successfully.
void onsuccess(Path path);
Since: 5.0
Parameters:
- path: Path to created or changed resource on the filesystem. In case of deletion, path to parent of the deleted resource is given.
2.9. SeekSuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface SeekSuccessCallback { void onsuccess(long long position); };
Since: 5.0
It is used in asynchronous operation FileHandle.seekNonBlocking().
2.10. ReadStringSuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface ReadStringSuccessCallback { void onsuccess(DOMString string); };
Since: 5.0
It is used in asynchronous operation FileHandle.readStringNonBlocking().
2.11. WriteStringSuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface WriteStringSuccessCallback { void onsuccess(long long bytesCount); };
Since: 5.0
It is used in asynchronous operation FileHandle.writeStringNonBlocking().
2.12. ReadBlobSuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface ReadBlobSuccessCallback { void onsuccess(Blob blob); };
Since: 5.0
It is used in asynchronous operation FileHandle.readBlobNonBlocking().
Methods
-
onsuccess
-
Called when the asynchronous call completes successfully.
void onsuccess(Blob blob);
Since: 5.0
Parameters:
- blob: Blob object with file content.
2.13. ReadDataSuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface ReadDataSuccessCallback { void onsuccess(Uint8Array data); };
Since: 5.0
It is used in asynchronous operation FileHandle.readDataNonBlocking().
Methods
-
onsuccess
-
Called when the asynchronous call completes successfully.
void onsuccess(Uint8Array data);
Since: 5.0
Parameters:
- data: A TypedArray with file content.
2.14. ListDirectorySuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface ListDirectorySuccessCallback { void onsuccess(DOMString[] names, Path path); };
Since: 5.0
This callback interface specifies a success callback with a function taking an array of strings as input argument. It is used in asynchronous operation FileSystemManager.listDirectory().
Methods
-
onsuccess
-
Called when the asynchronous call completes successfully.
void onsuccess(DOMString[] names, Path path);
Since: 5.0
Parameters:
- names: File or directory names resulting from the asynchronous call.
- path: Path to listed directory.
3. Full WebIDL
module Filesystem { typedef DOMString Path; typedef Blob Blob; enum FileMode { "a", "r", "rw", "rwo", "w" }; enum FileSystemStorageType { "INTERNAL", "EXTERNAL" }; enum FileSystemStorageState { "MOUNTED", "REMOVED", "UNMOUNTABLE" }; enum BaseSeekPosition { "BEGIN", "CURRENT", "END" }; dictionary FileFilter { DOMString name; boolean isFile; boolean isDirectory; Date startModified; Date endModified; Date startCreated; Date endCreated; }; Tizen implements FileSystemManagerObject; [NoInterfaceObject] interface FileSystemManagerObject { readonly attribute FileSystemManager filesystem; }; [NoInterfaceObject] interface FileSystemManager { readonly attribute long maxNameLength; readonly attribute long maxPathLength; FileHandle openFile(Path path, FileMode openMode, optional boolean makeParents) raises(WebAPIException); void createDirectory(Path path, optional boolean makeParents, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void deleteFile(Path path, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void deleteDirectory(Path path, optional boolean recursive, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void copyFile(Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void copyDirectory(Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void moveFile(Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void moveDirectory(Path sourcePath, Path destinationPath, optional boolean overwrite, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void rename(Path path, DOMString newName, optional PathSuccessCallback? successCallback, optional ErrorCallback? errorCallback) raises(WebAPIException); void listDirectory(Path path, ListDirectorySuccessCallback successCallback, optional ErrorCallback? errorCallback, optional FileFilter? filter) raises(WebAPIException); DOMString toURI(Path path) raises(WebAPIException); boolean isFile(Path path) raises(WebAPIException); boolean isDirectory(Path path) raises(WebAPIException); boolean pathExists(Path path) raises(WebAPIException); DOMString getDirName(DOMString path); void getStorage(DOMString label, FileSystemStorageSuccessCallback onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void listStorages(FileSystemStorageArraySuccessCallback onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); long addStorageStateChangeListener(FileSystemStorageSuccessCallback onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void removeStorageStateChangeListener(long watchId) raises(WebAPIException); }; [NoInterfaceObject] interface FileSystemStorage { readonly attribute DOMString label; readonly attribute FileSystemStorageType type; readonly attribute FileSystemStorageState state; }; [NoInterfaceObject] interface FileHandle { readonly attribute Path path; long long seek(long long offset, optional BaseSeekPosition whence) raises(WebAPIException); void seekNonBlocking(long long offset, optional SeekSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional BaseSeekPosition whence) raises(WebAPIException); DOMString readString(optional long long? count, optional DOMString inputEncoding) raises(WebAPIException); void readStringNonBlocking(optional ReadStringSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional long long count, optional DOMString inputEncoding) raises(WebAPIException); long long writeString(DOMString inputString, optional DOMString outputEncoding) raises(WebAPIException); void writeStringNonBlocking(DOMString inputString, optional WriteStringSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional DOMString outputEncoding) raises(WebAPIException); Blob readBlob(optional long long size) raises(WebAPIException); void readBlobNonBlocking(optional ReadBlobSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional long long? size) raises(WebAPIException); void writeBlob(Blob blob) raises(WebAPIException); void writeBlobNonBlocking(Blob blob, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); Uint8Array readData(optional long long size) raises(WebAPIException); void readDataNonBlocking(optional ReadDataSuccessCallback? onsuccess, optional ErrorCallback? onerror, optional long long? size) raises(WebAPIException); void writeData(Uint8Array data) raises(WebAPIException); void writeDataNonBlocking(Uint8Array data, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void flush() raises(WebAPIException); void flushNonBlocking(optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void sync() raises(WebAPIException); void syncNonBlocking(optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void close() raises(WebAPIException); void closeNonBlocking(optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); }; [Callback=FunctionOnly, NoInterfaceObject] interface FileSystemStorageArraySuccessCallback { void onsuccess(FileSystemStorage[] storages); }; [Callback=FunctionOnly, NoInterfaceObject] interface FileSystemStorageSuccessCallback { void onsuccess(FileSystemStorage storage); }; [Callback=FunctionOnly, NoInterfaceObject] interface PathSuccessCallback { void onsuccess(Path path); }; [Callback=FunctionOnly, NoInterfaceObject] interface SeekSuccessCallback { void onsuccess(long long position); }; [Callback=FunctionOnly, NoInterfaceObject] interface ReadStringSuccessCallback { void onsuccess(DOMString string); }; [Callback=FunctionOnly, NoInterfaceObject] interface WriteStringSuccessCallback { void onsuccess(long long bytesCount); }; [Callback=FunctionOnly, NoInterfaceObject] interface ReadBlobSuccessCallback { void onsuccess(Blob blob); }; [Callback=FunctionOnly, NoInterfaceObject] interface ReadDataSuccessCallback { void onsuccess(Uint8Array data); }; [Callback=FunctionOnly, NoInterfaceObject] interface ListDirectorySuccessCallback { void onsuccess(DOMString[] names, Path path); }; };