Overview | File | Class | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## Class File

    Object
       |
       +--File

class File

Class representing files and directories.

Objects of this class can refer to regular files, directories or archives of files. In the two latter cases, the object contains references to its subdirectories and files.

The `fileSystem.mountPoint` property and any mounted directories are `File` objects. You may make a `File` object by calling the `resolve()` method on any of these.

The `File` class is special in that it doubles as an array-like object containing the `File` objects it refers to. So if, a directory contains a series of files and directories, you can do the following:

    var dir = mp.resolve('path/to/dir'); //Get a File object referring to the directory
    dir.refresh(); //Load the contents of the directory
    for ( var i = 0, file; file = dir[i]; i++ )
    {
        opera.postError(file.name);
    }

Defined in file-io.js

Field Summary
`Date` | `created` The time and date this File was created.
`boolean` | `exists` Whether or not this File exists in the physical file system.
`int` | `fileSize` The number of bytes in this File.
`boolean` | `isArchive` Whether or not this File is a compressed archive, like a zip or gzip file.
`boolean` | `isDirectory` Whether or not this File is a directory.
`boolean` | `isFile` Whether or not this File is a regular file.
`boolean` | `isHidden` Whether or not this File is hidden in the underlying file system.
`int` | `length` The number of files and directories referenced by this File.
`int` | `maxPathLength` The maximum number of characters a path reference can contain.
`Object` | `metaData` Meta data for this file.
`Date` | `modified` The time and date this File was last modified.
`String` | `name` The name of this File as a URL encoded String.
`String` | `nativePath` The path to this File in the physical file system.
`File` | `parent` The parent File of this File, or null if it has no parent.
`String` | `path` The path to this File in the virtual file system as a URL encoded String.
`boolean` | `readOnly` Whether or not this File is read only.

Constructor Summary
`File()` This class has no public constructor.

Method Summary
`File` | `copyTo( <File> path, <boolean> overwrite, <Function> callback )` Copy this File to the given File path.
`File` | `createDirectory( <File> directory )` Create a new directory.
`boolean` | `deleteDirectory( <File> directory, <boolean> recursive )` Delete the given directory.
`boolean` | `deleteFile( <File> file )` Delete the given file.
`File` | `moveTo( <File> path, <boolean> overwrite, <Function> callback )` Move this File to the given File path.
`FileStream` | `open( <File> path, <int> mode )` Open a File for reading or writing.
`void` | `refresh()` Refresh the content in this File.
`File` | `resolve( <String> path )` Resolve a path to a file.
`String` | `toString()` String representation of this File.

Field Detail

### created

    Date created

The time and date this File was created.

### exists

    boolean exists

Whether or not this File exists in the physical file system. Readonly. File objects created through `resolve()` or `browseForSave()`, may in some cases not exist in the file system.

### fileSize

    int fileSize

The number of bytes in this File. Readonly. If this File is a directory, it's size is 0. Use the `length` property to find out how many files the directory contains.

### isArchive

    boolean isArchive

Whether or not this File is a compressed archive, like a zip or gzip file. Readonly.

Note that archives will also have the `isDirectory` and isFile properties set. You may both use `resolve()` to resolve files inside the archive, or open the archive file using `open()`.

Currently only a subset of the ZIP format is currently supported as archives.

### isDirectory

    boolean isDirectory

Whether or not this File is a directory. Readonly.

### isFile

    boolean isFile

Whether or not this File is a regular file. Readonly.

### isHidden

    boolean isHidden

Whether or not this File is hidden in the underlying file system. Readonly.

### length

    int length

The number of files and directories referenced by this File. Readonly.

This property is used for array style lookup. If the `File` object is a regular file, its length is 0. Use the `fileSize` property to get the size of regular files in bytes.

For directories or archives, this property is 0 until `refresh()` is called, except for mount point `File` objects that are already loaded.

### maxPathLength

    int maxPathLength

The maximum number of characters a path reference can contain. Readonly. This number is the maximum path length supplied by the operating system, minus the length of the actual path to the file in the actual file system. If `c:\foo\bar` is mounted as `bar`, and assuming the operating system has a maximum path length of 128, the `maxPathLength` property of the File would be 128 - 10 = 110.

### metaData

    Object metaData

Meta data for this file. This property holds meta data for special types of files, for example the file name of an uploaded file. For normal files, this property is `null.`

### modified

    Date modified

The time and date this File was last modified.

### name

    String name

The name of this File as a URL encoded String.

Anything that occurs after the last '/' in the path of this File. If the file has the path `/foo/bar`, the name is `bar`. There is no trailing path separator if this File is a directory.

### nativePath

    String nativePath

The path to this File in the physical file system. Readonly.

The full path of this File in the physical file system, including trailing slash or backslash for directories. If you mount a directory `c:\foo\` as `foo` and this directory contains a file `bar.txt`, the `nativePath` of this File will be `c:\foo\bar.txt`. Note that the path separator of the underlying operating system is used in the path.

For the mount points mounted by `mountSystemDirectory()`, and for all files under them, this property will be empty to avoid exposing system information to the application.

This property is not URL encoded, i.e. it is not modified in any way from how the underlying file system would represent the path.

### parent

    File parent

The parent File of this File, or null if it has no parent. Readonly. In most cases, the parent will be a directory. It can also be an archive. For Files that are mount points, this property is `null`.

### path

    String path

The path to this File in the virtual file system as a URL encoded String. Readonly.

The full path of this File in the virtual file system, starting with the name of the mount point and including the full file name of this file or directory. There is no trailing path separator if this File is a directory.

### readOnly

    boolean readOnly

Whether or not this File is read only. Readonly. Files mounted in the application directory, using `mountSystemDirectory()` are not writeable. Otherwise, the physical file system determines whether or not the File is writeable.

Constructor Detail

### File

    File()

This class has no public constructor.

Method Detail

### copyTo

    File copyTo( <File> path, <boolean> overwrite, <Function> callback )

Copy this File to the given File path.

Calling this function will copy all the contents of this File to the given target location, given as either a `File` object or a String containing the path.

If the target location exists, this operation will fail with an exception. Use the `overwrite` argument to replace existing files in target location.

Supplying the optional `callback` will make the operation asynchronous, and the function will immediately return a `File` object representing the copy of the File, regardless of whether the operation is complete. The callback is called when the copy operation is complete, with the copy of the File as an argument. If the operation fails, the callback is called with a `null` argument.

Parameters:

`path` - The target location to copy this File to, as either a File or an URL encoded String with the path.

`overwrite` - Whether or not to overwrite any content present in the target path. Optional, default false.

`callback` - Function to call when the copy is completed. Optional.

Returns:

File object representing the location of the copy.

Throws:

- GENERIC_ERR If the destination File already exists and the `overwrite` argument is `false`.

### createDirectory

    File createDirectory( <File> directory )

Create a new directory.

Create a new directory using either a File object or a URL encoded String with a path to the new directory. All non-existing parent directories are created along with it.

## Examples:

    file = mountPoint.createDirectory(somePath);
    file = mountPoint.createDirectory(mountPoint.resolve(somePath));

Parameters:

`directory` - File referring to the desired directory, or a URL encoded String with the path to the directory.

Returns:

File pointing to the new directory.

Throws:

- GENERIC_ERR If the directory or any of its parent directories could not be created.

### deleteDirectory

    boolean deleteDirectory( <File> directory, <boolean> recursive )

Delete the given directory.

If the `recursive` argument is given as `true`, this method will attempt to delete the directory and all of its content. If deleting individual files or directories in it fails, the method will continue to delete the rest of the content.

If the entire directory and all of its content is deleted, the method will return `true`. If parts of the content, and thus also the directory itself could not be deleted, the method will return `false`.

Parameters:

`directory` - File representing the directory or a URL encoded String with the path to the directory to delete.

`recursive` - Whether or not to recursively delete any content references by this File. Optional, default false.

Returns:

true if the directory and all its content was deleted, false if the directory or any part of its contents was not deleted.

### deleteFile

    boolean deleteFile( <File> file )

Delete the given file. This method takes either a `File` object or a URL encoded String with a path and deletes the referenced file.

Parameters:

`file` - File representing the directory or a URL encoded String with the path to the file to delete.

Returns:

true if the file was successfully deleted, otherwise false.

### moveTo

    File moveTo( <File> path, <boolean> overwrite, <Function> callback )

Move this File to the given File path.

Calling this function will move all the contents of this File to the given File target location.

If the target location exists, this operation will fail with an exception. Use the `overwrite` argument to replace existing files in target location.

Supplying the optional `callback` will make the operation asynchronous, and the function will immediately return a `File` object representing the new File regardless of whether the operation is complete. The callback is called with the new File as an argument. If the operation fails, the callback is called with a `null` argument.

Parameters:

`path` - The target location to move this File to, as either a File or an URL encoded String with the path.

`overwrite` - Whether or not to overwrite any content present in the target path. Optional, default false.

`callback` - Function to call when the move is competed. Optional.

Returns:

File object representing the location of the new file.

Throws:

- GENERICL_ERR If the destination File already exists and the `overwrite` argument is `false`.

### open

    FileStream open( <File> path, <int> mode )

Open a File for reading or writing.

If the path argument is given as `null`, this File will be opened.

The file can be opened in read, write, append or update mode, represented by the constants in opera.io.filemode.

The mode argument is similar to PHPs `fopen()`, but implemented as constants which can be combined through a bitwise OR, for example as `opera.io.filemode.APPEND | opera.io.filemode.READ`.

If the file does not exist when opened in WRITE or APPEND mode, it is immediately created. The entire path to the file is created if this does not exist.

If the file does not exist when opened in READ or UPDATE mode, a FILE_NOT_FOUND_ERR is thrown.

The previous version of the API accepted a string equal to the ones described below. This is now deprecated in favor of the constants in opera.io.filemode.

The the following is an extract from http://no2.php.net/fopen and explains possible combinations:

If a file is opened in an invalid mode, for example opening a read-online file in WRITE mode, a SECURITY_ERR is thrown.

'r'
  Open for reading only; place the file pointer at the beginning of the file.
'r+'
  Open for reading and writing; place the file pointer at the beginning of the file.
'w'
  Open for writing only; place the file pointer at the beginning of the file and truncate the file to zero length. If the file does not exist, attempt to create it.
'w+
  Open for reading and writing; place the file pointer at the beginning of the file and truncate the file to zero length. If the file does not exist, attempt to create it.
'a'
  Open for writing only; place the file pointer at the end of the file. If the file does not exist, attempt to create it.
'a+'
  Open for reading and writing; place the file pointer at the end of the file. If the file does not exist, attempt to create it.

Note that opera.io.filemode.UPDATE represents 'r+'.

Parameters:

`path` - File object to read, or a URL encoded String with the path to the file to read.

`mode` - Whether to open the file for reading, writing, appending or a combination.

Returns:

A FileStream pointing to the given file, or null if no File with the given path can be resolved.

Throws:

- WRONG_ARGUMENTS_ERR If the given path is not a valid File or if the mode argument is unrecognized.
- WRONG_TYPE_OF_OBJECT_ERR If the given path is not valid for opening, for example if it is a directory.
- SECURITY_ERR If opening the file is not permitted, for example if it is readonly and opened in write mode.
- FILE_NOT_FOUND_ERR If the filemode requires that a file must exist before accessing, such as READ or UPDATE, and it doesn't.

### refresh

    void refresh()

Refresh the content in this File. Initially a File representing a directory is loaded without its actual content. For directories you need to call this method at least once to load the content. The File is then not live, i.e. if the underlying file system changes, these changes are not propagated to this `File` object. You need to call this method again to see the changes.

### resolve

    File resolve( <String> path )

Resolve a path to a file.

This function will take a URL encoded String with a path and attempt to resolve the path. If the path is valid, a `File` object representing it is returned. The File may point to a non-existing file or directory, as long as the path is valid. The resulting File can, for example, be used with the File.createDirectory() method.

If the path is invalid, i.e. pointing to something outside en existing sandbox, an exception is thrown. You may resolve paths with characters that are not recommended and get a File, though exceptions will typically be thrown if you attempt to read from or write to such files.

Parameters:

`path` - URL encoded String with path of the file to resolve.

Returns:

File resolved by the given path.

Throws:

- SECURITY_ERR If the path points to something outside an existing sandbox.

### toString

    String toString()

String representation of this File. This method will return the absolute path to the File in the virtual file system, including the file name as an URL encoded String.

Returns:

URL encoded String with the path of the File.

Overview | File | Class | Tree | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Documentation generated by JSDoc on Fri Jan 29 17:08:19 2010