org.apache.cordova.file-extras plugin
=====================================

This plugin grants a Cordova application access to several additional filesystem roots, and provides a cross-platform means of accessing these filesystems based on their intended purpose.

The set of available filesystems depends on the platform.

Android
-------

    - files: The application's internal file storage directory
    - files-external: The application's external file storage directory
    - sdcard: The global external file storage directory (this is the root of the SD card, if one is installed)
    - cache: The application's internal cache directory
    - cache-external: The application's external cache directory
    - root: The entire device filesystem

Android also supports a special filesystem named "documents", which represents a "/Documents/" subdirectory within the "files" filesystem.

iOS
---

    - library: The application's Library directory
    - documents: The application's Documents directory
    - cache: The application's Cache directory
    - app-bundle: The application's bundle; the location of the app itself on disk
    - root: The entire device filesystem

By default, the library and documents directories can be synced to iCloud. You can also request two additional filesystems, "library-nosync" and "documents-nosync", which represent a special non-synced directory within the Library or Documents filesystem.

Configuring the plugin
----------------------

The set of available filesystems can be configured at build time per-platform. Both iOS and Android recognize a <preference> tag in `config.xml` which names the filesystems to be installed. The defaults for these preferences, if not set, are

    <preference name="iosExtraFilesystems" value="library,library-nosync,documents,documents-nosync,cache,bundle" />

    <preference name="AndroidExtraFilesystems" value="files,files-external,documents,sdcard,cache,cache-external" />

These defaults contain all available filesystems except for "root".

Accessing the filesystems
-------------------------

The simplest method of using these new filesystems is to call `cordova.plugins.fileextras.getFilesystem` with the name of the filesystem you want to use.

    cordova.plugins.fileextras.getFilesystemRoot(filesystemName, successCallback, errorCallback);

If successful, `successCallback` will be called with a `DirectoryEntry` object representing the root of the filesystem. Otherwise, `errorCallback` will be called with a `FileError`.

It is also possible to request a `DirectoryEntry` object for a particular purpose. This provides a cross-platform way of accessing the various filesystem locations.

    cordova.plugins.fileextras.getDirectoryForPurpose(purpose, options, successCallback, failureCallback)

will call successCallback with a `DirectoryEntry` object suitable for the specified purpose.

The following string constants are defined for the `purpose` field:

    data
    documents
    cache
    temp        (returns the TEMPORARY filesystem)
    app-bundle  (iOS only)

The `options` field is an object. On iOS, it is possible to set it to `{syncable: false}` to obtain the non-synced versions of `data` or `documents`. On Android, you can set `{sandboxed: false}` to get the external (not confined to your app) versions of `data`, `documents` or `cache`.