|
||||||||
PREV NEXT | FRAMES NO FRAMES |
This API document describes the JavaScript bindings for accessing the local file system in Opera.
The File I/O API consists of three classes: FileSystem
, File
and FileStream
.
The FileSystem
class is initialized as a singleton, and is available as opera.io.filesystem
.
This is a virtual file system. In order to actually use it, you'll need to add directories
from your actual file system as mount points to the virtual filesystem.
The File
object works like similar objects in other frameworks. It can point to a directory,
archive or regular file. It exposes properties like path
, isDirectory
, exists
,
parent
, etc. It also works as an array to let you access files and subdirectories in a directory.
The FileStream
is used when you want to read from or write to the files in the filesystem.
It supports reading and writing text, images, binary data and Base64 text.
In order to make the file system and its methods available, you need to add a feature
element to your config.xml file like this:
<widget>
...
<feature name="http://xmlns.opera.com/fileio">
<param name="folderhint" value="home" />
</feature>
...
</widget>
The folderhint
parameter is used in conjunction with the shared folder. If the parameter is present, the user will be presented with a file dialogue that defaults to a directory corresponding to the value of the parameter. If multiple folderhint
parameters are present, and the implementation supports only one shared folder, the last is used. If the parameter values do not correspond to a directory, the system will use its default starting location for the file dialogue.
If no folderhint
parameter is present, no dialogue will be presented to the user and no shared folder will be available.
The following folder hints are recognized:
You may compress multiple param
elements to value="home music pictures"
.
The following method is deprecated: In order to make the file system and its methods available, you need to add a file
attribute with the value yes
to the widget
element in the config.xml file of your Opera Widget or Opera Unite Application.
Instead of accessing the file system directly, this API uses a concept of mount points. In order to access parts of a disk, it must first be mounted as a mount point in a virtual filesystem. There are two types of mount points:
There are three special directories you can use with the File I/O API:
These are not available by default and need to be mounted using the opera.io.filesystem.mountSystemDirectory(). method:
var shared = opera.io.filesystem.mountSystemDirectory('shared');
var storage = opera.io.filesystem.mountSystemDirectory('storage','myCoolSaves');
Once mounted, they also become available under in the opera.io.filesystem.mountPoints
property.
You may specify an optional name to mount these directories as. If not supplied, it defaults to application
, storage
and shared
respectively.
In the example above shared directory will be mounted as shared
and have a path /shared
,
while storage will be mounted as myCoolSaves
and have a path /myCoolSaves
.
These can then be accessed as regular mount points and through the mountpoint URL protocol as other mounted files, except that the application
directory is mounted as read-only.
WARNING: The shared
directory will be read-write, unless the underlying
file system defines it to be read-only. Be careful to protect your data by controlling how data gets written to it. You
should supply some sort of authentication of users who access data in this folder and be careful to not leave code open to exploitation.
Note: Creating mount points with the browseFor*
methods is not supported in Opera Unite Applications. It should be possible for Opera Widgets. Mounting system mount points should work in both cases.
It is possible to create your own mount points from any directory on the user's disk, using the opera.io.filesystem.browseForDirectory(), opera.io.filesystem.browseForFile() and opera.io.filesystem.browseForSave() methods.
These functions will open a file dialog, and let the user choose a file to share. The selected file is returned as an argument to a callback function. If the user cancels the dialog, or the selected file is somehow invalid, the callback function is called with null.
WARNING: Once mounted, the mount point will be read-write unless the underlying file system defines it to be read-only. Be careful to protect your data by controlling how data gets written to them. You should supply some sort of authentication of users who access these directories and be careful to not leave code open to exploitation.
The following is an example using browseForDirectory()
, which is the most common case:
opera.io.filesystem.browseForDirectory( 'myImages', '', processDir ); //Let the user choose a directory
function processDir( dir )
{
if ( ! dir )
{
return; //Invalid file or canceled dialog
}
opera.postError(dir.path);
}
In this case, 'myImages'; becomes the name of the directory in the virtual file system. The processDir
function is called with the file the user selects.
When you have mounted a directory or file, it is available in the fileSystem.mountPoints
property. This property is a special File object with a blank name and a path of '/'. You can access mount points through an array-style notation:
var mp = opera.io.filesystem.mountPoints['myImages'];
In some cases, you want your application to be able to reference files
that have been mounted in the virtual file system from a Web page. You can use the mountpoint URL protocol
for this purpose. A mountpoint URL starts with mountpoint://
, followed by the name of a mount point
and a path to a file under that mount point.
For example, if a user has added a mount point, and named it myImages
using the call:
opera.io.filesystem.browseForDirectory( 'myImages', '', callback_function );
the user can access files inside the mount point by creating an absolute URI:
<img src="mountpoint://myImages/avatar.png">
Note that the path separator is always '/'
, regardless of the underlying file system.
The fileSystem.mountPoints
property represents the root of the file system and has the path '/'
.
A mount point mounted with the name foo has the path '/foo'
.
All files belong to only one mount point, so if a directory mounted as 'foo'
has a file called
'bar'
, the path of the file is '/foo/bar'
.
Paths that begin with '/'
are absolute paths, starting from the root and moving down through a
mount point, through any subdirectories and potentially to a file.
You may use relative paths. Any path not starting with a '/' is a relative path. The '.' and '..' directory references
are supported. Paths are relative to the current directory. If file
is a regular file, and you call
file.moveTo('some/path')
or similar methods, the path is relative to the parent directory of file
.
If file
is a directory, the path is relative to that directory.
You obtain an initial file by adding a mount point as described earlier. From here you have two options:
If the mount point is a directory, you can move into its content as described in the section on directories.
You can use the resolve()
method on the initial File
object to get a reference to a File
somewhere under the mount point. This method takes a path as an argument and will attempt to resolve it. If
the path is valid, an File
object is returned. Note that the file does not need to exist; the path simply needs to be a possible valid path.
var file = mp.resolve('vacation/img001.jpg');
Note that the path separator is always '/', regardless of the underlying file system.
Some important properties of the File
object:
File
object actually exists. Especially useful when using the resolve()
method.File
object references a regular file.File
object references a directory.To create a directory, call the File.createDirectory() method, with either String with the path or a File object resolved to the path:
var file = mp.createDirectory('keep');
Or:
var subFile = mountPoint.resolve('keep');
var file = mp.createDirectory(subFile);
You may copy and move files by using the copy
and moveTo
methods:
file.copyTo('../backup/img001.jpg');
file.moveTo('keep/img001.jpg');
Both methods take an optional argument overwrite
, which will cause any existing files with the new path to be overwritten.
In order to write files, you need to open a FileStream
to the file and write to it. See the section on working with streams.
To delete files or directories, use the deleteFile()
or deleteDirectory()
methods:
mp.deleteFile('keep/img001.jpg');
mp.deleteDirectory('keep', true);
Both methods may take a File
object instead of a path. The second argument is to delete content recursively
A File
object made from a directory points to its subdirectories and contained files.
The File
object supports a length
property and an array-like syntax to access these subfiles.
Note that the subfiles and directories need to be 'refreshed' before you can actually access
them. Through this process, information about the files in the directory are loaded into the virtual
filesystem. The method refresh()
is used for this purpose:
dir.refresh(); //Load the contents of the directory
for ( var i = 0, file; file = dir[i]; i++ )
{
opera.postError(file.path + ' ' + file.isDirectory + ' ' file.isFile);
}
When the file is a directory, its length
property will tell you how many files and subdirectories there are in the directory.
It's important to note that information about the subfiles and directories of this directory is
not live. If files are added, moved or deleted, you need to call refresh()
again to update
the information in the File
object.
You can similarly recurse through the file structure.
In order to read or write to a file, you need to make a File
object and then open it for reading or writing
using the open
method:
var stream = dir.open('shoppinglist.txt', opera.io.filemode.WRITE);
stream.writeLine('Eggs');
stream.writeLine('Milk');
stream.writeLine('Bread');
stream.close();
stream = dir.open('newfile');
var data = stream.readLine();
opera.postError(data);
Using opera.io.filemode.WRITE
will overwrite all data in the file. Use opera.io.filemode.APPEND
to append data instead. If the file does not exist, it is immediately created when opened in either of these modes.
If you're unsure if the file exists, you should resolve it first, test it for existence, and then perform operations on it:
var file = dir.resolve('shoppinglist.txt');
if ( ! file.exists )
{
var stream = file.open(null, opera.io.filemode.WRITE);
//Perform operations
}
The following modes are supported:
The modes can be combined using a bitwise OR: ( READ | WRITE )
.
You may write characters, lines, Base64-encoded text and images to the stream, using the different writeX()
methods of the FileStream
object.
Class Summary | |
File | Class representing files and directories. |
FileStream | A FileStream allows reading or writing specific parts of a File. |
opera.io.filemode | File mode constants that can be used with File.open() |
opera.io.filesystem | Virtual file system implementation |
|
||||||||
PREV NEXT | FRAMES NO FRAMES |