Added: cordova/site/public/docs/en/6.x/cordova-plugin-file/index.html URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/6.x/cordova-plugin-file/index.html?rev=1734016&view=auto ============================================================================== --- cordova/site/public/docs/en/6.x/cordova-plugin-file/index.html (added) +++ cordova/site/public/docs/en/6.x/cordova-plugin-file/index.html Tue Mar 8 01:36:30 2016 @@ -0,0 +1,3674 @@ +<!DOCTYPE html> +<html lang="en"> +<head> + <meta charset="utf-8"> + <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta name="format-detection" content="telephone=no"> + <meta name="viewport" content="user-scalable=no, initial-scale=1, maximum-scale=1, minimum-scale=1, width=device-width" /> + <meta name="description" content=" "> + + <title> + + Apache Cordova + + </title> + + <link rel="SHORTCUT ICON" href="/favicon.ico"/> + <link rel="canonical" href="https://cordova.apache.org/docs/en/6.x/cordova-plugin-file/"> + + <!-- CSS --> + <link rel="stylesheet" type="text/css" href="/static/css/main.css"> + + + <link rel="stylesheet" type="text/css" href="/static/js/lib/prettify/prettify.css"> + + + <!-- HTML5 shim and Respond.js for IE8 support of HTML5 elements and media queries --> + <!--[if lt IE 9]> + <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script> + <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script> + <![endif]--> + <script type="text/javascript"> + var disqus_developer = 1; // this would set it to developer mode + </script> + + <!-- JS --> + <script defer type="text/javascript" src="/static/js/lib/jquery-2.1.1.min.js"></script> + <script defer type="text/javascript" src="/static/js/lib/bootstrap.min.js"></script> + <script defer type="text/javascript" src="/static/js/lib/ZeroClipboard.js"></script> +</head> + +<body> + <header> + <a class="scroll-point pt-top" name="top"></a> + <nav class="navbar navbar-inverse navbar-fixed-top"> + <div class="container-fluid"> + <div class="navbar-header"> + <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false" aria-controls="navbar"> + <span class="sr-only">Toggle navigation</span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + <span class="icon-bar"></span> + </button> + <a class="navbar-brand" href="/"><img id="logo_top" src="/static/img/cordova-logo-newbrand.svg"/></a> + </div> + <div id="navbar" class="navbar-collapse collapse"> + <div class="nav_bar_center"> + <ul class="nav navbar-nav"> + <li class="active"> + <a href="/docs/en/latest/guide/overview/">Documentation</a> + </li> + <li > + <a href="/plugins">Plugins</a> + </li> + <li > + <a href="/blog" id="blog_button">Blog<span class="badge" id="new_blog_count"></span></a> + </li> + <li > + <a href="/contribute">Contribute</a> + </li> + <li> + <a href="/#getstarted">Get Started</a> + </li> + </ul> + <form action="https://www.google.com/search" method="GET" class="navbar-form navbar-right" id="header-search-form" role="search"> + <div class="input-group"> + <input type="text" name="q" class="form-control hidden-sm" placeholder="Site-wide Search"> + <span class="input-group-btn"> + <button type="submit" class="btn search-button"> + <span class="glyphicon glyphicon-search" aria-hidden="true"></span> + </button> + </span> + </div> + <input type="hidden" name="q" value="site:cordova.apache.org"> + </form> + </div> + </div><!--/.navbar-collapse --> + </div> + </nav> + <div id="_fixed_navbar_spacer" style="padding-top:50px"></div> +</header> + + <!-- Use the manual ToC, and if it doesn't exist, use the generated one --> + + + + + + + + + + + + +<div class="docs container"> + + <!-- Table of Contents --> + <div class="hidden-xs hidden-sm col-md-3 site-toc-container"> + <h2 class="site-toc-title">Table of Contents</h2> + <ul class="site-toc"> + + + + + + + + <li> + + <span class="toc-section-heading"> + Introduction + </span> + + + + + + + <ul class="site-toc"> + + + + + + <li> + + <a class="" href="../guide/overview/index.html"> + Overview + </a> + + + + + + + </li> + +</ul> + + + </li> + + + + + + + + <li> + + <span class="toc-section-heading"> + Create apps + </span> + + + + + + + <ul class="site-toc"> + + + + + + <li> + + <a class="" href="../guide/cli/index.html"> + Create your first app + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/support/index.html"> + Platform support + </a> + + + + + + + </li> + + + + + + + + <li> + + <span class="toc-section-heading"> + Develop for platforms + </span> + + + + + + + <ul class="site-toc"> + + + + + + <li> + + <a class="" href="../guide/platforms/android/index.html"> + Android + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/platforms/blackberry10/home.html"> + Blackberry 10 + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/platforms/ios/index.html"> + iOS + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/platforms/osx/index.html"> + OS X + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/platforms/ubuntu/index.html"> + Ubuntu + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/platforms/win8/index.html"> + Windows + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/platforms/wp8/home.html"> + WP8 + </a> + + + + + + + </li> + +</ul> + + + </li> + + + + + + <li> + + <a class="" href="../platform_plugin_versioning_ref/index.html"> + Manage versions and platforms + </a> + + + + + + + </li> + + + + + + + + + + + <li> + + <a class="" href="../config_ref/images.html"> + Customize icons + </a> + + + + + + + </li> + + + + + + + + + + + <li> + + <a class="" href="../cordova/storage/storage.html"> + Store data + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/appdev/privacy/index.html"> + Manage privacy + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/appdev/security/index.html"> + Manage security + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/appdev/whitelist/index.html"> + Whitelisting + </a> + + + + + + + </li> + + + + + + +</ul> + + + </li> + + + + + + + + <li> + + <span class="toc-section-heading"> + Create plugins + </span> + + + + + + + <ul class="site-toc"> + + + + + + <li> + + <a class="" href="../guide/hybrid/plugins/index.html"> + Create a plugin + </a> + + + + + + + </li> + + + + + + + + + + + + + <li> + + <span class="toc-section-heading"> + Develop for platforms + </span> + + + + + + + <ul class="site-toc"> + + + + + + <li> + + <a class="" href="../guide/platforms/android/plugin.html"> + Android + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/platforms/blackberry10/plugin.html"> + Blackberry 10 + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/platforms/ios/plugin.html"> + iOS + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/platforms/win8/plugin.html"> + Windows + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/platforms/wp8/plugin.html"> + WP8 + </a> + + + + + + + </li> + +</ul> + + + </li> + + + + + + <li> + + <a class="" href="../plugin_ref/plugman.html"> + Use Plugman + </a> + + + + + + + </li> + + + + + + +</ul> + + + </li> + + + + + + + + <li> + + <span class="toc-section-heading"> + Advanced Topics + </span> + + + + + + + <ul class="site-toc"> + + + + + + <li> + + <a class="" href="../guide/hybrid/webviews/index.html"> + Embed Cordova in native apps + </a> + + + + + + + </li> + + + + + + + + + + + <li> + + <a class="" href="../guide/next/index.html"> + Next Steps + </a> + + + + + + + </li> + +</ul> + + + </li> + + + + + + + + <li> + + <span class="toc-section-heading"> + Reference + </span> + + + + + + + <ul class="site-toc"> + + + + + + <li> + + <a class="" href="../config_ref/index.html"> + Config.xml + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova/events/events.html"> + Events + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-cli/index.html"> + CLI + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../guide/appdev/hooks/index.html"> + Hooks + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../plugin_ref/spec.html"> + Plugin.xml + </a> + + + + + + + </li> + + + + + + + + <li> + + <span class="toc-section-heading"> + Plugin APIs + </span> + + + + + + + <ul class="site-toc"> + + + + + + <li> + + <a class="" href="../cordova-plugin-battery-status/index.html"> + Battery Status + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-camera/index.html"> + Camera + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-console/index.html"> + Console + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-contacts/index.html"> + Contacts + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-device/index.html"> + Device + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-device-motion/index.html"> + Device Motion + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-device-orientation/index.html"> + Device Orientation + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-dialogs/index.html"> + Dialogs + </a> + + + + + + + </li> + + + + + + <li> + + <a class="this-page" href="../cordova-plugin-file/index.html"> + File + </a> + + + + <div id="page-toc" class="page-toc"></div> + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-file-transfer/index.html"> + File Transfer + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-geolocation/index.html"> + Geolocation + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-globalization/index.html"> + Globalization + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-inappbrowser/index.html"> + Inappbrowser + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-media/index.html"> + Media + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-media-capture/index.html"> + Media Capture + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-network-information/index.html"> + Network Information + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-splashscreen/index.html"> + Splashscreen + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-vibration/index.html"> + Vibration + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-statusbar/index.html"> + Statusbar + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-whitelist/index.html"> + Whitelist + </a> + + + + + + + </li> + + + + + + <li> + + <a class="" href="../cordova-plugin-legacy-whitelist/index.html"> + Legacy Whitelist + </a> + + + + + + + </li> + +</ul> + + + </li> + +</ul> + + + </li> + + + + + + +</ul> + + </div> + + <!-- Page content --> + <div class="col-md-8 col-md-offset-1"> + + <!-- ToC Dropdown (for XS and SM sizes only) --> + <div class="toc-dropdown content-header visible-xs-block visible-sm-block"> + <div class="dropdown"> + <button class="btn btn-default dropdown-toggle" type="button" id="tocDropdown" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true"> + Table of Contents + <span class="caret"></span> + </button> + <ul class="dropdown-menu"> + + + + + +<li> + <a class="" href="../guide/overview/index.html"> + Overview + </a> +</li> + + + + + + + + + + +<li> + <a class="" href="../guide/cli/index.html"> + Create your first app + </a> +</li> + + + + +<li> + <a class="" href="../guide/support/index.html"> + Platform support + </a> +</li> + + + + + + + +<li> + <a class="" href="../guide/platforms/android/index.html"> + Android + </a> +</li> + + + + +<li> + <a class="" href="../guide/platforms/blackberry10/home.html"> + Blackberry 10 + </a> +</li> + + + + +<li> + <a class="" href="../guide/platforms/ios/index.html"> + iOS + </a> +</li> + + + + +<li> + <a class="" href="../guide/platforms/osx/index.html"> + OS X + </a> +</li> + + + + +<li> + <a class="" href="../guide/platforms/ubuntu/index.html"> + Ubuntu + </a> +</li> + + + + +<li> + <a class="" href="../guide/platforms/win8/index.html"> + Windows + </a> +</li> + + + + +<li> + <a class="" href="../guide/platforms/wp8/home.html"> + WP8 + </a> +</li> + + + + + + + +<li> + <a class="" href="../platform_plugin_versioning_ref/index.html"> + Manage versions and platforms + </a> +</li> + + + + + + + +<li> + <a class="" href="../config_ref/images.html"> + Customize icons + </a> +</li> + + + + + + + +<li> + <a class="" href="../cordova/storage/storage.html"> + Store data + </a> +</li> + + + + +<li> + <a class="" href="../guide/appdev/privacy/index.html"> + Manage privacy + </a> +</li> + + + + +<li> + <a class="" href="../guide/appdev/security/index.html"> + Manage security + </a> +</li> + + + + +<li> + <a class="" href="../guide/appdev/whitelist/index.html"> + Whitelisting + </a> +</li> + + + + + + + + + + + + + +<li> + <a class="" href="../guide/hybrid/plugins/index.html"> + Create a plugin + </a> +</li> + + + + + + + + + + +<li> + <a class="" href="../guide/platforms/android/plugin.html"> + Android + </a> +</li> + + + + +<li> + <a class="" href="../guide/platforms/blackberry10/plugin.html"> + Blackberry 10 + </a> +</li> + + + + +<li> + <a class="" href="../guide/platforms/ios/plugin.html"> + iOS + </a> +</li> + + + + +<li> + <a class="" href="../guide/platforms/win8/plugin.html"> + Windows + </a> +</li> + + + + +<li> + <a class="" href="../guide/platforms/wp8/plugin.html"> + WP8 + </a> +</li> + + + + + + + +<li> + <a class="" href="../plugin_ref/plugman.html"> + Use Plugman + </a> +</li> + + + + + + + + + + + + + +<li> + <a class="" href="../guide/hybrid/webviews/index.html"> + Embed Cordova in native apps + </a> +</li> + + + + + + + +<li> + <a class="" href="../guide/next/index.html"> + Next Steps + </a> +</li> + + + + + + + + + + +<li> + <a class="" href="../config_ref/index.html"> + Config.xml + </a> +</li> + + + + +<li> + <a class="" href="../cordova/events/events.html"> + Events + </a> +</li> + + + + +<li> + <a class="" href="../cordova-cli/index.html"> + CLI + </a> +</li> + + + + +<li> + <a class="" href="../guide/appdev/hooks/index.html"> + Hooks + </a> +</li> + + + + +<li> + <a class="" href="../plugin_ref/spec.html"> + Plugin.xml + </a> +</li> + + + + + + + +<li> + <a class="" href="../cordova-plugin-battery-status/index.html"> + Battery Status + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-camera/index.html"> + Camera + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-console/index.html"> + Console + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-contacts/index.html"> + Contacts + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-device/index.html"> + Device + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-device-motion/index.html"> + Device Motion + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-device-orientation/index.html"> + Device Orientation + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-dialogs/index.html"> + Dialogs + </a> +</li> + + + + +<li> + <a class="this-page" href="../cordova-plugin-file/index.html"> + File + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-file-transfer/index.html"> + File Transfer + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-geolocation/index.html"> + Geolocation + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-globalization/index.html"> + Globalization + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-inappbrowser/index.html"> + Inappbrowser + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-media/index.html"> + Media + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-media-capture/index.html"> + Media Capture + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-network-information/index.html"> + Network Information + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-splashscreen/index.html"> + Splashscreen + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-vibration/index.html"> + Vibration + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-statusbar/index.html"> + Statusbar + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-whitelist/index.html"> + Whitelist + </a> +</li> + + + + +<li> + <a class="" href="../cordova-plugin-legacy-whitelist/index.html"> + Legacy Whitelist + </a> +</li> + + + + + + + + + + + + + + </ul> + </div> + </div> + + <div class="content-header"> + + <a class="edit" href="https://github.com/apache/cordova-plugin-file/blob/master/README.md"> + <span class="glyphicon glyphicon-pencil" aria-hidden="true"></span> Edit + </a> + + <!-- Language dropdown --> + <div class="dropdown"> + <button class="btn btn-default dropdown-toggle" type="button" id="languageDropdown" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true"> + English + <span class="caret"></span> + </button> + + <!-- List all languages --> + <ul class="dropdown-menu" aria-labelledby="languageDropdown"> + + + + + + + + + + + + + + <li> + <a href="/docs/de/6.x/cordova-plugin-file/index.html" class=" + + + " + > + + Deutsch + + </a> + </li> + + + + + + + + + + + + + + <li> + <a href="/docs/en/6.x/cordova-plugin-file/index.html" class=" + + + " + > + + <span class="selected"> + English + </span> + + </a> + </li> + + + + + + + + + + + + + + <li> + <a href="/docs/es/6.x/cordova-plugin-file/index.html" class=" + + + " + > + + Español + + </a> + </li> + + + + + + + + + + + + + + <li> + <a href="/docs/fr/6.x/cordova-plugin-file/index.html" class=" + + + " + > + + Français + + </a> + </li> + + + + + + + + + + + + + + <li> + <a href="/docs/it/6.x/cordova-plugin-file/index.html" class=" + + + " + > + + Italiano + + </a> + </li> + + + + + + + + + + + + + + <li> + <a href="/docs/ja/6.x/cordova-plugin-file/index.html" class=" + + + " + > + + æ¥æ¬èª + + </a> + </li> + + + + + + + + + + + + + + <li> + <a href="/docs/ko/6.x/cordova-plugin-file/index.html" class=" + + + " + > + + íêµì´ + + </a> + </li> + + + + + + + + + + + + + + <li> + <a href="/docs/pl/6.x/cordova-plugin-file/index.html" class=" + + + " + > + + Polski + + </a> + </li> + + + + + + + + + + + + + + <li> + <a href="/docs/ru/6.x/cordova-plugin-file/index.html" class=" + + + " + > + + Ð ÑÑÑкий + + </a> + </li> + + + + + + + + + + + + + + <li> + <a href="/docs/sl/6.x/cordova-plugin-file/index.html" class=" + + + " + > + + Slovene + + </a> + </li> + + + + + + + + + + + + + + <li> + <a href="/docs/zh/6.x/cordova-plugin-file/index.html" class=" + + + " + > + + æ±è¯ + + </a> + </li> + + </ul> + </div> + + <!-- Version dropdown --> + <div class="dropdown"> + <button class="btn btn-default dropdown-toggle" type="button" id="versionDropdown" data-toggle="dropdown" aria-haspopup="true" aria-expanded="true"> + 6.x + + (Latest) + + <span class="caret"></span> + </button> + <ul class="dropdown-menu" aria-labelledby="versionDropdown"> + + <!-- List versions available in this language --> + + <li> + + + + + + + + + <a href="/docs/en/dev/cordova-plugin-file/index.html"> + + + dev + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/6.x/cordova-plugin-file/index.html"> + + <span class="selected"> + + 6.x + + (Latest) + + + </span> + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/5.4.0/cordova-plugin-file/index.html"> + + + 5.4.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/5.1.1/cordova-plugin-file/index.html"> + + + 5.1.1 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/5.0.0/cordova-plugin-file/index.html"> + + + 5.0.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/4.0.0/cordova-plugin-file/index.html"> + + + 4.0.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/3.6.0/cordova-plugin-file/index.html"> + + + 3.6.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/3.5.0/cordova-plugin-file/index.html"> + + + 3.5.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/3.4.0/cordova-plugin-file/index.html"> + + + 3.4.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/3.3.0/cordova-plugin-file/index.html"> + + + 3.3.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/3.2.0/cordova-plugin-file/index.html"> + + + 3.2.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/3.1.0/cordova-plugin-file/index.html"> + + + 3.1.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/3.0.0/cordova-plugin-file/index.html"> + + + 3.0.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/2.9.0/cordova-plugin-file/index.html"> + + + 2.9.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/2.8.0/cordova-plugin-file/index.html"> + + + 2.8.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/2.7.0/cordova-plugin-file/index.html"> + + + 2.7.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/2.6.0/cordova-plugin-file/index.html"> + + + 2.6.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/2.5.0/cordova-plugin-file/index.html"> + + + 2.5.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/2.4.0/cordova-plugin-file/index.html"> + + + 2.4.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/2.3.0/cordova-plugin-file/index.html"> + + + 2.3.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/2.2.0/cordova-plugin-file/index.html"> + + + 2.2.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/2.1.0/cordova-plugin-file/index.html"> + + + 2.1.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/2.0.0/cordova-plugin-file/index.html"> + + + 2.0.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/1.9.0/cordova-plugin-file/index.html"> + + + 1.9.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/1.8.1/cordova-plugin-file/index.html"> + + + 1.8.1 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/1.8.0/cordova-plugin-file/index.html"> + + + 1.8.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/1.7.0/cordova-plugin-file/index.html"> + + + 1.7.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/1.6.1/cordova-plugin-file/index.html"> + + + 1.6.1 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/1.6.0/cordova-plugin-file/index.html"> + + + 1.6.0 + + + + </a> + </li> + + <li> + + + + + + + + + <a href="/docs/en/1.5.0/cordova-plugin-file/index.html"> + + + 1.5.0 + + + + </a> + </li> + + </ul> + </div> + </div> + + <!-- Get URL for this page in the latest version --> + + + + + <!-- Show warnings for special versions (i.e. non-latest, and dev) --> + + + + <div class="alert alert-warning docs-alert" role="alert"> + <button type="button" class="close" data-dismiss="alert" aria-label="Close"> + <span aria-hidden="true">×</span> + </button> + This documentation describes this plugin at version master. + <a href="https://github.com/apache/cordova-plugin-file/releases"> + Other versions are on GitHub. + </a> + </div> + + + + <div id="page-toc-source"> + <!-- +# license: 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. +--> + +<p><a href="https://travis-ci.org/apache/cordova-plugin-file"><img src="https://travis-ci.org/apache/cordova-plugin-file.svg?branch=master" alt="Build Status"></a></p> + +<h1>cordova-plugin-file</h1> + +<p>This plugin implements a File API allowing read/write access to files residing on the device.</p> + +<p>This plugin is based on several specs, including : +The HTML5 File API +<a href="http://www.w3.org/TR/FileAPI/">http://www.w3.org/TR/FileAPI/</a></p> + +<p>The (now-defunct) Directories and System extensions +Latest: +<a href="http://www.w3.org/TR/2012/WD-file-system-api-20120417/">http://www.w3.org/TR/2012/WD-file-system-api-20120417/</a> +Although most of the plugin code was written when an earlier spec was current: +<a href="http://www.w3.org/TR/2011/WD-file-system-api-20110419/">http://www.w3.org/TR/2011/WD-file-system-api-20110419/</a></p> + +<p>It also implements the FileWriter spec : +<a href="http://dev.w3.org/2009/dap/file-system/file-writer.html">http://dev.w3.org/2009/dap/file-system/file-writer.html</a></p> + +<p>For usage, please refer to HTML5 Rocks' excellent <a href="http://www.html5rocks.com/en/tutorials/file/filesystem/">FileSystem article.</a></p> + +<p>For an overview of other storage options, refer to Cordova's +<a href="http://cordova.apache.org/docs/en/edge/cordova_storage_storage.md.html">storage guide</a>.</p> + +<p>This plugin defines global <code class="prettyprint">cordova.file</code> object.</p> + +<p>Although in the global scope, it is not available until after the <code class="prettyprint">deviceready</code> event.</p> +<div class="highlight"><pre><code class="language-text" data-lang="text">document.addEventListener("deviceready", onDeviceReady, false); +function onDeviceReady() { + console.log(cordova.file); +} +</code></pre></div> +<p>Report issues on the <a href="https://issues.apache.org/jira/issues/?jql=project%20%3D%20CB%20AND%20status%20in%20%28Open%2C%20%22In%20Progress%22%2C%20Reopened%29%20AND%20resolution%20%3D%20Unresolved%20AND%20component%20%3D%20%22Plugin%20File%22%20ORDER%20BY%20priority%20DESC%2C%20summary%20ASC%2C%20updatedDate%20DESC">Apache Cordova issue tracker</a></p> + +<h2>Installation</h2> +<div class="highlight"><pre><code class="language-text" data-lang="text">cordova plugin add cordova-plugin-file +</code></pre></div> +<h2>Supported Platforms</h2> + +<ul> +<li>Amazon Fire OS</li> +<li>Android</li> +<li>BlackBerry 10</li> +<li>Firefox OS</li> +<li>iOS</li> +<li>OS X</li> +<li>Windows Phone 7 and 8*</li> +<li>Windows 8*</li> +<li>Windows*</li> +<li>Browser</li> +</ul> + +<p>* <em>These platforms do not support <code class="prettyprint">FileReader.readAsArrayBuffer</code> nor <code class="prettyprint">FileWriter.write(blob)</code>.</em></p> + +<h2>Where to Store Files</h2> + +<p>As of v1.2.0, URLs to important file-system directories are provided. +Each URL is in the form <em>file:///path/to/spot/</em>, and can be converted to a +<code class="prettyprint">DirectoryEntry</code> using <code class="prettyprint">window.resolveLocalFileSystemURL()</code>.</p> + +<ul> +<li><p><code class="prettyprint">cordova.file.applicationDirectory</code> - Read-only directory where the application +is installed. (<em>iOS</em>, <em>Android</em>, <em>BlackBerry 10</em>, <em>OSX</em>, <em>windows</em>)</p></li> +<li><p><code class="prettyprint">cordova.file.applicationStorageDirectory</code> - Root directory of the application's +sandbox; on iOS & windows this location is read-only (but specific subdirectories [like +<code class="prettyprint">/Documents</code> on iOS or <code class="prettyprint">/localState</code> on windows] are read-write). All data contained within +is private to the app. (<em>iOS</em>, <em>Android</em>, <em>BlackBerry 10</em>, <em>OSX</em>)</p></li> +<li><p><code class="prettyprint">cordova.file.dataDirectory</code> - Persistent and private data storage within the +application's sandbox using internal memory (on Android, if you need to use +external memory, use <code class="prettyprint">.externalDataDirectory</code>). On iOS, this directory is not +synced with iCloud (use <code class="prettyprint">.syncedDataDirectory</code>). (<em>iOS</em>, <em>Android</em>, <em>BlackBerry 10</em>, <em>windows</em>)</p></li> +<li><p><code class="prettyprint">cordova.file.cacheDirectory</code> - 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. (<em>iOS</em>, <em>Android</em>, <em>BlackBerry 10</em>, <em>OSX</em>, <em>windows</em>)</p></li> +<li><p><code class="prettyprint">cordova.file.externalApplicationStorageDirectory</code> - Application space on +external storage. (<em>Android</em>)</p></li> +<li><p><code class="prettyprint">cordova.file.externalDataDirectory</code> - Where to put app-specific data files on +external storage. (<em>Android</em>)</p></li> +<li><p><code class="prettyprint">cordova.file.externalCacheDirectory</code> - Application cache on external storage. +(<em>Android</em>)</p></li> +<li><p><code class="prettyprint">cordova.file.externalRootDirectory</code> - External storage (SD card) root. (<em>Android</em>, <em>BlackBerry 10</em>)</p></li> +<li><p><code class="prettyprint">cordova.file.tempDirectory</code> - 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. (<em>iOS</em>, <em>OSX</em>, <em>windows</em>)</p></li> +<li><p><code class="prettyprint">cordova.file.syncedDataDirectory</code> - Holds app-specific files that should be synced +(e.g. to iCloud). (<em>iOS</em>, <em>windows</em>)</p></li> +<li><p><code class="prettyprint">cordova.file.documentsDirectory</code> - Files private to the app, but that are meaningful +to other application (e.g. Office files). Note that for <em>OSX</em> this is the user's <code class="prettyprint">~/Documents</code> directory. (<em>iOS</em>, <em>OSX</em>)</p></li> +<li><p><code class="prettyprint">cordova.file.sharedDirectory</code> - Files globally available to all applications (<em>BlackBerry 10</em>)</p></li> +</ul> + +<h2>File System Layouts</h2> + +<p>Although technically an implementation detail, it can be very useful to know how +the <code class="prettyprint">cordova.file.*</code> properties map to physical paths on a real device.</p> + +<h3>iOS File System Layout</h3> + +<table><thead> +<tr> +<th style="text-align: left">Device Path</th> +<th style="text-align: left"><code class="prettyprint">cordova.file.*</code></th> +<th style="text-align: left"><code class="prettyprint">iosExtraFileSystems</code></th> +<th style="text-align: center">r/w?</th> +<th style="text-align: center">persistent?</th> +<th style="text-align: center">OS clears</th> +<th style="text-align: center">sync</th> +<th style="text-align: center">private</th> +</tr> +</thead><tbody> +<tr> +<td style="text-align: left"><code class="prettyprint">/var/mobile/Applications/<UUID>/</code></td> +<td style="text-align: left">applicationStorageDirectory</td> +<td style="text-align: left">-</td> +<td style="text-align: center">r</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">appname.app/</code></td> +<td style="text-align: left">applicationDirectory</td> +<td style="text-align: left">bundle</td> +<td style="text-align: center">r</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">www/</code></td> +<td style="text-align: left">-</td> +<td style="text-align: left">-</td> +<td style="text-align: center">r</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">Documents/</code></td> +<td style="text-align: left">documentsDirectory</td> +<td style="text-align: left">documents</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">NoCloud/</code></td> +<td style="text-align: left">-</td> +<td style="text-align: left">documents-nosync</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">Library</code></td> +<td style="text-align: left">-</td> +<td style="text-align: left">library</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes?</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">NoCloud/</code></td> +<td style="text-align: left">dataDirectory</td> +<td style="text-align: left">library-nosync</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">Cloud/</code></td> +<td style="text-align: left">syncedDataDirectory</td> +<td style="text-align: left">-</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">Caches/</code></td> +<td style="text-align: left">cacheDirectory</td> +<td style="text-align: left">cache</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes*</td> +<td style="text-align: center">Yes***</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">tmp/</code></td> +<td style="text-align: left">tempDirectory</td> +<td style="text-align: left">-</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">No**</td> +<td style="text-align: center">Yes***</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +</tr> +</tbody></table> + +<p>* 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.</p> + +<p>** 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.</p> + +<p>*** 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.</p> + +<h3>Android File System Layout</h3> + +<table><thead> +<tr> +<th style="text-align: left">Device Path</th> +<th style="text-align: left"><code class="prettyprint">cordova.file.*</code></th> +<th style="text-align: left"><code class="prettyprint">AndroidExtraFileSystems</code></th> +<th style="text-align: center">r/w?</th> +<th style="text-align: center">persistent?</th> +<th style="text-align: center">OS clears</th> +<th style="text-align: center">private</th> +</tr> +</thead><tbody> +<tr> +<td style="text-align: left"><code class="prettyprint">file:///android_asset/</code></td> +<td style="text-align: left">applicationDirectory</td> +<td style="text-align: left"></td> +<td style="text-align: center">r</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"><code class="prettyprint">/data/data/<app-id>/</code></td> +<td style="text-align: left">applicationStorageDirectory</td> +<td style="text-align: left">-</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">cache</code></td> +<td style="text-align: left">cacheDirectory</td> +<td style="text-align: left">cache</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">Yes*</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">files</code></td> +<td style="text-align: left">dataDirectory</td> +<td style="text-align: left">files</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">Documents</code></td> +<td style="text-align: left"></td> +<td style="text-align: left">documents</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"><code class="prettyprint"><sdcard>/</code></td> +<td style="text-align: left">externalRootDirectory</td> +<td style="text-align: left">sdcard</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">No</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">Android/data/<app-id>/</code></td> +<td style="text-align: left">externalApplicationStorageDirectory</td> +<td style="text-align: left">-</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">No</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">cache</code></td> +<td style="text-align: left">externalCacheDirectry</td> +<td style="text-align: left">cache-external</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No**</td> +<td style="text-align: center">No</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">files</code></td> +<td style="text-align: left">externalDataDirectory</td> +<td style="text-align: left">files-external</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">No</td> +</tr> +</tbody></table> + +<p>* 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.</p> + +<p>** 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.</p> + +<p><strong>Note</strong>: If external storage can't be mounted, the <code class="prettyprint">cordova.file.external*</code> +properties are <code class="prettyprint">null</code>.</p> + +<h3>BlackBerry 10 File System Layout</h3> + +<table><thead> +<tr> +<th style="text-align: left">Device Path</th> +<th style="text-align: left"><code class="prettyprint">cordova.file.*</code></th> +<th style="text-align: center">r/w?</th> +<th style="text-align: center">persistent?</th> +<th style="text-align: center">OS clears</th> +<th style="text-align: center">private</th> +</tr> +</thead><tbody> +<tr> +<td style="text-align: left"><code class="prettyprint">file:///accounts/1000/appdata/<app id>/</code></td> +<td style="text-align: left">applicationStorageDirectory</td> +<td style="text-align: center">r</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">app/native</code></td> +<td style="text-align: left">applicationDirectory</td> +<td style="text-align: center">r</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">data/webviews/webfs/temporary/local__0</code></td> +<td style="text-align: left">cacheDirectory</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">data/webviews/webfs/persistent/local__0</code></td> +<td style="text-align: left">dataDirectory</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"><code class="prettyprint">file:///accounts/1000/removable/sdcard</code></td> +<td style="text-align: left">externalRemovableDirectory</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">No</td> +</tr> +<tr> +<td style="text-align: left"><code class="prettyprint">file:///accounts/1000/shared</code></td> +<td style="text-align: left">sharedDirectory</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">No</td> +</tr> +</tbody></table> + +<p><em>Note</em>: When application is deployed to work perimeter, all paths are relative to /accounts/1000-enterprise.</p> + +<h3>OS X File System Layout</h3> + +<table><thead> +<tr> +<th style="text-align: left">Device Path</th> +<th style="text-align: left"><code class="prettyprint">cordova.file.*</code></th> +<th style="text-align: left"><code class="prettyprint">iosExtraFileSystems</code></th> +<th style="text-align: center">r/w?</th> +<th style="text-align: center">OS clears</th> +<th style="text-align: center">private</th> +</tr> +</thead><tbody> +<tr> +<td style="text-align: left"><code class="prettyprint">/Applications/<appname>.app/</code></td> +<td style="text-align: left">-</td> +<td style="text-align: left">bundle</td> +<td style="text-align: center">r</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">Content/Resources/</code></td> +<td style="text-align: left">applicationDirectory</td> +<td style="text-align: left">-</td> +<td style="text-align: center">r</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"><code class="prettyprint">~/Library/Application Support/<bundle-id>/</code></td> +<td style="text-align: left">applicationStorageDirectory</td> +<td style="text-align: left">-</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">files/</code></td> +<td style="text-align: left">dataDirectory</td> +<td style="text-align: left">-</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"><code class="prettyprint">~/Documents/</code></td> +<td style="text-align: left">documentsDirectory</td> +<td style="text-align: left">documents</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">No</td> +<td style="text-align: center">No</td> +</tr> +<tr> +<td style="text-align: left"><code class="prettyprint">~/Library/Caches/<bundle-id>/</code></td> +<td style="text-align: left">cacheDirectory</td> +<td style="text-align: left">cache</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"><code class="prettyprint">/tmp/</code></td> +<td style="text-align: left">tempDirectory</td> +<td style="text-align: left">-</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes*</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"><code class="prettyprint">/</code></td> +<td style="text-align: left">rootDirectory</td> +<td style="text-align: left">root</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">No**</td> +<td style="text-align: center">No</td> +</tr> +</tbody></table> + +<p><strong>Note</strong>: This is the layout for non sandboxed applications. I you enable sandboxing, the <code class="prettyprint">applicationStorageDirectory</code> will be below <code class="prettyprint">~/Library/Containers/<bundle-id>/Data/Library/Application Support</code>.</p> + +<p>* 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. You should clear this directory as + appropriate for your application.</p> + +<p>** Allows access to the entire file system. This is only available for non sandboxed apps.</p> + +<h3>Windows File System Layout</h3> + +<table><thead> +<tr> +<th style="text-align: left">Device Path</th> +<th style="text-align: left"><code class="prettyprint">cordova.file.*</code></th> +<th style="text-align: center">r/w?</th> +<th style="text-align: center">persistent?</th> +<th style="text-align: center">OS clears</th> +<th style="text-align: center">private</th> +</tr> +</thead><tbody> +<tr> +<td style="text-align: left"><code class="prettyprint">ms-appdata:///</code></td> +<td style="text-align: left">applicationDirectory</td> +<td style="text-align: center">r</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">N/A</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">local/</code></td> +<td style="text-align: left">dataDirectory</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">temp/</code></td> +<td style="text-align: left">cacheDirectory</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes*</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">temp/</code></td> +<td style="text-align: left">tempDirectory</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes*</td> +<td style="text-align: center">Yes</td> +</tr> +<tr> +<td style="text-align: left"> <code class="prettyprint">roaming/</code></td> +<td style="text-align: left">syncedDataDirectory</td> +<td style="text-align: center">r/w</td> +<td style="text-align: center">Yes</td> +<td style="text-align: center">No</td> +<td style="text-align: center">Yes</td> +</tr> +</tbody></table> + +<p>* The OS may periodically clear this directory</p> + +<h2>Android Quirks</h2> + +<h3>Android Persistent storage location</h3> + +<p>There are multiple valid locations to store persistent files on an Android +device. See <a href="http://developer.android.com/guide/topics/data/data-storage.html">this page</a> +for an extensive discussion of the various possibilities.</p> + +<p>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.</p> + +<p>If the SD card was not available, then previous versions would store data under +<code class="prettyprint">/data/data/<packageId></code>, which isolates apps from each other, but may still +cause data to be shared between users.</p> + +<p>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 <code class="prettyprint">config.xml</code> file. To do this, add one of these two lines to +<code class="prettyprint">config.xml</code>:</p> +<div class="highlight"><pre><code class="language-text" data-lang="text"><preference name="AndroidPersistentFileLocation" value="Internal" /> + +<preference name="AndroidPersistentFileLocation" value="Compatibility" /> +</code></pre></div> +<p>Without this line, the File plugin will use <code class="prettyprint">Internal</code> as the default. If +a preference tag is present, and is not one of these values, the application +will not start.</p> + +<p>If your application has previously been shipped to users, using an older (pre- +3.0.0) version of this plugin, and has stored files in the persistent filesystem, +then you should set the preference to <code class="prettyprint">Compatibility</code> if your config.xml does not specify a location for the persistent filesystem. 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.</p> + +<p>If your application is new, or has never previously stored files in the +persistent filesystem, then the <code class="prettyprint">Internal</code> setting is generally recommended.</p> + +<h3>Slow recursive operations for /android_asset</h3> + +<p>Listing asset directories is really slow on Android. You can speed it up though, by +adding <code class="prettyprint">src/android/build-extras.gradle</code> to the root of your android project (also +requires cordova-android@4.0.0 or greater).</p> + +<h2>iOS Quirks</h2> + +<ul> +<li><code class="prettyprint">cordova.file.applicationStorageDirectory</code> is read-only; attempting to store +files within the root directory will fail. Use one of the other <code class="prettyprint">cordova.file.*</code> +properties defined for iOS (only <code class="prettyprint">applicationDirectory</code> and <code class="prettyprint">applicationStorageDirectory</code> are +read-only).</li> +<li><code class="prettyprint">FileReader.readAsText(blob, encoding)</code> + +<ul> +<li>The <code class="prettyprint">encoding</code> parameter is not supported, and UTF-8 encoding is always in effect.</li> +</ul></li> +</ul> + +<h3>iOS Persistent storage location</h3> + +<p>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.</p> + +<p>It is now possible to choose whether to store files in the documents or library +directory, with a preference in your application's <code class="prettyprint">config.xml</code> file. To do this, +add one of these two lines to <code class="prettyprint">config.xml</code>:</p> +<div class="highlight"><pre><code class="language-text" data-lang="text"><preference name="iosPersistentFileLocation" value="Library" /> + +<preference name="iosPersistentFileLocation" value="Compatibility" /> +</code></pre></div> +<p>Without this line, the File plugin will use <code class="prettyprint">Compatibility</code> as the default. If +a preference tag is present, and is not one of these values, the application +will not start.</p> + +<p>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 <code class="prettyprint">Compatibility</code>. Switching the location to +<code class="prettyprint">Library</code> would mean that existing users who upgrade their application would be +unable to access their previously-stored files.</p> + +<p>If your application is new, or has never previously stored files in the +persistent filesystem, then the <code class="prettyprint">Library</code> setting is generally recommended.</p> + +<h2>Firefox OS Quirks</h2> + +<p>The File System API is not natively supported by Firefox OS and is implemented +as a shim on top of indexedDB.</p> + +<ul> +<li>Does not fail when removing non-empty directories</li> +<li>Does not support metadata for directories</li> +<li>Methods <code class="prettyprint">copyTo</code> and <code class="prettyprint">moveTo</code> do not support directories</li> +</ul> + +<p>The following data paths are supported:</p> + +<ul> +<li><code class="prettyprint">applicationDirectory</code> - Uses <code class="prettyprint">xhr</code> to get local files that are packaged with the app.</li> +<li><code class="prettyprint">dataDirectory</code> - For persistent app-specific data files.</li> +<li><code class="prettyprint">cacheDirectory</code> - Cached files that should survive app restarts (Apps should not rely +on the OS to delete files in here).</li> +</ul> + +<h2>Browser Quirks</h2> + +<h3>Common quirks and remarks</h3> + +<ul> +<li>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.</li> +<li>Directory entries have to be created successively. +For example, the call <code class="prettyprint">fs.root.getDirectory('dir1/dir2', {create:true}, successCallback, errorCallback)</code> +will fail if dir1 did not exist.</li> +<li>The plugin requests user permission to use persistent storage at the application first start.</li> +<li>Plugin supports <code class="prettyprint">cdvfile://localhost</code> (local resources) only. I.e. external resources are not supported via <code class="prettyprint">cdvfile</code>.</li> +<li>The plugin does not follow <a href="http://www.w3.org/TR/2011/WD-file-system-api-20110419/#naming-restrictions">"File System API 8.3 Naming restrictions"</a>.</li> +<li>Blob and File' <code class="prettyprint">close</code> function is not supported.</li> +<li><code class="prettyprint">FileSaver</code> and <code class="prettyprint">BlobBuilder</code> are not supported by this plugin and don't have stubs.</li> +<li>The plugin does not support <code class="prettyprint">requestAllFileSystems</code>. This function is also missing in the specifications.</li> +<li>Entries in directory will not be removed if you use <code class="prettyprint">create: true</code> flag for existing directory.</li> +<li>Files created via constructor are not supported. You should use entry.file method instead.</li> +<li>Each browser uses its own form for blob URL references.</li> +<li><code class="prettyprint">readAsDataURL</code> function is supported, but the mediatype in Chrome depends on entry name extension, +mediatype in IE is always empty (which is the same as <code class="prettyprint">text-plain</code> according the specification), +the mediatype in Firefox is always <code class="prettyprint">application/octet-stream</code>. +For example, if the content is <code class="prettyprint">abcdefg</code> then Firefox returns <code class="prettyprint">data:application/octet-stream;base64,YWJjZGVmZw==</code>, +IE returns <code class="prettyprint">data:;base64,YWJjZGVmZw==</code>, Chrome returns <code class="prettyprint">data:<mediatype depending on extension of entry name>;base64,YWJjZGVmZw==</code>.</li> +<li><code class="prettyprint">toInternalURL</code> returns the path in the form <code class="prettyprint">file:///persistent/path/to/entry</code> (Firefox, IE). +Chrome returns the path in the form <code class="prettyprint">cdvfile://localhost/persistent/file</code>.</li> +</ul> + +<h3>Chrome quirks</h3> + +<ul> +<li>Chrome filesystem is not immediately ready after device ready event. As a workaround you can subscribe to <code class="prettyprint">filePluginIsReady</code> event. +Example: +<code class="prettyprint">javascript +window.addEventListener('filePluginIsReady', function(){ console.log('File plugin is ready');}, false); +</code> +You can use <code class="prettyprint">window.isFilePluginReadyRaised</code> function to check whether event was already raised.</li> +<li>window.requestFileSystem TEMPORARY and PERSISTENT filesystem quotas are not limited in Chrome.</li> +<li>To increase persistent storage in Chrome you need to call <code class="prettyprint">window.initPersistentFileSystem</code> method. Persistent storage quota is 5 MB by default.</li> +<li>Chrome requires <code class="prettyprint">--allow-file-access-from-files</code> run argument to support API via <code class="prettyprint">file:///</code> protocol.</li> +<li><code class="prettyprint">File</code> object will be not changed if you use flag <code class="prettyprint">{create:true}</code> when getting an existing <code class="prettyprint">Entry</code>.</li> +<li>events <code class="prettyprint">cancelable</code> property is set to true in Chrome. This is contrary to the <a href="http://dev.w3.org/2009/dap/file-system/file-writer.html">specification</a>.</li> +<li><code class="prettyprint">toURL</code> function in Chrome returns <code class="prettyprint">filesystem:</code>-prefixed path depending on application host. +For example, <code class="prettyprint">filesystem:file:///persistent/somefile.txt</code>, <code class="prettyprint">filesystem:http://localhost:8080/persistent/somefile.txt</code>.</li> +<li><code class="prettyprint">toURL</code> function result does not contain trailing slash in case of directory entry. +Chrome resolves directories with slash-trailed urls correctly though.</li> +<li><code class="prettyprint">resolveLocalFileSystemURL</code> method requires the inbound <code class="prettyprint">url</code> to have <code class="prettyprint">filesystem</code> prefix. For example, <code class="prettyprint">url</code> parameter for <code class="prettyprint">resolveLocalFileSystemURL</code> +should be in the form <code class="prettyprint">filesystem:file:///persistent/somefile.txt</code> as opposed to the form <code class="prettyprint">file:///persistent/somefile.txt</code> in Android.</li> +<li>Deprecated <code class="prettyprint">toNativeURL</code> function is not supported and does not have a stub.</li> +<li><code class="prettyprint">setMetadata</code> function is not stated in the specifications and not supported.</li> +<li>INVALID<em>MODIFICATION</em>ERR (code: 9) is thrown instead of SYNTAX_ERR(code: 8) on requesting of a non-existant filesystem.</li> +<li>INVALID<em>MODIFICATION</em>ERR (code: 9) is thrown instead of PATH<em>EXISTS</em>ERR(code: 12) on trying to exclusively create a file or directory, which already exists.</li> +<li>INVALID<em>MODIFICATION</em>ERR (code: 9) is thrown instead of NO<em>MODIFICATION</em>ALLOWED_ERR(code: 6) on trying to call removeRecursively on the root file system.</li> +<li>INVALID<em>MODIFICATION</em>ERR (code: 9) is thrown instead of NOT<em>FOUND</em>ERR(code: 1) on trying to moveTo directory that does not exist.</li> +</ul> + +<h3>IndexedDB-based impl quirks (Firefox and IE)</h3> + +<ul> +<li><code class="prettyprint">.</code> and <code class="prettyprint">..</code> are not supported.</li> +<li>IE does not support <code class="prettyprint">file:///</code>-mode; only hosted mode is supported (http://localhost:xxxx).</li> +<li>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 <code class="prettyprint">size</code> parameter for <code class="prettyprint">requestFileSystem</code> function does not affect filesystem in Firefox and IE.</li> +<li><code class="prettyprint">readAsBinaryString</code> function is not stated in the Specs and not supported in IE and does not have a stub.</li> +<li><code class="prettyprint">file.type</code> is always null.</li> +<li>You should not create entry using DirectoryEntry instance callback result which was deleted. +Otherwise, you will get a 'hanging entry'.</li> +<li>Before you can read a file, which was just written you need to get a new instance of this file.</li> +<li><code class="prettyprint">setMetadata</code> function, which is not stated in the Specs supports <code class="prettyprint">modificationTime</code> field change only.</li> +<li><code class="prettyprint">copyTo</code> and <code class="prettyprint">moveTo</code> functions do not support directories.</li> +<li>Directories metadata is not supported.</li> +<li>Both Entry.remove and directoryEntry.removeRecursively don't fail when removing +non-empty directories - directories being removed are cleaned along with contents instead.</li> +<li><code class="prettyprint">abort</code> and <code class="prettyprint">truncate</code> functions are not supported.</li> +<li>progress events are not fired. For example, this handler will be not executed: +<code class="prettyprint">javascript +writer.onprogress = function() { /*commands*/ }; +</code></li> +</ul> + +<h2>Upgrading Notes</h2> + +<p>In v1.0.0 of this plugin, the <code class="prettyprint">FileEntry</code> and <code class="prettyprint">DirectoryEntry</code> structures have changed, +to be more in line with the published specification.</p> + +<p>Previous (pre-1.0.0) versions of the plugin stored the device-absolute-file-location +in the <code class="prettyprint">fullPath</code> property of <code class="prettyprint">Entry</code> objects. These paths would typically look like</p> +<div class="highlight"><pre><code class="language-text" data-lang="text">/var/mobile/Applications/<application UUID>/Documents/path/to/file (iOS) +/storage/emulated/0/path/to/file (Android) +</code></pre></div> +<p>These paths were also returned by the <code class="prettyprint">toURL()</code> method of the <code class="prettyprint">Entry</code> objects.</p> + +<p>With v1.0.0, the <code class="prettyprint">fullPath</code> attribute is the path to the file, <em>relative to the root of +the HTML filesystem</em>. So, the above paths would now both be represented by a <code class="prettyprint">FileEntry</code> +object with a <code class="prettyprint">fullPath</code> of</p> +<div class="highlight"><pre><code class="language-text" data-lang="text">/path/to/file +</code></pre></div> +<p>If your application works with device-absolute-paths, and you previously retrieved those +paths through the <code class="prettyprint">fullPath</code> property of <code class="prettyprint">Entry</code> objects, then you should update your code
[... 251 lines stripped ...] --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@cordova.apache.org For additional commands, e-mail: commits-h...@cordova.apache.org