Libr-mobile/plugins/org.apache.cordova.file/package.json

{
    "version": "1.1.0",
    "name": "org.apache.cordova.file",
    "cordova_name": "File",
    "description": "Cordova File Plugin",
    "license": "Apache 2.0",
    "repo": "https://git-wip-us.apache.org/repos/asf/cordova-plugin-file.git",
    "issue": "https://issues.apache.org/jira/browse/CB/component/12320651",
    "keywords": [
        "cordova",
        "file"
    ],
    "platforms": [
        "android",
        "amazon-fireos",
        "ubuntu",
        "ios",
        "wp7",
        "wp8",
        "blackberry10",
        "windows8"
    ],
    "engines": [],
    "englishdoc": "<!---\n    Licensed to the Apache Software Foundation (ASF) under one\n    or more contributor license agreements.  See the NOTICE file\n    distributed with this work for additional information\n    regarding copyright ownership.  The ASF licenses this file\n    to you under the Apache License, Version 2.0 (the\n    \"License\"); you may not use this file except in compliance\n    with the License.  You may obtain a copy of the License at\n\n      http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing,\n    software distributed under the License is distributed on an\n    \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY\n    KIND, either express or implied.  See the License for the\n    specific language governing permissions and limitations\n    under the License.\n-->\n\n# org.apache.cordova.file\n\nThis plugin provides the [HTML5 Filesystem API](http://dev.w3.org/2009/dap/file-system/pub/FileSystem/). For usage, refer\nto HTML5 Rocks' [FileSystem article](http://www.html5rocks.com/en/tutorials/file/filesystem/)\non the subject. For an overview of other storage options, refer to Cordova's\n[storage guide](http://cordova.apache.org/docs/en/edge/cordova_storage_storage.md.html).\n\n## Installation\n\n    cordova plugin add org.apache.cordova.file\n\n## Supported Platforms\n\n- Amazon Fire OS\n- Android\n- BlackBerry 10*\n- iOS\n- Windows Phone 7 and 8*\n- Windows 8*\n\n\\* _These platforms do not support `FileReader.readAsArrayBuffer` nor `FileWriter.write(blob)`._\n\n## Configuring the Plugin\n\nThe set of available filesystems can be configured per-platform. Both iOS and\nAndroid recognize a <preference> tag in `config.xml` which names the\nfilesystems to be installed. By default, all file-system roots are enabled.\n\n    <preference name=\"iosExtraFilesystems\" value=\"library,library-nosync,documents,documents-nosync,cache,bundle,root\" />\n    <preference name=\"AndroidExtraFilesystems\" value=\"files,files-external,documents,sdcard,cache,cache-external,root\" />\n\n### Android\n\n* files: The application's internal file storage directory\n* files-external: The application's external file storage directory\n* sdcard: The global external file storage directory (this is the root of the SD card, if one is installed)\n* cache: The application's internal cache directory\n* cache-external: The application's external cache directory\n* root: The entire device filesystem\n\nAndroid also supports a special filesystem named \"documents\", which represents a \"/Documents/\" subdirectory within the \"files\" filesystem.\n\n### iOS\n\n* library: The application's Library directory\n* documents: The application's Documents directory\n* cache: The application's Cache directory\n* app-bundle: The application's bundle; the location of the app itself on disk\n* root: The entire device filesystem\n\nBy 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.\n\n## Android Quirks\n\n### Android Persistent storage location\n\nThere are multiple valid locations to store persistent files on an Android\ndevice. See [this page](http://developer.android.com/guide/topics/data/data-storage.html)\nfor an extensive discussion of the various possibilities.\n\nPrevious versions of the plugin would choose the location of the temporary and\npersistent files on startup, based on whether the device claimed that the SD\nCard (or equivalent storage partition) was mounted. If the SD Card was mounted,\nor if a large internal storage partition was available (such as on Nexus\ndevices,) then the persistent files would be stored in the root of that space.\nThis meant that all Cordova apps could see all of the files available on the\ncard.\n\nIf the SD card was not available, then previous versions would store data under\n/data/data/<packageId>, which isolates apps from each other, but may still\ncause data to be shared between users.\n\nIt is now possible to choose whether to store files in the internal file\nstorage location, or using the previous logic, with a preference in your\napplication's config.xml file. To do this, add one of these two lines to\nconfig.xml:\n\n    <preference name=\"AndroidPersistentFileLocation\" value=\"Internal\" />\n\n    <preference name=\"AndroidPersistentFileLocation\" value=\"Compatibility\" />\n\nWithout this line, the File plugin will use \"Compatibility\" as the default. If\na preference tag is present, and is not one of these values, the application\nwill not start.\n\nIf your application has previously been shipped to users, using an older (pre-\n1.0) version of this plugin, and has stored files in the persistent filesystem,\nthen you should set the preference to \"Compatibility\". Switching the location to\n\"Internal\" would mean that existing users who upgrade their application may be\nunable to access their previously-stored files, depending on their device.\n\nIf your application is new, or has never previously stored files in the\npersistent filesystem, then the \"internal\" setting is generally recommended.\n\n## BlackBerry Quirks\n\n`DirectoryEntry.removeRecursively()` may fail with a `ControlledAccessException` in the following cases:\n\n- An app attempts to access a directory created by a previous installation of the app.\n\n> Solution: ensure temporary directories are cleaned manually, or by the application prior to reinstallation.\n\n- If the device is connected by USB.\n\n> Solution: disconnect the USB cable from the device and run again.\n\n## iOS Quirks\n- `FileReader.readAsText(blob, encoding)`\n  - The `encoding` parameter is not supported, and UTF-8 encoding is always in effect.\n\n### iOS Persistent storage location\n\nThere are two valid locations to store persistent files on an iOS device: the\nDocuments directory and the Library directory. Previous versions of the plugin\nonly ever stored persistent files in the Documents directory. This had the\nside-effect of making all of an application's files visible in iTunes, which\nwas often unintended, especially for applications which handle lots of small\nfiles, rather than producing complete documents for export, which is the\nintended purpose of the directory.\n\nIt is now possible to choose whether to store files in the documents or library\ndirectory, with a preference in your application's config.xml file. To do this,\nadd one of these two lines to config.xml:\n\n    <preference name=\"iosPersistentFileLocation\" value=\"Library\" />\n\n    <preference name=\"iosPersistentFileLocation\" value=\"Compatibility\" />\n\nWithout this line, the File plugin will use \"Compatibility\" as the default. If\na preference tag is present, and is not one of these values, the application\nwill not start.\n\nIf your application has previously been shipped to users, using an older (pre-\n1.0) version of this plugin, and has stored files in the persistent filesystem,\nthen you should set the preference to \"Compatibility\". Switching the location to\n\"Library\" would mean that existing users who upgrade their application would be\nunable to access their previously-stored files.\n\nIf your application is new, or has never previously stored files in the\npersistent filesystem, then the \"Library\" setting is generally recommended.\n\n## Upgrading Notes\n\nIn v1.0.0 of this plugin, the `FileEntry` and `DirectoryEntry` structures have changed,\nto be more in line with the published specification.\n\nPrevious (pre-1.0.0) versions of the plugin stored the device-absolute-file-location\nin the `fullPath` property of `Entry` objects. These paths would typically look like\n\n    /var/mobile/Applications/<application UUID>/Documents/path/to/file  (iOS)\n    /storage/emulated/0/path/to/file                                    (Android)\n\nThese paths were also returned by the `toURL()` method of the `Entry` objects.\n\nWith v1.0.0, the `fullPath` attribute is the path to the file, _relative to the root of\nthe HTML filesystem_. So, the above paths would now both be represented by a `FileEntry`\nobject with a `fullPath` of\n\n    /path/to/file\n\nIf your application works with device-absolute-paths, and you previously retrieved those\npaths through the `fullPath` property of `Entry` objects, then you should update your code\nto use `entry.toURL()` instead. This method will now return filesystem URLs of the form\n\n    cdvfile://localhost/persistent/path/to/file\n\nwhich can be used to identify the file uniquely.\n\nFor backwards compatibility, the `resolveLocalFileSystemURL()` method will accept a\ndevice-absolute-path, and will return an `Entry` object corresponding to it, as long as that\nfile exists within either the TEMPORARY or PERSISTENT filesystems.\n\nThis has particularly been an issue with the File-Transfer plugin, which previously used\ndevice-absolute-paths (and can still accept them). It has been updated to work correctly\nwith FileSystem URLs, so replacing `entry.fullPath` with `entry.toURL()` should resolve any\nissues getting that plugin to work with files on the device.\n"
}