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
- ringtones - the location for ringtones (read-only location)
- 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.
To access specific locations apart from those specified above, a file handle must be retrieved using the filesystem.resolve() call. A file handle represents either a file or a directory:
- For a file, the isFile attribute is set to true.
- For a directory, the isDirectory attribute is set to true.
A file can be opened for both read and write operations, using a FileStream handle. A list of files and sub-directories can be obtained from a directory and a resolve method exists to resolve files or sub-directories more conveniently than processing directory listings.
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.
- Storage privileges are privacy-related privileges and there is a need of asking user directly with proper pop-up. Please refer to Privacy Privilege API for more details.
For more information on the Filesystem features, see File System Guide.
Since: 1.0
Table of Contents
- 1. Type Definitions
- 1.1. FileMode
- 1.2. FileSystemStorageType
- 1.3. FileSystemStorageState
- 2. Interfaces
- 2.1. FileSystemManagerObject
- 2.2. FileSystemManager
- 2.3. FileSystemStorage
- 2.4. File
- 2.5. FileFilter
- 2.6. FileStream
- 2.7. FileSuccessCallback
- 2.8. FileSystemStorageArraySuccessCallback
- 2.9. FileSystemStorageSuccessCallback
- 2.10. FileStringSuccessCallback
- 2.11. FileStreamSuccessCallback
- 2.12. FileArraySuccessCallback
- 3. Full WebIDL
Summary of Interfaces and Methods
Interface | Method |
---|---|
FileSystemManagerObject | |
FileSystemManager |
void resolve (DOMString location, FileSuccessCallback onsuccess, optional ErrorCallback? onerror, optional FileMode? mode)
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 | |
File |
DOMString toURI ()
void listFiles (FileArraySuccessCallback onsuccess, optional ErrorCallback? onerror, optional FileFilter? filter)
void openStream (FileMode mode, FileStreamSuccessCallback onsuccess, optional ErrorCallback? onerror, optional DOMString? encoding)
void readAsText (FileStringSuccessCallback onsuccess, optional ErrorCallback? onerror, optional DOMString? encoding)
void copyTo (DOMString originFilePath, DOMString destinationFilePath, boolean overwrite, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror)
void moveTo (DOMString originFilePath, DOMString destinationFilePath, boolean overwrite, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror)
File createDirectory (DOMString dirPath)
File createFile (DOMString relativeFilePath)
void deleteDirectory (DOMString directoryPath, boolean recursive, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror)
void deleteFile (DOMString filePath, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror)
|
FileFilter | |
FileStream |
void close ()
DOMString read (long charCount)
octet[] readBytes (long byteCount)
DOMString readBase64 (long byteCount)
void write (DOMString stringData)
void writeBytes (octet[] byteData)
void writeBase64 (DOMString base64Data)
|
FileSuccessCallback | |
FileSystemStorageArraySuccessCallback | void onsuccess (FileSystemStorage[] storages) |
FileSystemStorageSuccessCallback | void onsuccess (FileSystemStorage storage) |
FileStringSuccessCallback | void onsuccess (DOMString fileStr) |
FileStreamSuccessCallback | void onsuccess (FileStream filestream) |
FileArraySuccessCallback |
1. Type Definitions
1.1. FileMode
enum FileMode { "a", "r", "rw", "w" };
Since: 1.0
The file modes defined by this enumerator are:
- a - append access.
- r - read-only access.
- rw - read and write access.
- w - write access.
1.2. 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.3. 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.
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 maxPathLength; void resolve(DOMString location, FileSuccessCallback onsuccess, optional ErrorCallback? onerror, optional FileMode? mode) raises(WebAPIException); 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.
Code example:
var documentsDir; function onsuccess(files) { for (var i = 0; i < files.length; i++) { console.log("File name is " + files[i].name); } var testFile = documentsDir.createFile("test.txt"); testFile.openStream("w", function(fs) { fs.write("HelloWorld"); fs.close(); }, function(error) { console.log("Error " + error.message); }, "UTF-8"); } function onerror(error) { console.log( "The error " + error.message + " occurred when listing the files in the selected folder"); } tizen.filesystem.resolve("documents", function(dir) { documentsDir = dir; dir.listFiles(onsuccess, onerror); }, function(error) { console.log("Error " + error.message); }, "rw");
Attributes
-
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
-
resolve
-
Resolves a location to a file handle after validating it.
void resolve(DOMString location, FileSuccessCallback onsuccess, optional ErrorCallback? onerror, optional FileMode? mode);
Since: 1.0
A location can contain a virtual path like "documents/some_file.txt" or a file URI like "file:///my_strange_path/some_file.png". A location is not allowed to contain the "." or ".." directory entries inside its value.
The list of root locations that must be supported by a compliant implementation are:
- documents - The default folder in which text documents (such as pdf, doc...) are stored by default in a device. For example, in some platforms it corresponds to the "My Documents" folder.
- images - The default folder in which still images, like pictures (in formats including jpg, gif, png, etc.), are stored in the device by default. For example, in some platforms it corresponds to the "My Images" folder.
- music - The default folder in which sound clips (in formats including mp3, aac, etc.) are stored in the device by default. For example, in some platforms it corresponds to the "My Music" folder.
- videos - The default folder in which video clips (in formats including avi, mp4, etc.) are stored in the device by default. For example, in some platforms it corresponds to the "My Videos" folder.
- downloads - The default folder in which downloaded files (from sources including browser, e-mail client, etc.) are stored by default in the device. For example, in some platforms it corresponds to the "Downloads" folder.
- ringtones - The default folder in which ringtones (such as mp3, etc.) are stored in the device.
- camera - The default folder in which pictures and videos taken by a device are stored.
- wgt-package - The read-only folder to which the content of a widget file is extracted.
- wgt-private - The private folder in which a widget stores its information. This folder must be accessible only to the same widget and other widgets or applications must not be able to access the stored information.
- wgt-private-tmp - Temporary, the private folder in which a widget can store data that is available during a widget execution cycle. Content of this folder can be removed from this directory when the widget is closed or the Web Runtime is restarted. This folder must be accessible only to the same widget and other widgets or applications must not be able to access it.
The mode parameter specifies whether the resulting File object has read-only access (r access), read and write access (rw access), append access (a access), or write access (w access) to the root location containing directory tree. Permission for the requested access is obtained from the security framework. Once the resulting File object has access, access is inherited by any other File objects that are derived from this instance without any further reference to the security framework, as noted in descriptions of certain methods of File.
The ErrorCallback is launched with these error types:
- InvalidValuesError - If any of the input parameters contains an invalid value. For example, the mode is w for the read-only virtual roots (wgt-package and ringtones).
- NotFoundError - If the location input argument does not correspond to a valid location.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Remark: camera location is supported since Tizen 2.3. If a device does not support camera, NotSupportedError will be thrown.
Parameters:
- location: Location to resolve that can be a virtual path or file URI.
- onsuccess: Callback method to be invoked when the location has been successfully resolved, passing the newly created File object.
- onerror [optional] [nullable]: Callback method to be invoked when an error has occurred.
-
mode [optional] [nullable]:
Optional value to indicate the file access mode on all files and directories that can be reached from the File object passed to onsuccess.
Default value of this parameter is rw if absent or null.
Exceptions:
- WebAPIException
with error type NotSupportedError, if this feature is not supported (e.g. in the case of "camera" virtual path if the device does not support camera).
with error type SecurityError, if the application does not have the privilege to call this method.
with error type TypeMismatchError, if any of the input parameters is not compatible with the expected type for that parameter.
Code example:
tizen.filesystem.resolve("images", function(dir) { console.log("Images are stored in " + dir.path); }, function(e) { console.log("Error: " + e.message); }, "r");
-
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.
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.
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.
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.
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. File
[NoInterfaceObject] interface File { readonly attribute File? parent; readonly attribute boolean readOnly; readonly attribute boolean isFile; readonly attribute boolean isDirectory; readonly attribute Date? created; readonly attribute Date? modified; readonly attribute DOMString path; readonly attribute DOMString name; readonly attribute DOMString fullPath; readonly attribute unsigned long long fileSize; readonly attribute long length; DOMString toURI() raises(WebAPIException); void listFiles(FileArraySuccessCallback onsuccess, optional ErrorCallback? onerror, optional FileFilter? filter) raises(WebAPIException); void openStream(FileMode mode, FileStreamSuccessCallback onsuccess, optional ErrorCallback? onerror, optional DOMString? encoding) raises(WebAPIException); void readAsText(FileStringSuccessCallback onsuccess, optional ErrorCallback? onerror, optional DOMString? encoding) raises(WebAPIException); void copyTo(DOMString originFilePath, DOMString destinationFilePath, boolean overwrite, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void moveTo(DOMString originFilePath, DOMString destinationFilePath, boolean overwrite, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); File createDirectory(DOMString dirPath) raises(WebAPIException); File createFile(DOMString relativeFilePath) raises(WebAPIException); File resolve(DOMString filePath) raises(WebAPIException); void deleteDirectory(DOMString directoryPath, boolean recursive, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void deleteFile(DOMString filePath, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); };
Since: 1.0
The file object permissions for the file object location and tree rooted at that location depend upon the mode defined in the resolve method. When a File object creates a child File object, the new File object inherits its access rights from the parent object without any reference to the security framework, as noted in certain methods of File.
A file handle represents either a file or a directory:
- For a file, the isFile attribute is set to true.
- For a directory, the isDirectory attribute is set to true.
A file can be opened for both read and write operations, using a FileStream handle. A list of files and sub-directories can be obtained from a directory and a resolve method exists to resolve files or sub-directories more conveniently than processing directory listings.
A file handle representing a file can be opened for I/O operations, such as reading and writing.
A file handle representing a directory can be used for listing all files and directories rooted as the file handle location.
Code example:
function onsuccess(files) { for (var i = 0; i < files.length; i++) { /* Alerts each name of dir's content. */ console.log(files[i].name); } } function onerror(error) { console.log( "The error " + error.message + " occurred when listing the files in the selected folder"); } /* List directory content. */ dir.listFiles(onsuccess, onerror);
Attributes
-
readonly
File parent [nullable]The parent directory handle.
This attribute is set to null if there is no parent directory. This also implies that this directory represents a root location.
Since: 1.0
Code example:
/* List directory content. */ dir.listFiles(onsuccess, onerror); function onsuccess(files) { for (var i = 0; i < files.length; i++) { /* Prints the file parent, must contain the */ /* same value for all the files in the loop. */ console.log("All the files should have the same parent " + files[i].parent); } } function onerror(error) { console.log( "The error " + error.message + " occurred when listing the files in the selected folder"); }
-
readonly
boolean readOnlyThe file/directory access state in the filesystem.
This attribute is set to:
- true - if object has read-only access at its location.
- false - if object has write access at its location.
This attribute represents the actual state of a file or directory in the filesystem. Its value is not affected by the mode used in FileSystemManager.resolve() that was used to create the File object from which this File object was obtained.
Since: 1.0
Code example:
/* Lists directory content. */ dir.listFiles(onsuccess, onerror); function onsuccess(files) { for (var i = 0; i < files.length; i++) { if (files[i].readOnly) console.log("Cannot write to file " + files[i].name); else console.log("Can write to file " + files[i].name); } } function onerror(error) { console.log( "The error " + error.message + " occurred when listing the files in the selected folder"); }
-
readonly
boolean isFileThe flag indicating whether it is a file.
This attribute can have the following values:
- true if this handle is a file
- false if this handle is a directory
Since: 1.0
-
readonly
boolean isDirectoryThe flag indicating whether it is a directory.
This attribute can have the following values:
- true if this handle is a directory
- false if this handle is a file
Since: 1.0
-
readonly
Date created [nullable]The timestamp when a file is first created in the filesystem.
This timestamp is equivalent to the timestamp when a call to createFile() succeeds.
If the platform does not support this attribute, it will be null.
It is unspecified and platform-dependent if the creation timestamp changes when a file is moved.
Since: 1.0
-
readonly
Date modified [nullable]The timestamp when the most recent modification is made to a file, usually when the last write operation succeeds.
Opening a file for reading does not change the modification timestamp.
If the platform does not support this attribute, it will be null.
It is unspecified and platform-dependent if the modified timestamp changes when a file is moved.
Since: 1.0
Code example:
console.log(file.modified); /* Displays the modification timestamp. */
-
readonly
DOMString pathThe path of a file after excluding its file name.
It begins with the name of the root containing the file, followed by the path, including the directory containing the file, but excluding the file name.
Except in some special cases of the File representing the root itself, the last character is always "/".
For example, if a file is located at music/ramones/volume1/RockawayBeach.mp3, the path is music/ramones/volume1/.
For example, if a directory is located at music/ramones/volume1, the path is music/ramones/.
For the virtual roots, the path is same as the name of the virtual root. For example, if the root is music, then the path is music. If the root is documents, then the path is documents.
Since: 1.0
Code example:
console.log(file.path); /* Must be music/ if the file is music/foo.mp3. */
-
readonly
DOMString nameThe file name after excluding the root name and any path components.
This is the name of this file, excluding the root name and any other path components.
For example, if a file is located at music/ramones/volume1/RockawayBeach.mp3, the name is "RockawayBeach.mp3".
For example, if a directory is located at music/ramones/volume1, the name is be "volume1".
For the special case of the root itself, the name is an empty string.
Since: 1.0
Code example:
/* Must be foo.mp3 if the file path is music/foo.mp3. */ console.log(file.name);
-
readonly
DOMString fullPathThe full path of a file.
It begins with the name of the root containing the file, and including the name of the file or directory itself.
For instance, if the RockawayBeach.mp3 file is located at music/ramones/volume1/, then the fullPath is music/ramones/volume1/RockawayBeach.mp3.
For a directory, if the volume1 directory is located at music/ramones/, then the fullPath is music/ramones/volume1.
For the special case of the root itself, if the root is music, then the fullPath is music.
The fullPath is always equal to path + name.
Since: 1.0
Code example:
/* Must be music/track1.mp3 if the file is music/track1.mp3. */ console.log(file.fullPath);
-
readonly
unsigned long long fileSizeThe size of this file, in bytes.
If an attempt to read this attribute for a directory is made, undefined is returned. To retrieve the number of files and directories contained in the directory, use the length attribute.
Since: 1.0
Code example:
/* Displays the file size. */ console.log(file.fileSize);
-
readonly
long lengthThe number of files and directories contained in a file handle.
If an attempt to read this attribute for a file is made, undefined is returned. To retrieve the size of a file, use the fileSize attribute.
Since: 1.0
Code example:
/* "3" if the directory contains two files and one sub-directory. */ console.log(file.length);
Methods
-
toURI
-
Returns a URI for a file to identify an entry (such as using it as the src attribute on an HTML img element). The URI has no specific expiration, it should be valid at least as long as the file exists.
DOMString toURI();
Since: 1.0
If that URI corresponds to any of the public virtual roots (that is images, videos, music, documents and downloads) the URI must be globally unique and could be used by any widget.
If that URI corresponds to a file located in any a widget's private areas (such as wgt-package, wgt-private, wgt-private-tmp), the generated URI must be unique for that file and for the widget making the request (such as including some derived from the widget ID in the URI). These URIs must not be accessible to other widgets, apart from the one invoking this method.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Return value:
-
DOMString:
URI that identifies the file or null if an error occurs.
Exceptions:
- WebAPIException
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, if any other error occurred.
Code example:
tizen.filesystem.resolve("music/ramones/RockawayBeach.mp3", function(file) { var audio = new Audio(file.toURI()); audio.play(); console.log(file.toURI()); });
- WebAPIException
-
listFiles
-
Lists all files in a directory.
void listFiles(FileArraySuccessCallback onsuccess, optional ErrorCallback? onerror, optional FileFilter? filter);
Since: 1.0
The list of files is passed as a File[] in onsuccess() and contains directories and files. However, the directories "." and ".." must not be returned. Each File object that is part of the array must inherit all the access rights (that is, one of the values in FileMode) from the File object in which this method is invoked.
If the filter is passed and contains valid values, only those directories and files in the directory that match the filter criteria specified in the FileFilter interface must be returned in the onsuccess() method. If no filter is passed, the filter is null or undefined, or the filter contains invalid values, 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 any files or directories, the onsuccess() is invoked with an empty array.
The ErrorCallback is launched with these error types:
- IOError - If the operation is launched on a file (not a directory).
- InvalidValuesError - If any of the input parameters contain 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 the list operation has been successfully completed.
- onerror [optional] [nullable]: Callback method to be invoked when an error has occurred.
- filter [optional] [nullable]: Criteria to restrict the listed files.
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.
Code example:
function onsuccess(files) { console.log("There are " + files.length + " in the selected folder"); } function onerror(error) { console.log( "The error " + error.message + " occurred when listing the files in the selected folder"); } tizen.filesystem.resolve("documents", function(dir) { dir.listFiles(onsuccess, onerror); }, function(e) { console.log("Error " + e.message); }, "r");
-
openStream
-
Opens the file in the given mode supporting a specified encoding.
void openStream(FileMode mode, FileStreamSuccessCallback onsuccess, optional ErrorCallback? onerror, optional DOMString? encoding);
Since: 1.0
This operation is performed asynchronously. If the file is opened successfully, the onsuccess() method is invoked with a FileStream that can be used for reading and writing the file, depending on the mode. The returned FileStream instance includes a file pointer, which represents the current position in the file. The file pointer, by default, is at the start of the file, except in the case of opening a file in append ("a") mode, in which case the file pointer points to the end of the file.
The ErrorCallback is launched with these error types:
- InvalidValuesError - If any of the input parameters contains an invalid value.
- IOError - The operation is launched on a directory (not a file), the file is not valid or it does not exist.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Parameters:
-
mode:
Mode in which the file is opened
"r" for reading
"a" for appending
"w" for [over]writing
"rw" for reading and writing
- onsuccess: Callback method to be invoked when a file has been opened.
- onerror [optional] [nullable]: Callback method to be invoked when an error has occurred.
-
encoding [optional] [nullable]:
Encoding to use for read/write operations on the file, at least the following encodings must be supported:
"UTF-8" default encoding
"ISO-8859-1" latin1 encoding
If no encoding is passed by the developer, then the default platform encoding must be used.
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.
Code example:
var documentsDir; function onsuccess(files) { for (var i = 0; i < files.length; i++) { console.log("File Name is " + files[i].name); /* Displays file name. */ } var testFile = documentsDir.createFile("test.txt"); if (testFile != null) { testFile.openStream("w", function(fs) { fs.write("HelloWorld"); fs.close(); }, function(e) { console.log("Error " + e.message); }, "UTF-8"); } } function onerror(error) { console.log( "The error " + error.message + " occurred when listing the files in the selected folder"); } tizen.filesystem.resolve("documents", function(dir) { documentsDir = dir; dir.listFiles(onsuccess, onerror); }, function(e) { console.log("Error " + e.message); }, "rw");
-
readAsText
-
Reads the content of a file as a DOMString.
void readAsText(FileStringSuccessCallback onsuccess, optional ErrorCallback? onerror, optional DOMString? encoding);
Since: 1.0
If the operation is successfully executed, the onsuccess() method is invoked and a DOMString is passed as input parameter that represents the file content in the format determined by the encoding parameter.
The ErrorCallback is launched with these error types:
- InvalidValuesError - If any of the input parameters contains an invalid value.
- IOError - If the operation is launched on a directory (not a file), the file is not valid, or the file does not exist.
- 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 file has been successfully read.
- onerror [optional] [nullable]: Callback method to be invoked when an error occurs while reading a file.
-
encoding [optional] [nullable]:
Encoding for read/write operations on a file, at least the following encodings must be supported:
"UTF-8" default encoding
"ISO-8859-1" latin1 encoding
If no encoding is passed by the developer, then the default platform encoding must be used.
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.
Code example:
var documentsDir; function onsuccess(files) { for (var i = 0; i < files.length; i++) { console.log("File Name is " + files[i].name); /* Displays file name. */ if (files[i].isDirectory == false) { files[i].readAsText( function(str) { console.log("The file content " + str); }, function(e) { console.log("Error " + e.message); }, "UTF-8"); } } } function onerror(error) { console.log( "The error " + error.message + " occurred when listing the files in the selected folder"); } tizen.filesystem.resolve("documents", function(dir) { documentsDir = dir; dir.listFiles(onsuccess, onerror); }, function(e) { console.log("Error " + e.message); }, "rw");
-
copyTo
-
Copies (and overwrites if possible and specified) a file or a directory from a specified location to another specified location.
void copyTo(DOMString originFilePath, DOMString destinationFilePath, boolean overwrite, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);
Since: 1.0
The copy of the file or directory identified by the originFilePath parameter must be created in the path passed in the destinationFilePath parameter.
The file or directory to copy must be under the Directory from which the method is invoked, otherwise the operation must not be performed.
If the copy is performed successfully, the onsuccess() method is invoked.
The ErrorCallback is launched with these error types:
- InvalidValuesError - If any of the input parameters contains an invalid value.
- NotFoundError - If the originFilePath does not correspond to a valid file or destinationPath is not a valid path.
- IOError - If the file in which the copyTo() method is invoked is a file (and not a directory), originFilePath corresponds to a file or directory in use by another process, overwrite parameter is false and destinationFilePath corresponds to an existing file or directory.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- originFilePath: Origin full virtual file or directory path and it must be under the current directory.
- destinationFilePath: New full virtual file path or directory path.
-
overwrite:
Attribute to determine whether overwriting is allowed or not
If set to true, it enforces overwriting an existing file. - onsuccess [optional] [nullable]: Callback method to be invoked when the file has been copied.
- onerror [optional] [nullable]: Callback method to be invoked when an error has occurred.
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.
Code example:
var documentsDir; function onsuccess(files) { for (var i = 0; i < files.length; i++) { if (files[i].isDirectory == false) { documentsDir.copyTo(files[i].fullPath, "images/backup/" + files[i].name, false, function() { console.log("File copied"); }); } } } function onerror(error) { console.log( "The error " + error.message + " occurred when listing the files in the selected folder"); } tizen.filesystem.resolve("documents", function(dir) { documentsDir = dir; dir.listFiles(onsuccess, onerror); }, function(e) { console.log("Error " + e.message); }, "rw");
-
moveTo
-
Moves (and overwrites if possible and specified) a file or a directory from a specified location to another. This operation is different from instantiating copyTo() and then deleting the original file, as on certain platforms, this operation does not require extra disk space.
void moveTo(DOMString originFilePath, DOMString destinationFilePath, boolean overwrite, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);
Since: 1.0
The file or directory identified by the originFilePath parameter is moved to the path passed in the destinationFilePath parameter.
The file to move must be under the directory from which the method is invoked, else the operation can not be performed.
If the file or directory is moved successfully, the onsuccess() method is invoked.
The ErrorCallback is launched with these error types:
- InvalidValuesError - If any of the input parameters contains an invalid value.
- NotFoundError - If originFilePath does not correspond to a valid file or destinationPath is not a valid path.
- IOError - If the File in which the moveTo() method is invoked is a file (not a directory), originFilePath corresponds to a file or directory in use by another process, overwrite parameter is false and destinationFilePath corresponds to an existing file or directory.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- originFilePath: Origin full virtual file or directory path and it must be under the current directory.
- destinationFilePath: New full virtual file path or directory path.
-
overwrite:
Flag indicating whether to overwrite an existing file.
When set to true, the files can be overwritten. - onsuccess [optional] [nullable]: Callback method to be invoked when the file has been moved.
- onerror [optional] [nullable]: Callback method to be invoked when an error has occurred.
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.
Code example:
var documentsDir; function onsuccess(files) { for (var i = 0; i < files.length; i++) { if (files[i].isDirectory == false) { documentsDir.moveTo( files[i].fullPath, "images/newFolder/" + files[i].name, false, function() { console.log("File moved"); }); } } } function onerror(error) { console.log( "The error " + error.message + " occurred during listing the files in the selected folder"); } tizen.filesystem.resolve("documents", function(dir) { documentsDir = dir; dir.listFiles(onsuccess, onerror); }, function(e) { console.log("Error " + e.message); }, "rw");
-
createDirectory
-
Creates a new directory.
File createDirectory(DOMString dirPath);
Since: 1.0
A new directory will be created relative to the current directory that this operation is performed on. The implementation will attempt to create all necessary sub-directories specified in the dirPath, as well. The use of "." or ".." in path components is not supported.
This operation can only be performed on file handles that represent directories (that is, isDirectory == true).
If the directory is successfully created, it will be returned.
In case the directory cannot be created, an error must be thrown with the appropriate error type.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- dirPath: Relative directory path and it only contains characters supported by the underlying filesystem.
Return value:
-
File:
File handle of the new directory.
The new File object has "rw" access rights, as it inherits this from the File object on which the createDirectory() method is called.
Exceptions:
- WebAPIException
with error type IOError, if the dirPath already exists, if the file in which the createDirectory() method is invoked is a file (and not a directory).
with error type InvalidValuesError, if the dirPath does not contain a valid path.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, if any other error occurs.
Code example:
var dir; /* Directory object obtained from filesystem API. */ var newDir = dir.createDirectory("newDir"); var anotherNewDir = dir.createDirectory("newDir1/subNewDir1");
-
createFile
-
Creates a empty new file in a specified location that is relative to the directory indicated by current File object's path attribute.
File createFile(DOMString relativeFilePath);
Since: 1.0
The use of "." or ".." in path components is not supported. This operation can only be performed on file handlers that represent a directory (that is, isDirectory == true).
If the file is successfully created, a file handle must be returned by this method.
In case the file cannot be created, an error must be thrown with the appropriate error type.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- relativeFilePath: New file path and it should only contain characters supported by the underlying filesystem.
Return value:
-
File:
File handle for the new empty file.
The new File object has "rw" access rights, as it inherits this from the File object on which the createFile() method is
called.
Exceptions:
- WebAPIException
with error type IOError, if relativeFilePath already exists, if the File in which the createFile() method is invoked is a file (not a directory).
with error type InvalidValuesError, if relativeFilePath contains an invalid value.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, if any other error occurs.
Code example:
var newFile = dir.createFile("newFilePath");
-
resolve
-
Resolves an existing file or directory relative to the current directory this operation is performed on and returns a file handle for it.
File resolve(DOMString filePath);
Since: 1.0
The filePath is not allowed to contain the "." or ".." directory entries inside its value.
The encoding of file paths is UTF-8.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Parameters:
- filePath: Relative file path or file URI to resolve.
Return value:
-
File:
File handle of the file.
The new File object inherits its access rights from the File object on which this resolve() method is called.
Exceptions:
- WebAPIException
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type InvalidValuesError, if the file path contains an invalid value.
with error type IOError, if the method is executed in a File object that does not represent a directory (that is, isDirectory attribute is false).
with error type NotFoundError, if a file does not exist for the passed file path.
with error type SecurityError, if the application does not have the privilege to call this method.
with error type UnknownError, if any other error occurs.
Code example:
var file; /* Resolves helloWorld.doc file that is located in the */ /* documents root location. */ tizen.filesystem.resolve("documents", function(dir) { file = dir.resolve("helloWorld.doc"); }, function(e) { console.log("Error " + e.message); }, "rw");
-
deleteDirectory
-
Deletes a specified directory and directory tree if specified.
void deleteDirectory(DOMString directoryPath, boolean recursive, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);
Since: 1.0
This method attempts to asynchronously delete a directory or directory tree under the current directory.
If the recursive parameter is set to true, all the directories and files under the specified directory must be deleted. If the recursive parameter is set to false, the directory is only deleted if it is empty, otherwise an IOError error type will be passed in onerror().
If the deletion is performed successfully, the onsuccess() is invoked.
The ErrorCallback is launched with these error types:
- InvalidValuesError - If any of the input parameters contains an invalid value.
- NotFoundError -If the passed directory does not correspond to a valid directory.
-
IOError - If the File in which the delete method is invoked is a file (and not a directory), the directory is in use by another process or the directory is not empty and recursive argument is false.
This code is also used if a recursive deletion partially fails and any data deleted so far cannot be recovered. This may occur due to the lack of filesystem permissions or if any directories or files are already opened by other processes. - UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- directoryPath: Full virtual path to the directory to delete (must be under the current one).
-
recursive:
Flag indicating whether the deletion is recursive or not
When set to true recursive deletion is allowed. Also, this function deletes all data in all subdirectories and so needs to be used with caution. - onsuccess [optional] [nullable]: Callback method to be invoked when a directory is successfully deleted.
- onerror [optional] [nullable]: Callback method to be invoked when an error has occurred.
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.
Code example:
var documentsDir; function onsuccess(files) { for (var i = 0; i < files.length; i++) { if (files[i].isDirectory) { documentsDir.deleteDirectory(files[i].fullPath, false, function() { console.log("Directory Deleted"); }, function(e) { console.log("Error " + e.message); }); } } } function onerror(error) { console.log( "The error " + error.message + " occurred when listing the files in the selected folder"); } tizen.filesystem.resolve("documents", function(dir) { documentsDir = dir; dir.listFiles(onsuccess, onerror); }, function(e) { console.log("Error " + e.message); }, "rw");
-
deleteFile
-
Deletes a specified file.
This function attempts to asynchronously delete a file under the current directory.void deleteFile(DOMString filePath, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror);
Since: 1.0
If the deletion is performed successfully, the onsuccess() is invoked.
The ErrorCallback is launched with these error types:
- InvalidValuesError - If any of the input parameters contains an invalid value.
- NotFoundError - If the file does not correspond to a valid file.
- IOError - If the file in which the delete() method is invoked is a file (not a directory), the file is in use by another process, or there is no permission in the file system.
- UnknownError - If any other error occurs.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- filePath: Full virtual path to the file to delete (must be under the current directory).
- onsuccess [optional] [nullable]: Callback method to be invoked when the file is successfully deleted.
- onerror [optional] [nullable]: Callback method to be invoked when an error has occurred.
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.
Code example:
var documentsDir; function onsuccess(files) { for (var i = 0; i < files.length; i++) { if (!files[i].isDirectory) { documentsDir.deleteFile(files[i].fullPath, function() { console.log("File Deleted"); }, function(e) { console.log("Error " + e.message); }); } } } function onerror(error) { console.log( "The error " + error.message + " occurred when listing the files in the selected folder"); } tizen.filesystem.resolve("documents", function(dir) { documentsDir = dir; dir.listFiles(onsuccess, onerror); }, function(e) { console.log("Error " + e.message); }, "rw");
2.5. FileFilter
dictionary FileFilter { DOMString name; 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
- 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. FileStream
[NoInterfaceObject] interface FileStream { readonly attribute boolean eof; attribute long position; readonly attribute long bytesAvailable; void close(); DOMString read(long charCount) raises(WebAPIException); octet[] readBytes(long byteCount) raises(WebAPIException); DOMString readBase64(long byteCount) raises(WebAPIException); void write(DOMString stringData) raises(WebAPIException); void writeBytes(octet[] byteData) raises(WebAPIException); void writeBase64(DOMString base64Data) raises(WebAPIException); };
Since: 1.0
A series of read/write methods are available that permit both binary and text to be processed.
Once a file stream is closed, any operation attempt made on this stream results in a standard JavaScript error.
The read/write operations in this interface do not throw any security exceptions as the access rights are expected to be granted through the initial resolve() method or through the openStream() method of the File interface. Therefore, all actions performed on a successfully resolved File and FileStream are expected to succeed. This avoids successive asynchronous calls and may potentially increase application for a user.
Attributes
-
readonly
boolean eofThe flag indicating whether the current file pointer is at the end of the file.
If set to true, this attribute indicates that the file pointer is at the end of the file.
If set to false, this attribute indicates that the file pointer is not at the end of the file and so it is anywhere within the file.
Since: 1.0
Code example:
if (stream.eof) { /* File has been read completely. */ }
-
long positionThe flag indicating the stream position for reads/writes.
The stream position is an offset of bytes from the start of the file stream. When invoking an operation that reads or writes from the stream, the operation will take place from the byte defined by this position attribute. If the read or write operation is successful, the position of the stream is advanced by the number of bytes read or written. If the read/write operation is not successful, the position of the stream is unchanged.
Since: 1.0
Code example:
console.log(stream.position); /* Displays current stream position. */ /* Alters current stream position to the begin of the file, */ /* like seek() in C. */ stream.position = 0;
-
readonly
long bytesAvailableThe number of bytes that are available for reading from the stream.
The number of bytes available for reading is the maximum amount of bytes that can be read in the next read operation. It corresponds to the number of bytes available after the file pointer denoted by the position attribute.
-1 if EOF is true.
Since: 1.0
Code example:
console.log(stream.bytesAvailable); /* Displays the available bytes to be read. */
Methods
-
close
-
Closes this FileStream.
void close();
Since: 1.0
Flushes any pending buffered writes and closes the File. Always succeeds. Note that pending writes might not succeed.
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Code example:
stream.close(); /* Closes this stream, no subsequent access to stream allowed. */
-
read
-
Reads the specified number of characters from the position of the file pointer in a FileStream and returns the characters as a string. The resulting string length might be shorter than charCount if EOF is true.
DOMString read(long charCount);
Since: 1.0
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Parameters:
- charCount: Number of characters being read.
Return value:
-
DOMString:
Array of read characters as a string.
Exceptions:
- WebAPIException
with error type IOError, if a read error occurs, such as the bytes in the stream cannot be decoded with the encoding in use.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type InvalidValuesError, if any of the input parameters contains an invalid value.
with error type SecurityError, if the application does not have the privilege to call this method.
Code example:
var text = stream.read(file.fileSize); stream.close();
-
readBytes
-
Reads the specified number of bytes from a FileStream.
octet[] readBytes(long byteCount);
Since: 1.0
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Parameters:
- byteCount: Number of bytes to read.
Return value:
-
octet[]:
Result of read bytes as a byte (or number) array.
Exceptions:
- WebAPIException
with error type IOError, if a read error occurs.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type InvalidValuesError, if any of the input parameters contains an invalid value.
with error type SecurityError, if the application does not have the privilege to call this method.
Code example:
/* Reads up to 256 bytes from the stream. */ var raw = stream.readBytes(256); for (var i = 0; i < raw.length; i++) { /* raw[i] contains the i-th byte of the current data chunk. */ }
-
readBase64
-
Reads the specified number of bytes from this FileStream, encoding the result in base64.
DOMString readBase64(long byteCount);
Since: 1.0
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.read
Parameters:
- byteCount: Number of bytes to read.
Return value:
-
DOMString:
Array of read characters as base64 encoding string.
Exceptions:
- WebAPIException
with error type IOError, if a read error occurs.
with error type TypeMismatchError, if the input parameter is not compatible with the expected type for that parameter.
with error type InvalidValuesError, if any of the input parameters contains an invalid value.
with error type SecurityError, if the application does not have the privilege to call this method.
Code example:
/* Reads up to 256 bytes from the stream. */ var base64 = stream.readBase64(256);
-
write
-
Writes the specified DOMString to a FileStream.
void write(DOMString stringData);
Since: 1.0
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- stringData: Actual string to write.
Exceptions:
- WebAPIException
with error type IOError, if a write error occurs.
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.
Code example:
var text = "Hello world"; stream.write(text);
-
writeBytes
-
Writes the specified bytes to this FileStream.
void writeBytes(octet[] byteData);
Since: 1.0
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- byteData: Byte data array being written.
Exceptions:
- WebAPIException
with error type IOError, if a write error occurs.
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.
Code example:
var bytes = input.readBytes(256); /* Writes the bytes read from input to output. */ output.writeBytes(bytes);
-
writeBase64
-
Writes the result to this FileStream after converting the specified base64 DOMString to bytes.
void writeBase64(DOMString base64Data);
Since: 1.0
Privilege level: public
Privilege: http://tizen.org/privilege/filesystem.write
Parameters:
- base64Data: The base64 data to written.
Exceptions:
- WebAPIException
with error type IOError, if an error occurs during writeBase64.
with error type InvalidValuesError, if the input parameter contains an invalid value (e.g. the base64Data input parameter is not a valid Base64 sequence).
with error type SecurityError, if the application does not have the privilege to call this method.
Code example:
var base64 = input.readBase64(256); /* Writes the base64 data read from input to output. */ output.writeBase64(base64);
2.7. FileSuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface FileSuccessCallback { void onsuccess(File file); };
Since: 1.0
It is used in asynchronous operations, such as FileSystemManager.resolve(), copying, moving and deleting files.
Methods
-
onsuccess
-
Called when the asynchronous call completes successfully.
void onsuccess(File file);
Since: 1.0
Parameters:
- file: File resulting from the asynchronous call.
2.8. 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.9. 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.10. FileStringSuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface FileStringSuccessCallback { void onsuccess(DOMString fileStr); };
Since: 1.0
It is used in asynchronous operation File.readAsText().
2.11. FileStreamSuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface FileStreamSuccessCallback { void onsuccess(FileStream filestream); };
Since: 1.0
It is used in asynchronous operation File.openStream().
Methods
-
onsuccess
-
Called when the File.openStream asynchronous call completes successfully.
void onsuccess(FileStream filestream);
Since: 1.0
Parameters:
- filestream: Filestream to access file content.
2.12. FileArraySuccessCallback
[Callback=FunctionOnly, NoInterfaceObject] interface FileArraySuccessCallback { void onsuccess(File[] files); };
Since: 1.0
This callback interface specifies a success callback with a function taking an array of File objects as input argument. It is used in asynchronous methods, such as File.listFiles().
Methods
-
onsuccess
-
Called when the asynchronous call completes successfully.
void onsuccess(File[] files);
Since: 1.0
Parameters:
- files: Files resulting from the asynchronous call.
3. Full WebIDL
module Filesystem { enum FileMode { "a", "r", "rw", "w" }; enum FileSystemStorageType { "INTERNAL", "EXTERNAL" }; enum FileSystemStorageState { "MOUNTED", "REMOVED", "UNMOUNTABLE" }; dictionary FileFilter { DOMString name; Date startModified; Date endModified; Date startCreated; Date endCreated; }; Tizen implements FileSystemManagerObject; [NoInterfaceObject] interface FileSystemManagerObject { readonly attribute FileSystemManager filesystem; }; [NoInterfaceObject] interface FileSystemManager { readonly attribute long maxPathLength; void resolve(DOMString location, FileSuccessCallback onsuccess, optional ErrorCallback? onerror, optional FileMode? mode) raises(WebAPIException); 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 File { readonly attribute File? parent; readonly attribute boolean readOnly; readonly attribute boolean isFile; readonly attribute boolean isDirectory; readonly attribute Date? created; readonly attribute Date? modified; readonly attribute DOMString path; readonly attribute DOMString name; readonly attribute DOMString fullPath; readonly attribute unsigned long long fileSize; readonly attribute long length; DOMString toURI() raises(WebAPIException); void listFiles(FileArraySuccessCallback onsuccess, optional ErrorCallback? onerror, optional FileFilter? filter) raises(WebAPIException); void openStream(FileMode mode, FileStreamSuccessCallback onsuccess, optional ErrorCallback? onerror, optional DOMString? encoding) raises(WebAPIException); void readAsText(FileStringSuccessCallback onsuccess, optional ErrorCallback? onerror, optional DOMString? encoding) raises(WebAPIException); void copyTo(DOMString originFilePath, DOMString destinationFilePath, boolean overwrite, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void moveTo(DOMString originFilePath, DOMString destinationFilePath, boolean overwrite, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); File createDirectory(DOMString dirPath) raises(WebAPIException); File createFile(DOMString relativeFilePath) raises(WebAPIException); File resolve(DOMString filePath) raises(WebAPIException); void deleteDirectory(DOMString directoryPath, boolean recursive, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); void deleteFile(DOMString filePath, optional SuccessCallback? onsuccess, optional ErrorCallback? onerror) raises(WebAPIException); }; [NoInterfaceObject] interface FileStream { readonly attribute boolean eof; attribute long position; readonly attribute long bytesAvailable; void close(); DOMString read(long charCount) raises(WebAPIException); octet[] readBytes(long byteCount) raises(WebAPIException); DOMString readBase64(long byteCount) raises(WebAPIException); void write(DOMString stringData) raises(WebAPIException); void writeBytes(octet[] byteData) raises(WebAPIException); void writeBase64(DOMString base64Data) raises(WebAPIException); }; [Callback=FunctionOnly, NoInterfaceObject] interface FileSuccessCallback { void onsuccess(File file); }; [Callback=FunctionOnly, NoInterfaceObject] interface FileSystemStorageArraySuccessCallback { void onsuccess(FileSystemStorage[] storages); }; [Callback=FunctionOnly, NoInterfaceObject] interface FileSystemStorageSuccessCallback { void onsuccess(FileSystemStorage storage); }; [Callback=FunctionOnly, NoInterfaceObject] interface FileStringSuccessCallback { void onsuccess(DOMString fileStr); }; [Callback=FunctionOnly, NoInterfaceObject] interface FileStreamSuccessCallback { void onsuccess(FileStream filestream); }; [Callback=FunctionOnly, NoInterfaceObject] interface FileArraySuccessCallback { void onsuccess(File[] files); }; };