You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by st...@apache.org on 2015/03/14 03:22:21 UTC
cordova-plugin-file git commit: CB-8653 Updated Readme
Repository: cordova-plugin-file
Updated Branches:
refs/heads/master aff7334cd -> caadf608a
CB-8653 Updated Readme
Project: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file/commit/caadf608
Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file/tree/caadf608
Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file/diff/caadf608
Branch: refs/heads/master
Commit: caadf608a7c8ebebb21f94e1910444c2d3c18a31
Parents: aff7334
Author: Steve Gill <st...@gmail.com>
Authored: Fri Mar 13 19:22:14 2015 -0700
Committer: Steve Gill <st...@gmail.com>
Committed: Fri Mar 13 19:22:14 2015 -0700
----------------------------------------------------------------------
README.md | 426 ++++++++++++++++++++++++++++++++++++++++++++++++++-
doc/index.md | 445 ------------------------------------------------------
2 files changed, 424 insertions(+), 447 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/cordova-plugin-file/blob/caadf608/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
index 0372cf4..ed71b9e 100644
--- a/README.md
+++ b/README.md
@@ -17,8 +17,430 @@
under the License.
-->
-# org.apache.cordova.file
+# cordova-plugin-file
[](https://travis-ci.org/apache/cordova-plugin-file)
-Plugin documentation: [doc/index.md](doc/index.md)
+This plugin implements a File API allowing read/write access to files residing on the device.
+
+This plugin is based on several specs, including :
+The HTML5 File API
+[http://www.w3.org/TR/FileAPI/](http://www.w3.org/TR/FileAPI/)
+
+The (now-defunct) Directories and System extensions
+Latest:
+[http://www.w3.org/TR/2012/WD-file-system-api-20120417/](http://www.w3.org/TR/2012/WD-file-system-api-20120417/)
+Although most of the plugin code was written when an earlier spec was current:
+[http://www.w3.org/TR/2011/WD-file-system-api-20110419/](http://www.w3.org/TR/2011/WD-file-system-api-20110419/)
+
+It also implements the FileWriter spec :
+[http://dev.w3.org/2009/dap/file-system/file-writer.html](http://dev.w3.org/2009/dap/file-system/file-writer.html)
+
+For usage, please refer to HTML5 Rocks' excellent [FileSystem article.](http://www.html5rocks.com/en/tutorials/file/filesystem/)
+
+For an overview of other storage options, refer to Cordova's
+[storage guide](http://cordova.apache.org/docs/en/edge/cordova_storage_storage.md.html).
+
+This plugin defines global `cordova.file` object.
+
+Although in the global scope, it is not available until after the `deviceready` event.
+
+ document.addEventListener("deviceready", onDeviceReady, false);
+ function onDeviceReady() {
+ console.log(cordova.file);
+ }
+
+## Installation
+
+ cordova plugin add cordova-plugin-file
+
+## Supported Platforms
+
+- Amazon Fire OS
+- Android
+- BlackBerry 10
+- Firefox OS
+- iOS
+- Windows Phone 7 and 8*
+- Windows 8*
+- Browser
+
+\* _These platforms do not support `FileReader.readAsArrayBuffer` nor `FileWriter.write(blob)`._
+
+## Where to Store Files
+
+As of v1.2.0, URLs to important file-system directories are provided.
+Each URL is in the form _file:///path/to/spot/_, and can be converted to a
+`DirectoryEntry` using `window.resolveLocalFileSystemURL()`.
+
+* `cordova.file.applicationDirectory` - Read-only directory where the application
+ is installed. (_iOS_, _Android_, _BlackBerry 10_)
+
+* `cordova.file.applicationStorageDirectory` - Root directory of the application's
+ sandbox; on iOS this location is read-only (but specific subdirectories [like
+ `/Documents`] are read-write). All data contained within is private to the app. (
+ _iOS_, _Android_, _BlackBerry 10_)
+
+* `cordova.file.dataDirectory` - Persistent and private data storage within the
+ application's sandbox using internal memory (on Android, if you need to use
+ external memory, use `.externalDataDirectory`). On iOS, this directory is not
+ synced with iCloud (use `.syncedDataDirectory`). (_iOS_, _Android_, _BlackBerry 10_)
+
+* `cordova.file.cacheDirectory` - Directory for cached data files or any files
+ that your app can re-create easily. The OS may delete these files when the device
+ runs low on storage, nevertheless, apps should not rely on the OS to delete files
+ in here. (_iOS_, _Android_, _BlackBerry 10_)
+
+* `cordova.file.externalApplicationStorageDirectory` - Application space on
+ external storage. (_Android_)
+
+* `cordova.file.externalDataDirectory` - Where to put app-specific data files on
+ external storage. (_Android_)
+
+* `cordova.file.externalCacheDirectory` - Application cache on external storage.
+ (_Android_)
+
+* `cordova.file.externalRootDirectory` - External storage (SD card) root. (_Android_, _BlackBerry 10_)
+
+* `cordova.file.tempDirectory` - Temp directory that the OS can clear at will. Do not
+ rely on the OS to clear this directory; your app should always remove files as
+ applicable. (_iOS_)
+
+* `cordova.file.syncedDataDirectory` - Holds app-specific files that should be synced
+ (e.g. to iCloud). (_iOS_)
+
+* `cordova.file.documentsDirectory` - Files private to the app, but that are meaningful
+ to other application (e.g. Office files). (_iOS_)
+
+* `cordova.file.sharedDirectory` - Files globally available to all applications (_BlackBerry 10_)
+
+## File System Layouts
+
+Although technically an implementation detail, it can be very useful to know how
+the `cordova.file.*` properties map to physical paths on a real device.
+
+### iOS File System Layout
+
+| Device Path | `cordova.file.*` | `iosExtraFileSystems` | r/w? | persistent? | OS clears | sync | private |
+|:-----------------------------------------------|:----------------------------|:----------------------|:----:|:-----------:|:---------:|:----:|:-------:|
+| `/var/mobile/Applications/<UUID>/` | applicationStorageDirectory | - | r | N/A | N/A | N/A | Yes |
+| `appname.app/` | applicationDirectory | bundle | r | N/A | N/A | N/A | Yes |
+| `www/` | - | - | r | N/A | N/A | N/A | Yes |
+| `Documents/` | documentsDirectory | documents | r/w | Yes | No | Yes | Yes |
+| `NoCloud/` | - | documents-nosync | r/w | Yes | No | No | Yes |
+| `Library` | - | library | r/w | Yes | No | Yes? | Yes |
+| `NoCloud/` | dataDirectory | library-nosync | r/w | Yes | No | No | Yes |
+| `Cloud/` | syncedDataDirectory | - | r/w | Yes | No | Yes | Yes |
+| `Caches/` | cacheDirectory | cache | r/w | Yes* | Yes\*\*\*| No | Yes |
+| `tmp/` | tempDirectory | - | r/w | No\*\* | Yes\*\*\*| No | Yes |
+
+
+ \* Files persist across app restarts and upgrades, but this directory can
+ be cleared whenever the OS desires. Your app should be able to recreate any
+ content that might be deleted.
+
+\*\* Files may persist across app restarts, but do not rely on this behavior. Files
+ are not guaranteed to persist across updates. Your app should remove files from
+ this directory when it is applicable, as the OS does not guarantee when (or even
+ if) these files are removed.
+
+\*\*\* The OS may clear the contents of this directory whenever it feels it is
+ necessary, but do not rely on this. You should clear this directory as
+ appropriate for your application.
+
+### Android File System Layout
+
+| Device Path | `cordova.file.*` | `AndroidExtraFileSystems` | r/w? | persistent? | OS clears | private |
+|:------------------------------------------------|:----------------------------|:--------------------------|:----:|:-----------:|:---------:|:-------:|
+| `file:///android_asset/` | applicationDirectory | | r | N/A | N/A | Yes |
+| `/data/data/<app-id>/` | applicationStorageDirectory | - | r/w | N/A | N/A | Yes |
+| `cache` | cacheDirectory | cache | r/w | Yes | Yes\* | Yes |
+| `files` | dataDirectory | files | r/w | Yes | No | Yes |
+| `Documents` | | documents | r/w | Yes | No | Yes |
+| `<sdcard>/` | externalRootDirectory | sdcard | r/w | Yes | No | No |
+| `Android/data/<app-id>/` | externalApplicationStorageDirectory | - | r/w | Yes | No | No |
+| `cache` | externalCacheDirectry | cache-external | r/w | Yes | No\*\*| No |
+| `files` | externalDataDirectory | files-external | r/w | Yes | No | No |
+
+\* The OS may periodically clear this directory, but do not rely on this behavior. Clear
+ the contents of this directory as appropriate for your application. Should a user
+ purge the cache manually, the contents of this directory are removed.
+
+\*\* The OS does not clear this directory automatically; you are responsible for managing
+ the contents yourself. Should the user purge the cache manually, the contents of the
+ directory are removed.
+
+**Note**: If external storage can't be mounted, the `cordova.file.external*`
+properties are `null`.
+
+### BlackBerry 10 File System Layout
+
+| Device Path | `cordova.file.*` | r/w? | persistent? | OS clears | private |
+|:-------------------------------------------------------------|:----------------------------|:----:|:-----------:|:---------:|:-------:|
+| `file:///accounts/1000/appdata/<app id>/` | applicationStorageDirectory | r | N/A | N/A | Yes |
+| `app/native` | applicationDirectory | r | N/A | N/A | Yes |
+| `data/webviews/webfs/temporary/local__0` | cacheDirectory | r/w | No | Yes | Yes |
+| `data/webviews/webfs/persistent/local__0` | dataDirectory | r/w | Yes | No | Yes |
+| `file:///accounts/1000/removable/sdcard` | externalRemovableDirectory | r/w | Yes | No | No |
+| `file:///accounts/1000/shared` | sharedDirectory | r/w | Yes | No | No |
+
+*Note*: When application is deployed to work perimeter, all paths are relative to /accounts/1000-enterprise.
+
+## Android Quirks
+
+### Android Persistent storage location
+
+There are multiple valid locations to store persistent files on an Android
+device. See [this page](http://developer.android.com/guide/topics/data/data-storage.html)
+for an extensive discussion of the various possibilities.
+
+Previous versions of the plugin would choose the location of the temporary and
+persistent files on startup, based on whether the device claimed that the SD
+Card (or equivalent storage partition) was mounted. If the SD Card was mounted,
+or if a large internal storage partition was available (such as on Nexus
+devices,) then the persistent files would be stored in the root of that space.
+This meant that all Cordova apps could see all of the files available on the
+card.
+
+If the SD card was not available, then previous versions would store data under
+`/data/data/<packageId>`, which isolates apps from each other, but may still
+cause data to be shared between users.
+
+It is now possible to choose whether to store files in the internal file
+storage location, or using the previous logic, with a preference in your
+application's `config.xml` file. To do this, add one of these two lines to
+`config.xml`:
+
+ <preference name="AndroidPersistentFileLocation" value="Internal" />
+
+ <preference name="AndroidPersistentFileLocation" value="Compatibility" />
+
+Without this line, the File plugin will use `Compatibility` as the default. If
+a preference tag is present, and is not one of these values, the application
+will not start.
+
+If your application has previously been shipped to users, using an older (pre-
+1.0) version of this plugin, and has stored files in the persistent filesystem,
+then you should set the preference to `Compatibility`. Switching the location to
+"Internal" would mean that existing users who upgrade their application may be
+unable to access their previously-stored files, depending on their device.
+
+If your application is new, or has never previously stored files in the
+persistent filesystem, then the `Internal` setting is generally recommended.
+
+
+## iOS Quirks
+
+- `cordova.file.applicationStorageDirectory` is read-only; attempting to store
+ files within the root directory will fail. Use one of the other `cordova.file.*`
+ properties defined for iOS (only `applicationDirectory` and `applicationStorageDirectory` are
+ read-only).
+- `FileReader.readAsText(blob, encoding)`
+ - The `encoding` parameter is not supported, and UTF-8 encoding is always in effect.
+
+### iOS Persistent storage location
+
+There are two valid locations to store persistent files on an iOS device: the
+Documents directory and the Library directory. Previous versions of the plugin
+only ever stored persistent files in the Documents directory. This had the
+side-effect of making all of an application's files visible in iTunes, which
+was often unintended, especially for applications which handle lots of small
+files, rather than producing complete documents for export, which is the
+intended purpose of the directory.
+
+It is now possible to choose whether to store files in the documents or library
+directory, with a preference in your application's `config.xml` file. To do this,
+add one of these two lines to `config.xml`:
+
+ <preference name="iosPersistentFileLocation" value="Library" />
+
+ <preference name="iosPersistentFileLocation" value="Compatibility" />
+
+Without this line, the File plugin will use `Compatibility` as the default. If
+a preference tag is present, and is not one of these values, the application
+will not start.
+
+If your application has previously been shipped to users, using an older (pre-
+1.0) version of this plugin, and has stored files in the persistent filesystem,
+then you should set the preference to `Compatibility`. Switching the location to
+`Library` would mean that existing users who upgrade their application would be
+unable to access their previously-stored files.
+
+If your application is new, or has never previously stored files in the
+persistent filesystem, then the `Library` setting is generally recommended.
+
+## Firefox OS Quirks
+
+The File System API is not natively supported by Firefox OS and is implemented
+as a shim on top of indexedDB.
+
+* Does not fail when removing non-empty directories
+* Does not support metadata for directories
+* Methods `copyTo` and `moveTo` do not support directories
+
+The following data paths are supported:
+* `applicationDirectory` - Uses `xhr` to get local files that are packaged with the app.
+* `dataDirectory` - For persistent app-specific data files.
+* `cacheDirectory` - Cached files that should survive app restarts (Apps should not rely
+on the OS to delete files in here).
+
+## Browser Quirks
+
+### Common quirks and remarks
+- Each browser uses its own sandboxed filesystem. IE and Firefox use IndexedDB as a base.
+All browsers use forward slash as directory separator in a path.
+- Directory entries have to be created successively.
+For example, the call `fs.root.getDirectory('dir1/dir2', {create:true}, successCallback, errorCallback)`
+will fail if dir1 did not exist.
+- The plugin requests user permission to use persistent storage at the application first start.
+- Plugin supports `cdvfile://localhost` (local resources) only. I.e. external resources are not supported via `cdvfile`.
+- The plugin does not follow ["File System API 8.3 Naming restrictions"](http://www.w3.org/TR/2011/WD-file-system-api-20110419/#naming-restrictions).
+- Blob and File' `close` function is not supported.
+- `FileSaver` and `BlobBuilder` are not supported by this plugin and don't have stubs.
+- The plugin does not support `requestAllFileSystems`. This function is also missing in the specifications.
+- Entries in directory will not be removed if you use `create: true` flag for existing directory.
+- Files created via constructor are not supported. You should use entry.file method instead.
+- Each browser uses its own form for blob URL references.
+- `readAsDataURL` function is supported, but the mediatype in Chrome depends on entry name extension,
+mediatype in IE is always empty (which is the same as `text-plain` according the specification),
+the mediatype in Firefox is always `application/octet-stream`.
+For example, if the content is `abcdefg` then Firefox returns `data:application/octet-stream;base64,YWJjZGVmZw==`,
+IE returns `data:;base64,YWJjZGVmZw==`, Chrome returns `data:<mediatype depending on extension of entry name>;base64,YWJjZGVmZw==`.
+- `toInternalURL` returns the path in the form `file:///persistent/path/to/entry` (Firefox, IE).
+Chrome returns the path in the form `cdvfile://localhost/persistent/file`.
+
+### Chrome quirks
+- Chrome filesystem is not immediately ready after device ready event. As a workaround you can subscribe to `filePluginIsReady` event.
+Example:
+```javascript
+window.addEventListener('filePluginIsReady', function(){ console.log('File plugin is ready');}, false);
+```
+You can use `window.isFilePluginReadyRaised` function to check whether event was already raised.
+- window.requestFileSystem TEMPORARY and PERSISTENT filesystem quotas are not limited in Chrome.
+- To increase persistent storage in Chrome you need to call `window.initPersistentFileSystem` method. Persistent storage quota is 5 MB by default.
+- Chrome requires `--allow-file-access-from-files` run argument to support API via `file:///` protocol.
+- `File` object will be not changed if you use flag `{create:true}` when getting an existing `Entry`.
+- events `cancelable` property is set to true in Chrome. This is contrary to the [specification](http://dev.w3.org/2009/dap/file-system/file-writer.html).
+- `toURL` function in Chrome returns `filesystem:`-prefixed path depending on application host.
+For example, `filesystem:file:///persistent/somefile.txt`, `filesystem:http://localhost:8080/persistent/somefile.txt`.
+- `toURL` function result does not contain trailing slash in case of directory entry.
+Chrome resolves directories with slash-trailed urls correctly though.
+- `resolveLocalFileSystemURL` method requires the inbound `url` to have `filesystem` prefix. For example, `url` parameter for `resolveLocalFileSystemURL`
+should be in the form `filesystem:file:///persistent/somefile.txt` as opposed to the form `file:///persistent/somefile.txt` in Android.
+- Deprecated `toNativeURL` function is not supported and does not have a stub.
+- `setMetadata` function is not stated in the specifications and not supported.
+- INVALID_MODIFICATION_ERR (code: 9) is thrown instead of SYNTAX_ERR(code: 8) on requesting of a non-existant filesystem.
+- INVALID_MODIFICATION_ERR (code: 9) is thrown instead of PATH_EXISTS_ERR(code: 12) on trying to exclusively create a file or directory, which already exists.
+- INVALID_MODIFICATION_ERR (code: 9) is thrown instead of NO_MODIFICATION_ALLOWED_ERR(code: 6) on trying to call removeRecursively on the root file system.
+- INVALID_MODIFICATION_ERR (code: 9) is thrown instead of NOT_FOUND_ERR(code: 1) on trying to moveTo directory that does not exist.
+
+### IndexedDB-based impl quirks (Firefox and IE)
+- `.` and `..` are not supported.
+- IE does not support `file:///`-mode; only hosted mode is supported (http://localhost:xxxx).
+- Firefox filesystem size is not limited but each 50MB extension will request a user permission.
+IE10 allows up to 10mb of combined AppCache and IndexedDB used in implementation of filesystem without prompting,
+once you hit that level you will be asked if you want to allow it to be increased up to a max of 250mb per site.
+So `size` parameter for `requestFileSystem` function does not affect filesystem in Firefox and IE.
+- `readAsBinaryString` function is not stated in the Specs and not supported in IE and does not have a stub.
+- `file.type` is always null.
+- You should not create entry using DirectoryEntry instance callback result which was deleted.
+Otherwise, you will get a 'hanging entry'.
+- Before you can read a file, which was just written you need to get a new instance of this file.
+- `setMetadata` function, which is not stated in the Specs supports `modificationTime` field change only.
+- `copyTo` and `moveTo` functions do not support directories.
+- Directories metadata is not supported.
+- Both Entry.remove and directoryEntry.removeRecursively don't fail when removing
+non-empty directories - directories being removed are cleaned along with contents instead.
+- `abort` and `truncate` functions are not supported.
+- progress events are not fired. For example, this handler will be not executed:
+```javascript
+writer.onprogress = function() { /*commands*/ };
+```
+
+## Upgrading Notes
+
+In v1.0.0 of this plugin, the `FileEntry` and `DirectoryEntry` structures have changed,
+to be more in line with the published specification.
+
+Previous (pre-1.0.0) versions of the plugin stored the device-absolute-file-location
+in the `fullPath` property of `Entry` objects. These paths would typically look like
+
+ /var/mobile/Applications/<application UUID>/Documents/path/to/file (iOS)
+ /storage/emulated/0/path/to/file (Android)
+
+These paths were also returned by the `toURL()` method of the `Entry` objects.
+
+With v1.0.0, the `fullPath` attribute is the path to the file, _relative to the root of
+the HTML filesystem_. So, the above paths would now both be represented by a `FileEntry`
+object with a `fullPath` of
+
+ /path/to/file
+
+If your application works with device-absolute-paths, and you previously retrieved those
+paths through the `fullPath` property of `Entry` objects, then you should update your code
+to use `entry.toURL()` instead.
+
+For backwards compatibility, the `resolveLocalFileSystemURL()` method will accept a
+device-absolute-path, and will return an `Entry` object corresponding to it, as long as that
+file exists within either the `TEMPORARY` or `PERSISTENT` filesystems.
+
+This has particularly been an issue with the File-Transfer plugin, which previously used
+device-absolute-paths (and can still accept them). It has been updated to work correctly
+with FileSystem URLs, so replacing `entry.fullPath` with `entry.toURL()` should resolve any
+issues getting that plugin to work with files on the device.
+
+In v1.1.0 the return value of `toURL()` was changed (see [CB-6394] (https://issues.apache.org/jira/browse/CB-6394))
+to return an absolute 'file://' URL. wherever possible. To ensure a 'cdvfile:'-URL you can use `toInternalURL()` now.
+This method will now return filesystem URLs of the form
+
+ cdvfile://localhost/persistent/path/to/file
+
+which can be used to identify the file uniquely.
+
+## List of Error Codes and Meanings
+When an error is thrown, one of the following codes will be used.
+
+| Code | Constant |
+|-----:|:------------------------------|
+| 1 | `NOT_FOUND_ERR` |
+| 2 | `SECURITY_ERR` |
+| 3 | `ABORT_ERR` |
+| 4 | `NOT_READABLE_ERR` |
+| 5 | `ENCODING_ERR` |
+| 6 | `NO_MODIFICATION_ALLOWED_ERR` |
+| 7 | `INVALID_STATE_ERR` |
+| 8 | `SYNTAX_ERR` |
+| 9 | `INVALID_MODIFICATION_ERR` |
+| 10 | `QUOTA_EXCEEDED_ERR` |
+| 11 | `TYPE_MISMATCH_ERR` |
+| 12 | `PATH_EXISTS_ERR` |
+
+## Configuring the Plugin (Optional)
+
+The set of available filesystems can be configured per-platform. Both iOS and
+Android recognize a <preference> tag in `config.xml` which names the
+filesystems to be installed. By default, all file-system roots are enabled.
+
+ <preference name="iosExtraFilesystems" value="library,library-nosync,documents,documents-nosync,cache,bundle,root" />
+ <preference name="AndroidExtraFilesystems" value="files,files-external,documents,sdcard,cache,cache-external,root" />
+
+### 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). You must have the `android.permission.WRITE_EXTERNAL_STORAGE` permission to use this.
+* `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
+* `bundle`: The application's bundle; the location of the app itself on disk (read-only)
+* `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.
http://git-wip-us.apache.org/repos/asf/cordova-plugin-file/blob/caadf608/doc/index.md
----------------------------------------------------------------------
diff --git a/doc/index.md b/doc/index.md
deleted file mode 100644
index 26f0919..0000000
--- a/doc/index.md
+++ /dev/null
@@ -1,445 +0,0 @@
-<!---
- Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
--->
-
-# org.apache.cordova.file
-
-
-This plugin implements a File API allowing read/write access to files residing on the device.
-
-This plugin is based on several specs, including :
-The HTML5 File API
-[http://www.w3.org/TR/FileAPI/](http://www.w3.org/TR/FileAPI/)
-
-The (now-defunct) Directories and System extensions
-Latest:
-[http://www.w3.org/TR/2012/WD-file-system-api-20120417/](http://www.w3.org/TR/2012/WD-file-system-api-20120417/)
-Although most of the plugin code was written when an earlier spec was current:
-[http://www.w3.org/TR/2011/WD-file-system-api-20110419/](http://www.w3.org/TR/2011/WD-file-system-api-20110419/)
-
-It also implements the FileWriter spec :
-[http://dev.w3.org/2009/dap/file-system/file-writer.html](http://dev.w3.org/2009/dap/file-system/file-writer.html)
-
-For usage, please refer to HTML5 Rocks' excellent [FileSystem article.](http://www.html5rocks.com/en/tutorials/file/filesystem/)
-
-For an overview of other storage options, refer to Cordova's
-[storage guide](http://cordova.apache.org/docs/en/edge/cordova_storage_storage.md.html).
-
-This plugin defines global `cordova.file` object.
-
-Although in the global scope, it is not available until after the `deviceready` event.
-
- document.addEventListener("deviceready", onDeviceReady, false);
- function onDeviceReady() {
- console.log(cordova.file);
- }
-
-## Installation
-
- cordova plugin add org.apache.cordova.file
-
-## Supported Platforms
-
-- Amazon Fire OS
-- Android
-- BlackBerry 10
-- Firefox OS
-- iOS
-- Windows Phone 7 and 8*
-- Windows 8*
-- Browser
-
-\* _These platforms do not support `FileReader.readAsArrayBuffer` nor `FileWriter.write(blob)`._
-
-## Where to Store Files
-
-As of v1.2.0, URLs to important file-system directories are provided.
-Each URL is in the form _file:///path/to/spot/_, and can be converted to a
-`DirectoryEntry` using `window.resolveLocalFileSystemURL()`.
-
-* `cordova.file.applicationDirectory` - Read-only directory where the application
- is installed. (_iOS_, _Android_, _BlackBerry 10_)
-
-* `cordova.file.applicationStorageDirectory` - Root directory of the application's
- sandbox; on iOS this location is read-only (but specific subdirectories [like
- `/Documents`] are read-write). All data contained within is private to the app. (
- _iOS_, _Android_, _BlackBerry 10_)
-
-* `cordova.file.dataDirectory` - Persistent and private data storage within the
- application's sandbox using internal memory (on Android, if you need to use
- external memory, use `.externalDataDirectory`). On iOS, this directory is not
- synced with iCloud (use `.syncedDataDirectory`). (_iOS_, _Android_, _BlackBerry 10_)
-
-* `cordova.file.cacheDirectory` - Directory for cached data files or any files
- that your app can re-create easily. The OS may delete these files when the device
- runs low on storage, nevertheless, apps should not rely on the OS to delete files
- in here. (_iOS_, _Android_, _BlackBerry 10_)
-
-* `cordova.file.externalApplicationStorageDirectory` - Application space on
- external storage. (_Android_)
-
-* `cordova.file.externalDataDirectory` - Where to put app-specific data files on
- external storage. (_Android_)
-
-* `cordova.file.externalCacheDirectory` - Application cache on external storage.
- (_Android_)
-
-* `cordova.file.externalRootDirectory` - External storage (SD card) root. (_Android_, _BlackBerry 10_)
-
-* `cordova.file.tempDirectory` - Temp directory that the OS can clear at will. Do not
- rely on the OS to clear this directory; your app should always remove files as
- applicable. (_iOS_)
-
-* `cordova.file.syncedDataDirectory` - Holds app-specific files that should be synced
- (e.g. to iCloud). (_iOS_)
-
-* `cordova.file.documentsDirectory` - Files private to the app, but that are meaningful
- to other application (e.g. Office files). (_iOS_)
-
-* `cordova.file.sharedDirectory` - Files globally available to all applications (_BlackBerry 10_)
-
-## File System Layouts
-
-Although technically an implementation detail, it can be very useful to know how
-the `cordova.file.*` properties map to physical paths on a real device.
-
-### iOS File System Layout
-
-| Device Path | `cordova.file.*` | `iosExtraFileSystems` | r/w? | persistent? | OS clears | sync | private |
-|:-----------------------------------------------|:----------------------------|:----------------------|:----:|:-----------:|:---------:|:----:|:-------:|
-| `/var/mobile/Applications/<UUID>/` | applicationStorageDirectory | - | r | N/A | N/A | N/A | Yes |
-| `appname.app/` | applicationDirectory | bundle | r | N/A | N/A | N/A | Yes |
-| `www/` | - | - | r | N/A | N/A | N/A | Yes |
-| `Documents/` | documentsDirectory | documents | r/w | Yes | No | Yes | Yes |
-| `NoCloud/` | - | documents-nosync | r/w | Yes | No | No | Yes |
-| `Library` | - | library | r/w | Yes | No | Yes? | Yes |
-| `NoCloud/` | dataDirectory | library-nosync | r/w | Yes | No | No | Yes |
-| `Cloud/` | syncedDataDirectory | - | r/w | Yes | No | Yes | Yes |
-| `Caches/` | cacheDirectory | cache | r/w | Yes* | Yes\*\*\*| No | Yes |
-| `tmp/` | tempDirectory | - | r/w | No\*\* | Yes\*\*\*| No | Yes |
-
-
- \* Files persist across app restarts and upgrades, but this directory can
- be cleared whenever the OS desires. Your app should be able to recreate any
- content that might be deleted.
-
-\*\* Files may persist across app restarts, but do not rely on this behavior. Files
- are not guaranteed to persist across updates. Your app should remove files from
- this directory when it is applicable, as the OS does not guarantee when (or even
- if) these files are removed.
-
-\*\*\* The OS may clear the contents of this directory whenever it feels it is
- necessary, but do not rely on this. You should clear this directory as
- appropriate for your application.
-
-### Android File System Layout
-
-| Device Path | `cordova.file.*` | `AndroidExtraFileSystems` | r/w? | persistent? | OS clears | private |
-|:------------------------------------------------|:----------------------------|:--------------------------|:----:|:-----------:|:---------:|:-------:|
-| `file:///android_asset/` | applicationDirectory | | r | N/A | N/A | Yes |
-| `/data/data/<app-id>/` | applicationStorageDirectory | - | r/w | N/A | N/A | Yes |
-| `cache` | cacheDirectory | cache | r/w | Yes | Yes\* | Yes |
-| `files` | dataDirectory | files | r/w | Yes | No | Yes |
-| `Documents` | | documents | r/w | Yes | No | Yes |
-| `<sdcard>/` | externalRootDirectory | sdcard | r/w | Yes | No | No |
-| `Android/data/<app-id>/` | externalApplicationStorageDirectory | - | r/w | Yes | No | No |
-| `cache` | externalCacheDirectry | cache-external | r/w | Yes | No\*\*| No |
-| `files` | externalDataDirectory | files-external | r/w | Yes | No | No |
-
-\* The OS may periodically clear this directory, but do not rely on this behavior. Clear
- the contents of this directory as appropriate for your application. Should a user
- purge the cache manually, the contents of this directory are removed.
-
-\*\* The OS does not clear this directory automatically; you are responsible for managing
- the contents yourself. Should the user purge the cache manually, the contents of the
- directory are removed.
-
-**Note**: If external storage can't be mounted, the `cordova.file.external*`
-properties are `null`.
-
-### BlackBerry 10 File System Layout
-
-| Device Path | `cordova.file.*` | r/w? | persistent? | OS clears | private |
-|:-------------------------------------------------------------|:----------------------------|:----:|:-----------:|:---------:|:-------:|
-| `file:///accounts/1000/appdata/<app id>/` | applicationStorageDirectory | r | N/A | N/A | Yes |
-| `app/native` | applicationDirectory | r | N/A | N/A | Yes |
-| `data/webviews/webfs/temporary/local__0` | cacheDirectory | r/w | No | Yes | Yes |
-| `data/webviews/webfs/persistent/local__0` | dataDirectory | r/w | Yes | No | Yes |
-| `file:///accounts/1000/removable/sdcard` | externalRemovableDirectory | r/w | Yes | No | No |
-| `file:///accounts/1000/shared` | sharedDirectory | r/w | Yes | No | No |
-
-*Note*: When application is deployed to work perimeter, all paths are relative to /accounts/1000-enterprise.
-
-## Android Quirks
-
-### Android Persistent storage location
-
-There are multiple valid locations to store persistent files on an Android
-device. See [this page](http://developer.android.com/guide/topics/data/data-storage.html)
-for an extensive discussion of the various possibilities.
-
-Previous versions of the plugin would choose the location of the temporary and
-persistent files on startup, based on whether the device claimed that the SD
-Card (or equivalent storage partition) was mounted. If the SD Card was mounted,
-or if a large internal storage partition was available (such as on Nexus
-devices,) then the persistent files would be stored in the root of that space.
-This meant that all Cordova apps could see all of the files available on the
-card.
-
-If the SD card was not available, then previous versions would store data under
-`/data/data/<packageId>`, which isolates apps from each other, but may still
-cause data to be shared between users.
-
-It is now possible to choose whether to store files in the internal file
-storage location, or using the previous logic, with a preference in your
-application's `config.xml` file. To do this, add one of these two lines to
-`config.xml`:
-
- <preference name="AndroidPersistentFileLocation" value="Internal" />
-
- <preference name="AndroidPersistentFileLocation" value="Compatibility" />
-
-Without this line, the File plugin will use `Compatibility` as the default. If
-a preference tag is present, and is not one of these values, the application
-will not start.
-
-If your application has previously been shipped to users, using an older (pre-
-1.0) version of this plugin, and has stored files in the persistent filesystem,
-then you should set the preference to `Compatibility`. Switching the location to
-"Internal" would mean that existing users who upgrade their application may be
-unable to access their previously-stored files, depending on their device.
-
-If your application is new, or has never previously stored files in the
-persistent filesystem, then the `Internal` setting is generally recommended.
-
-
-## iOS Quirks
-
-- `cordova.file.applicationStorageDirectory` is read-only; attempting to store
- files within the root directory will fail. Use one of the other `cordova.file.*`
- properties defined for iOS (only `applicationDirectory` and `applicationStorageDirectory` are
- read-only).
-- `FileReader.readAsText(blob, encoding)`
- - The `encoding` parameter is not supported, and UTF-8 encoding is always in effect.
-
-### iOS Persistent storage location
-
-There are two valid locations to store persistent files on an iOS device: the
-Documents directory and the Library directory. Previous versions of the plugin
-only ever stored persistent files in the Documents directory. This had the
-side-effect of making all of an application's files visible in iTunes, which
-was often unintended, especially for applications which handle lots of small
-files, rather than producing complete documents for export, which is the
-intended purpose of the directory.
-
-It is now possible to choose whether to store files in the documents or library
-directory, with a preference in your application's `config.xml` file. To do this,
-add one of these two lines to `config.xml`:
-
- <preference name="iosPersistentFileLocation" value="Library" />
-
- <preference name="iosPersistentFileLocation" value="Compatibility" />
-
-Without this line, the File plugin will use `Compatibility` as the default. If
-a preference tag is present, and is not one of these values, the application
-will not start.
-
-If your application has previously been shipped to users, using an older (pre-
-1.0) version of this plugin, and has stored files in the persistent filesystem,
-then you should set the preference to `Compatibility`. Switching the location to
-`Library` would mean that existing users who upgrade their application would be
-unable to access their previously-stored files.
-
-If your application is new, or has never previously stored files in the
-persistent filesystem, then the `Library` setting is generally recommended.
-
-## Firefox OS Quirks
-
-The File System API is not natively supported by Firefox OS and is implemented
-as a shim on top of indexedDB.
-
-* Does not fail when removing non-empty directories
-* Does not support metadata for directories
-* Methods `copyTo` and `moveTo` do not support directories
-
-The following data paths are supported:
-* `applicationDirectory` - Uses `xhr` to get local files that are packaged with the app.
-* `dataDirectory` - For persistent app-specific data files.
-* `cacheDirectory` - Cached files that should survive app restarts (Apps should not rely
-on the OS to delete files in here).
-
-## Browser Quirks
-
-### Common quirks and remarks
-- Each browser uses its own sandboxed filesystem. IE and Firefox use IndexedDB as a base.
-All browsers use forward slash as directory separator in a path.
-- Directory entries have to be created successively.
-For example, the call `fs.root.getDirectory('dir1/dir2', {create:true}, successCallback, errorCallback)`
-will fail if dir1 did not exist.
-- The plugin requests user permission to use persistent storage at the application first start.
-- Plugin supports `cdvfile://localhost` (local resources) only. I.e. external resources are not supported via `cdvfile`.
-- The plugin does not follow ["File System API 8.3 Naming restrictions"](http://www.w3.org/TR/2011/WD-file-system-api-20110419/#naming-restrictions).
-- Blob and File' `close` function is not supported.
-- `FileSaver` and `BlobBuilder` are not supported by this plugin and don't have stubs.
-- The plugin does not support `requestAllFileSystems`. This function is also missing in the specifications.
-- Entries in directory will not be removed if you use `create: true` flag for existing directory.
-- Files created via constructor are not supported. You should use entry.file method instead.
-- Each browser uses its own form for blob URL references.
-- `readAsDataURL` function is supported, but the mediatype in Chrome depends on entry name extension,
-mediatype in IE is always empty (which is the same as `text-plain` according the specification),
-the mediatype in Firefox is always `application/octet-stream`.
-For example, if the content is `abcdefg` then Firefox returns `data:application/octet-stream;base64,YWJjZGVmZw==`,
-IE returns `data:;base64,YWJjZGVmZw==`, Chrome returns `data:<mediatype depending on extension of entry name>;base64,YWJjZGVmZw==`.
-- `toInternalURL` returns the path in the form `file:///persistent/path/to/entry` (Firefox, IE).
-Chrome returns the path in the form `cdvfile://localhost/persistent/file`.
-
-### Chrome quirks
-- Chrome filesystem is not immediately ready after device ready event. As a workaround you can subscribe to `filePluginIsReady` event.
-Example:
-```javascript
-window.addEventListener('filePluginIsReady', function(){ console.log('File plugin is ready');}, false);
-```
-You can use `window.isFilePluginReadyRaised` function to check whether event was already raised.
-- window.requestFileSystem TEMPORARY and PERSISTENT filesystem quotas are not limited in Chrome.
-- To increase persistent storage in Chrome you need to call `window.initPersistentFileSystem` method. Persistent storage quota is 5 MB by default.
-- Chrome requires `--allow-file-access-from-files` run argument to support API via `file:///` protocol.
-- `File` object will be not changed if you use flag `{create:true}` when getting an existing `Entry`.
-- events `cancelable` property is set to true in Chrome. This is contrary to the [specification](http://dev.w3.org/2009/dap/file-system/file-writer.html).
-- `toURL` function in Chrome returns `filesystem:`-prefixed path depending on application host.
-For example, `filesystem:file:///persistent/somefile.txt`, `filesystem:http://localhost:8080/persistent/somefile.txt`.
-- `toURL` function result does not contain trailing slash in case of directory entry.
-Chrome resolves directories with slash-trailed urls correctly though.
-- `resolveLocalFileSystemURL` method requires the inbound `url` to have `filesystem` prefix. For example, `url` parameter for `resolveLocalFileSystemURL`
-should be in the form `filesystem:file:///persistent/somefile.txt` as opposed to the form `file:///persistent/somefile.txt` in Android.
-- Deprecated `toNativeURL` function is not supported and does not have a stub.
-- `setMetadata` function is not stated in the specifications and not supported.
-- INVALID_MODIFICATION_ERR (code: 9) is thrown instead of SYNTAX_ERR(code: 8) on requesting of a non-existant filesystem.
-- INVALID_MODIFICATION_ERR (code: 9) is thrown instead of PATH_EXISTS_ERR(code: 12) on trying to exclusively create a file or directory, which already exists.
-- INVALID_MODIFICATION_ERR (code: 9) is thrown instead of NO_MODIFICATION_ALLOWED_ERR(code: 6) on trying to call removeRecursively on the root file system.
-- INVALID_MODIFICATION_ERR (code: 9) is thrown instead of NOT_FOUND_ERR(code: 1) on trying to moveTo directory that does not exist.
-
-### IndexedDB-based impl quirks (Firefox and IE)
-- `.` and `..` are not supported.
-- IE does not support `file:///`-mode; only hosted mode is supported (http://localhost:xxxx).
-- Firefox filesystem size is not limited but each 50MB extension will request a user permission.
-IE10 allows up to 10mb of combined AppCache and IndexedDB used in implementation of filesystem without prompting,
-once you hit that level you will be asked if you want to allow it to be increased up to a max of 250mb per site.
-So `size` parameter for `requestFileSystem` function does not affect filesystem in Firefox and IE.
-- `readAsBinaryString` function is not stated in the Specs and not supported in IE and does not have a stub.
-- `file.type` is always null.
-- You should not create entry using DirectoryEntry instance callback result which was deleted.
-Otherwise, you will get a 'hanging entry'.
-- Before you can read a file, which was just written you need to get a new instance of this file.
-- `setMetadata` function, which is not stated in the Specs supports `modificationTime` field change only.
-- `copyTo` and `moveTo` functions do not support directories.
-- Directories metadata is not supported.
-- Both Entry.remove and directoryEntry.removeRecursively don't fail when removing
-non-empty directories - directories being removed are cleaned along with contents instead.
-- `abort` and `truncate` functions are not supported.
-- progress events are not fired. For example, this handler will be not executed:
-```javascript
-writer.onprogress = function() { /*commands*/ };
-```
-
-## Upgrading Notes
-
-In v1.0.0 of this plugin, the `FileEntry` and `DirectoryEntry` structures have changed,
-to be more in line with the published specification.
-
-Previous (pre-1.0.0) versions of the plugin stored the device-absolute-file-location
-in the `fullPath` property of `Entry` objects. These paths would typically look like
-
- /var/mobile/Applications/<application UUID>/Documents/path/to/file (iOS)
- /storage/emulated/0/path/to/file (Android)
-
-These paths were also returned by the `toURL()` method of the `Entry` objects.
-
-With v1.0.0, the `fullPath` attribute is the path to the file, _relative to the root of
-the HTML filesystem_. So, the above paths would now both be represented by a `FileEntry`
-object with a `fullPath` of
-
- /path/to/file
-
-If your application works with device-absolute-paths, and you previously retrieved those
-paths through the `fullPath` property of `Entry` objects, then you should update your code
-to use `entry.toURL()` instead.
-
-For backwards compatibility, the `resolveLocalFileSystemURL()` method will accept a
-device-absolute-path, and will return an `Entry` object corresponding to it, as long as that
-file exists within either the `TEMPORARY` or `PERSISTENT` filesystems.
-
-This has particularly been an issue with the File-Transfer plugin, which previously used
-device-absolute-paths (and can still accept them). It has been updated to work correctly
-with FileSystem URLs, so replacing `entry.fullPath` with `entry.toURL()` should resolve any
-issues getting that plugin to work with files on the device.
-
-In v1.1.0 the return value of `toURL()` was changed (see [CB-6394] (https://issues.apache.org/jira/browse/CB-6394))
-to return an absolute 'file://' URL. wherever possible. To ensure a 'cdvfile:'-URL you can use `toInternalURL()` now.
-This method will now return filesystem URLs of the form
-
- cdvfile://localhost/persistent/path/to/file
-
-which can be used to identify the file uniquely.
-
-## List of Error Codes and Meanings
-When an error is thrown, one of the following codes will be used.
-
-| Code | Constant |
-|-----:|:------------------------------|
-| 1 | `NOT_FOUND_ERR` |
-| 2 | `SECURITY_ERR` |
-| 3 | `ABORT_ERR` |
-| 4 | `NOT_READABLE_ERR` |
-| 5 | `ENCODING_ERR` |
-| 6 | `NO_MODIFICATION_ALLOWED_ERR` |
-| 7 | `INVALID_STATE_ERR` |
-| 8 | `SYNTAX_ERR` |
-| 9 | `INVALID_MODIFICATION_ERR` |
-| 10 | `QUOTA_EXCEEDED_ERR` |
-| 11 | `TYPE_MISMATCH_ERR` |
-| 12 | `PATH_EXISTS_ERR` |
-
-## Configuring the Plugin (Optional)
-
-The set of available filesystems can be configured per-platform. Both iOS and
-Android recognize a <preference> tag in `config.xml` which names the
-filesystems to be installed. By default, all file-system roots are enabled.
-
- <preference name="iosExtraFilesystems" value="library,library-nosync,documents,documents-nosync,cache,bundle,root" />
- <preference name="AndroidExtraFilesystems" value="files,files-external,documents,sdcard,cache,cache-external,root" />
-
-### 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). You must have the `android.permission.WRITE_EXTERNAL_STORAGE` permission to use this.
-* `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
-* `bundle`: The application's bundle; the location of the app itself on disk (read-only)
-* `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.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@cordova.apache.org
For additional commands, e-mail: commits-help@cordova.apache.org