You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by ma...@apache.org on 2013/10/01 05:56:01 UTC
svn commit: r1527865 [7/25] - in /cordova/site/public/docs/en/3.1.0: ./ img/
img/guide/ img/guide/cli/ img/guide/platforms/ img/guide/platforms/android/
img/guide/platforms/bada/ img/guide/platforms/blackberry10/
img/guide/platforms/ios/ img/guide/plat...
Added: cordova/site/public/docs/en/3.1.0/cordova_file_file.md.html
URL: http://svn.apache.org/viewvc/cordova/site/public/docs/en/3.1.0/cordova_file_file.md.html?rev=1527865&view=auto
==============================================================================
--- cordova/site/public/docs/en/3.1.0/cordova_file_file.md.html (added)
+++ cordova/site/public/docs/en/3.1.0/cordova_file_file.md.html Tue Oct 1 03:55:57 2013
@@ -0,0 +1,2513 @@
+<!DOCTYPE html>
+<!--
+ 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.
+--><html lang="en">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<meta name="viewport" content="initial-scale=1.0, maximum-scale=1.0, user-scalable=no, width=device-width">
+<meta name="generator" content="joDoc">
+<title>Apache Cordova API Documentation</title>
+<link rel="stylesheet" type="text/css" href="index.css">
+<link rel="stylesheet" type="text/css" href="mobile.css" media="only screen and (max-device-width: 1024px)">
+<link rel="stylesheet" type="text/css" href="prettify/prettify.css">
+</head>
+<body>
+ <div id="header">
+ <h1><a href="index.html">Apache <strong>Cordova</strong> Documentation</a></h1>
+ <small>
+ <select><optgroup label="Chinese" value="zh"><option value="edge">edge</option></optgroup>
+<optgroup label="English" value="en">
+<option value="edge">edge</option>
+<option selected value="3.1.0">3.1.0</option>
+<option value="3.0.0">3.0.0</option>
+<option value="2.9.0">2.9.0</option>
+<option value="2.8.0">2.8.0</option>
+<option value="2.7.0">2.7.0</option>
+<option value="2.6.0">2.6.0</option>
+<option value="2.5.0">2.5.0</option>
+<option value="2.4.0">2.4.0</option>
+<option value="2.3.0">2.3.0</option>
+<option value="2.2.0">2.2.0</option>
+<option value="2.1.0">2.1.0</option>
+<option value="2.0.0">2.0.0</option>
+<option value="1.9.0">1.9.0</option>
+<option value="1.8.1">1.8.1</option>
+<option value="1.8.0">1.8.0</option>
+<option value="1.7.0">1.7.0</option>
+<option value="1.6.1">1.6.1</option>
+<option value="1.6.0">1.6.0</option>
+<option value="1.5.0">1.5.0</option>
+</optgroup>
+<optgroup label="French" value="fr"><option value="edge">edge</option></optgroup>
+<optgroup label="German" value="de"><option value="edge">edge</option></optgroup>
+<optgroup label="Italian" value="it"><option value="edge">edge</option></optgroup>
+<optgroup label="Japanese" value="ja">
+<option value="edge">edge</option>
+<option value="2.2.0">2.2.0</option>
+<option value="2.1.0">2.1.0</option>
+<option value="2.0.0">2.0.0</option>
+<option value="1.9.0">1.9.0</option>
+<option value="1.8.1">1.8.1</option>
+<option value="1.7.0">1.7.0</option>
+</optgroup>
+<optgroup label="Korean" value="ko">
+<option value="edge">edge</option>
+<option value="2.0.0">2.0.0</option>
+</optgroup>
+<optgroup label="Russian" value="ru"><option value="edge">edge</option></optgroup>
+<optgroup label="Spanish" value="es"><option value="edge">edge</option></optgroup></select></small>
+ </div>
+ <div id="subheader">
+ <h1>File</h1>
+ <small><select><option value="File">File</option>
+<option value="File_objects">Â Â Â Â Â Â - Objects</option>
+<option value="File_accessing_the_feature">Â Â Â Â Â Â - Accessing the Feature</option>
+<option value="File">File</option>
+<option value="File_properties">Â Â Â Â Â Â - Properties</option>
+<option value="File_methods">Â Â Â Â Â Â - Methods</option>
+<option value="File_details">Â Â Â Â Â Â - Details</option>
+<option value="File_supported_platforms">Â Â Â Â Â Â - Supported Platforms</option>
+<option value="File_slice">Â Â Â Â Â Â - slice</option>
+<option value="FileReader">FileReader</option>
+<option value="FileReader_properties">Â Â Â Â Â Â - Properties</option>
+<option value="FileReader_methods">Â Â Â Â Â Â - Methods</option>
+<option value="FileReader_details">Â Â Â Â Â Â - Details</option>
+<option value="FileReader_supported_platforms">Â Â Â Â Â Â - Supported Platforms</option>
+<option value="FileReader_readasdataurl">Â Â Â Â Â Â - readAsDataURL</option>
+<option value="FileReader_quick_example">Â Â Â Â Â Â - Quick Example</option>
+<option value="FileReader_readastext">Â Â Â Â Â Â - readAsText</option>
+<option value="FileReader_quick_example">Â Â Â Â Â Â - Quick Example</option>
+<option value="FileReader_abort">Â Â Â Â Â Â - abort</option>
+<option value="FileReader_full_example">Â Â Â Â Â Â - Full Example</option>
+<option value="FileReader_ios_quirks">Â Â Â Â Â Â - iOS Quirks</option>
+<option value="FileReader_readasbinarystring">Â Â Â Â Â Â - readAsBinaryString</option>
+<option value="FileReader_quick_example">Â Â Â Â Â Â - Quick Example</option>
+<option value="FileReader_readasarraybuffer">Â Â Â Â Â Â - readAsArrayBuffer</option>
+<option value="FileReader_quick_example">Â Â Â Â Â Â - Quick Example</option>
+<option value="FileWriter">FileWriter</option>
+<option value="FileWriter_properties">Â Â Â Â Â Â - Properties</option>
+<option value="FileWriter_details">Â Â Â Â Â Â - Details</option>
+<option value="FileWriter_supported_platforms">Â Â Â Â Â Â - Supported Platforms</option>
+<option value="FileWriter_seek_quick_example">Â Â Â Â Â Â - Seek Quick Example</option>
+<option value="FileWriter_truncate_quick_example">Â Â Â Â Â Â - Truncate Quick Example</option>
+<option value="FileWriter_write_quick_example">Â Â Â Â Â Â - Write Quick Example</option>
+<option value="FileWriter_binary_write_quick_example">Â Â Â Â Â Â - Binary Write Quick Example</option>
+<option value="FileWriter_append_quick_example">Â Â Â Â Â Â - Append Quick Example</option>
+<option value="FileWriter_abort_quick_example">Â Â Â Â Â Â - Abort Quick Example</option>
+<option value="FileWriter_full_example">Â Â Â Â Â Â - Full Example</option>
+<option value="FileSystem">FileSystem</option>
+<option value="FileSystem_properties">Â Â Â Â Â Â - Properties</option>
+<option value="FileSystem_details">Â Â Â Â Â Â - Details</option>
+<option value="FileSystem_supported_platforms">Â Â Â Â Â Â - Supported Platforms</option>
+<option value="FileSystem_file_system_quick_example">Â Â Â Â Â Â -
+File System Quick Example</option>
+<option value="FileSystem_full_example">Â Â Â Â Â Â - Full Example</option>
+<option value="FileEntry">FileEntry</option>
+<option value="FileEntry_properties">Â Â Â Â Â Â - Properties</option>
+<option value="FileEntry_methods">Â Â Â Â Â Â - Methods</option>
+<option value="FileEntry_supported_platforms">Â Â Â Â Â Â - Supported Platforms</option>
+<option value="FileEntry_getmetadata">Â Â Â Â Â Â - getMetadata</option>
+<option value="FileEntry_setmetadata">Â Â Â Â Â Â - setMetadata</option>
+<option value="FileEntry_moveto">Â Â Â Â Â Â - moveTo</option>
+<option value="FileEntry_copyto">Â Â Â Â Â Â - copyTo</option>
+<option value="FileEntry_tourl">Â Â Â Â Â Â - toURL</option>
+<option value="FileEntry_remove">Â Â Â Â Â Â - remove</option>
+<option value="FileEntry_getparent">Â Â Â Â Â Â - getParent</option>
+<option value="FileEntry_createwriter">Â Â Â Â Â Â - createWriter</option>
+<option value="FileEntry_file">Â Â Â Â Â Â - file</option>
+<option value="DirectoryEntry">DirectoryEntry</option>
+<option value="DirectoryEntry_properties">Â Â Â Â Â Â - Properties</option>
+<option value="DirectoryEntry_methods">Â Â Â Â Â Â - Methods</option>
+<option value="DirectoryEntry_supported_platforms">Â Â Â Â Â Â - Supported Platforms</option>
+<option value="DirectoryEntry_getmetadata">Â Â Â Â Â Â - getMetadata</option>
+<option value="DirectoryEntry_setmetadata">Â Â Â Â Â Â - setMetadata</option>
+<option value="DirectoryEntry_moveto">Â Â Â Â Â Â - moveTo</option>
+<option value="DirectoryEntry_copyto">Â Â Â Â Â Â - copyTo</option>
+<option value="DirectoryEntry_tourl">Â Â Â Â Â Â - toURL</option>
+<option value="DirectoryEntry_remove">Â Â Â Â Â Â - remove</option>
+<option value="DirectoryEntry_getparent">Â Â Â Â Â Â - getParent</option>
+<option value="DirectoryEntry_createreader">Â Â Â Â Â Â - createReader</option>
+<option value="DirectoryEntry_getdirectory">Â Â Â Â Â Â - getDirectory</option>
+<option value="DirectoryEntry_getfile">Â Â Â Â Â Â - getFile</option>
+<option value="DirectoryEntry_removerecursively">Â Â Â Â Â Â - removeRecursively</option>
+<option value="DirectoryEntry_blackberry_quirks">Â Â Â Â Â Â - BlackBerry Quirks</option>
+<option value="DirectoryReader">DirectoryReader</option>
+<option value="DirectoryReader_methods">Â Â Â Â Â Â - Methods</option>
+<option value="DirectoryReader_supported_platforms">Â Â Â Â Â Â - Supported Platforms</option>
+<option value="DirectoryReader_readentries">Â Â Â Â Â Â - readEntries</option>
+<option value="FileTransfer">FileTransfer</option>
+<option value="FileTransfer_properties">Â Â Â Â Â Â - Properties</option>
+<option value="FileTransfer_methods">Â Â Â Â Â Â - Methods</option>
+<option value="FileTransfer_details">Â Â Â Â Â Â - Details</option>
+<option value="FileTransfer_supported_platforms">Â Â Â Â Â Â - Supported Platforms</option>
+<option value="FileTransfer_upload">Â Â Â Â Â Â - upload</option>
+<option value="FileTransfer_download">Â Â Â Â Â Â - download</option>
+<option value="FileTransfer_abort">Â Â Â Â Â Â - abort</option>
+<option value="FileTransfer_onprogress">Â Â Â Â Â Â - onprogress</option>
+<option value="FileUploadOptions">FileUploadOptions</option>
+<option value="FileUploadOptions_properties">Â Â Â Â Â Â - Properties</option>
+<option value="FileUploadOptions_description">Â Â Â Â Â Â - Description</option>
+<option value="FileUploadOptions_wp7_quirk">Â Â Â Â Â Â - WP7 Quirk</option>
+<option value="FileUploadResult">FileUploadResult</option>
+<option value="FileUploadResult_properties">Â Â Â Â Â Â - Properties</option>
+<option value="FileUploadResult_description">Â Â Â Â Â Â - Description</option>
+<option value="FileUploadResult_ios_quirks">Â Â Â Â Â Â - iOS Quirks</option>
+<option value="Flags">Flags</option>
+<option value="Flags_properties">Â Â Â Â Â Â - Properties</option>
+<option value="Flags_supported_platforms">Â Â Â Â Â Â - Supported Platforms</option>
+<option value="Flags_quick_example">Â Â Â Â Â Â - Quick Example</option>
+<option value="LocalFileSystem">LocalFileSystem</option>
+<option value="LocalFileSystem_methods">Â Â Â Â Â Â - Methods</option>
+<option value="LocalFileSystem_constants">Â Â Â Â Â Â - Constants</option>
+<option value="LocalFileSystem_details">Â Â Â Â Â Â - Details</option>
+<option value="LocalFileSystem_supported_platforms">Â Â Â Â Â Â - Supported Platforms</option>
+<option value="LocalFileSystem_request_file_system_quick_example">Â Â Â Â Â Â - Request File System Quick Example</option>
+<option value="LocalFileSystem_resolve_local_file_system_uri_quick_example">Â Â Â Â Â Â - Resolve Local File System URI Quick Example</option>
+<option value="LocalFileSystem_full_example">Â Â Â Â Â Â - Full Example</option>
+<option value="requestFileSystem">requestFileSystem</option>
+<option value="requestFileSystem_request_file_system_quick_example">Â Â Â Â Â Â - Request File System Quick Example</option>
+<option value="Metadata">Metadata</option>
+<option value="Metadata_properties">Â Â Â Â Â Â - Properties</option>
+<option value="Metadata_details">Â Â Â Â Â Â - Details</option>
+<option value="Metadata_supported_platforms">Â Â Â Â Â Â - Supported Platforms</option>
+<option value="Metadata_quick_example">Â Â Â Â Â Â - Quick Example</option>
+<option value="FileError">FileError</option>
+<option value="FileError_properties">Â Â Â Â Â Â - Properties</option>
+<option value="FileError_constants">Â Â Â Â Â Â - Constants</option>
+<option value="FileError_description">Â Â Â Â Â Â - Description</option>
+<option value="FileTransferError">FileTransferError</option>
+<option value="FileTransferError_properties">Â Â Â Â Â Â - Properties</option>
+<option value="FileTransferError_constants">Â Â Â Â Â Â - Constants</option>
+<option value="FileTransferError_description">Â Â Â Â Â Â - Description</option></select></small>
+ </div>
+
+ <div id="sidebar">
+ <div class="vertical_divider"></div>
+ <h1>Guides</h1>
+<ul>
+<li><a href="guide_overview_index.md.html#Overview">Overview</a></li>
+<li><a href="guide_cli_index.md.html#The%20Command-line%20Interface">The Command-line Interface</a></li>
+<li><a href="guide_platforms_index.md.html#Platform%20Guides">Platform Guides</a></li>
+<li><a href="config_ref_index.md.html#The%20config.xml%20File">The config.xml File</a></li>
+<li><a href="guide_hybrid_webviews_index.md.html#Embedding%20WebViews">Embedding WebViews</a></li>
+<li><a href="guide_hybrid_plugins_index.md.html#Plugin%20Development%20Guide">Plugin Development Guide</a></li>
+<li><a href="guide_appdev_privacy_index.md.html#Privacy%20Guide">Privacy Guide</a></li>
+<li><a href="guide_appdev_whitelist_index.md.html#Domain%20Whitelist%20Guide">Domain Whitelist Guide</a></li>
+<li><a href="_index.html">Keyword Index</a></li>
+</ul>
+<h1>API Reference</h1>
+<ul>
+<li><a href="cordova_accelerometer_accelerometer.md.html#Accelerometer">Accelerometer</a></li>
+<li><a href="cordova_camera_camera.md.html#Camera">Camera</a></li>
+<li><a href="cordova_media_capture_capture.md.html#Capture">Capture</a></li>
+<li><a href="cordova_compass_compass.md.html#Compass">Compass</a></li>
+<li><a href="cordova_connection_connection.md.html#Connection">Connection</a></li>
+<li><a href="cordova_contacts_contacts.md.html#Contacts">Contacts</a></li>
+<li><a href="cordova_device_device.md.html#Device">Device</a></li>
+<li><a href="cordova_events_events.md.html#Events">Events</a></li>
+<li><a href="cordova_file_file.md.html#File">File</a></li>
+<li><a href="cordova_geolocation_geolocation.md.html#Geolocation">Geolocation</a></li>
+<li><a href="cordova_globalization_globalization.md.html#Globalization">Globalization</a></li>
+<li><a href="cordova_inappbrowser_inappbrowser.md.html#InAppBrowser">InAppBrowser</a></li>
+<li><a href="cordova_media_media.md.html#Media">Media</a></li>
+<li><a href="cordova_notification_notification.md.html#Notification">Notification</a></li>
+<li><a href="cordova_splashscreen_splashscreen.md.html#Splashscreen">Splashscreen</a></li>
+<li><a href="cordova_storage_storage.md.html#Storage">Storage</a></li>
+</ul>
+</div>
+
+ <div id="scrollable">
+ <div id="content">
+ <h1><a name="File">File</a></h1>
+
+<blockquote>
+ <p>An API to read, write and navigate file system hierarchies, based on the <a class="external" href="http://www.w3.org/TR/FileAPI">w3c file api</a>.</p>
+</blockquote>
+
+<h2>
+<a name="File_objects">Objects</a>
+</h2>
+
+<ul>
+<li><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></li>
+<li><a href="cordova_file_file.md.html#DirectoryReader">DirectoryReader</a></li>
+<li><a href="cordova_file_file.md.html#File">File</a></li>
+<li><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></li>
+<li><a href="cordova_file_file.md.html#FileError">FileError</a></li>
+<li><a href="cordova_file_file.md.html#FileReader">FileReader</a></li>
+<li><a href="cordova_file_file.md.html#FileSystem">FileSystem</a></li>
+<li><a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a></li>
+<li><a href="cordova_file_file.md.html#FileTransferError">FileTransferError</a></li>
+<li><a href="cordova_file_file.md.html#FileUploadOptions">FileUploadOptions</a></li>
+<li><a href="cordova_file_file.md.html#FileUploadResult">FileUploadResult</a></li>
+<li><a href="cordova_file_file.md.html#FileWriter">FileWriter</a></li>
+<li><a href="cordova_file_file.md.html#Flags">Flags</a></li>
+<li><a href="cordova_file_file.md.html#LocalFileSystem">LocalFileSystem</a></li>
+<li><a href="cordova_file_file.md.html#Metadata">Metadata</a></li>
+</ul>
+<h2>
+<a name="File_accessing_the_feature">Accessing the Feature</a>
+</h2>
+
+<p>As of version 3.0, Cordova implements device-level APIs as <em>plugins</em>.
+Use the CLI's <code>plugin</code> command, described in <a href="#The%20Command-line%0AInterface">The Command-line
+Interface</a>, to add or remove this feature for a project:</p>
+
+<pre class="prettyprint"><code> $ cordova plugin add org.apache.cordova.file
+ $ cordova plugin ls
+ [ 'org.apache.cordova.file' ]
+ $ cordova plugin rm org.apache.cordova.file
+</code></pre>
+
+<p>To use the file-transfer plugin you must add that separately.</p>
+
+<pre class="prettyprint"><code> $ cordova plugin add org.apache.cordova.file-transfer
+ $ cordova plugin ls
+ [ 'org.apache.cordova.file-transfer' ]
+ $ cordova plugin rm org.apache.cordova.file-transfer
+</code></pre>
+
+<p>These commands apply to all targeted platforms, but modify the
+platform-specific configuration settings described below:</p>
+
+<ul>
+<li>
+<p>Android</p>
+
+<pre class="prettyprint"><code>(in app/res/xml/config.xml)
+<feature name="<a href="cordova_file_file.md.html#File">File</a>">
+ <param name="android-package" value="org.apache.cordova.FileUtils" />
+</feature>
+<feature name="<a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>">
+ <param name="android-package" value="org.apache.cordova.<a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>" />
+</feature>
+
+
+(in app/AndroidManifest.xml)
+<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+</code></pre>
+</li>
+<li>
+<p>BlackBerry WebWorks</p>
+
+<pre class="prettyprint"><code>(in www/plugins.xml)
+<feature name="<a href="cordova_file_file.md.html#File">File</a>">
+ <param name="blackberry-package" value="org.apache.cordova.file.FileManager" />
+</feature>
+<feature name="<a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>">
+ <param name="blackberry-package" value="org.apache.cordova.http.<a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>" />
+</feature>
+
+
+(in www/config.xml)
+<feature id="blackberry.io.file" required="true" version="1.0.0.0" />
+<feature id="blackberry.utils" required="true" version="1.0.0.0" />
+<feature id="blackberry.io.dir" required="true" version="1.0.0.0" />
+<rim:permissions>
+ <rim:permit>access_shared</rim:permit>
+</rim:permissions>
+</code></pre>
+</li>
+<li>
+<p>iOS (in <code>config.xml</code>)</p>
+
+<pre class="prettyprint"><code><feature name="<a href="cordova_file_file.md.html#File">File</a>">
+ <param name="ios-package" value="CDVFile" />
+</feature>
+<feature name="<a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>">
+ <param name="ios-package" value="CDVFileTransfer" />
+</feature>
+</code></pre>
+</li>
+</ul>
+<p>Some platforms may support this feature without requiring any special
+configuration. See <em>Platform Support</em> in the <a href="guide_overview_index.md.html#Overview">Overview</a> section.</p>
+
+<hr>
+<h1><a name="File">File</a></h1>
+
+<p>This object contains attributes of a single file.</p>
+
+<h2>
+<a name="File_properties">Properties</a>
+</h2>
+
+<ul>
+<li><p><strong>name</strong>: The name of the file. <em>(DOMString)</em></p></li>
+<li><p><strong>fullPath</strong>: The full path of the file including the file name. <em>(DOMString)</em></p></li>
+<li><p><strong>type</strong>: The mime type of the file. <em>(DOMString)</em></p></li>
+<li><p><strong>lastModifiedDate</strong>: The last time the file was modified. <em>(Date)</em></p></li>
+<li><p><strong>size</strong>: The size of the file in bytes. <em>(long)</em></p></li>
+</ul>
+<h2>
+<a name="File_methods">Methods</a>
+</h2>
+
+<ul>
+<li>
+<strong>slice</strong>: Select only a portion of the file to be read.</li>
+</ul>
+<h2>
+<a name="File_details">Details</a>
+</h2>
+
+<p>The <code><a href="cordova_file_file.md.html#File">File</a></code> object contains attributes of a single file. You can get
+an instance of a <code><a href="cordova_file_file.md.html#File">File</a></code> object by calling a <code><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></code> object's
+<code>file()</code> method.</p>
+
+<h2>
+<a name="File_supported_platforms">Supported Platforms</a>
+</h2>
+
+<ul>
+<li>Android</li>
+<li>BlackBerry WebWorks (OS 5.0 and higher)</li>
+<li>iOS</li>
+<li>Windows Phone 7 and 8</li>
+<li>Windows 8</li>
+</ul>
+<h2>
+<a name="File_slice">slice</a>
+</h2>
+
+<p>Return a new <code><a href="cordova_file_file.md.html#File">File</a></code> object, for which <code><a href="cordova_file_file.md.html#FileReader">FileReader</a></code> returns only the
+specified portion of the file. Negative values for <code>start</code> or <code>end</code>
+are measured from the end of the file. Indexes are positioned
+relative to the current slice. (See the full example below.)</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>start</strong>: The index of the first byte to read, inclusive.</p></li>
+<li><p><strong>end</strong>: The index of the byte after the last one to read.</p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>var slicedFile = file.slice(10, 30);
+</code></pre>
+
+<p><strong>Full Example</strong></p>
+
+<pre class="prettyprint"><code>var slice1 = file.slice(100, 400);
+var slice2 = slice1.slice(20, 35);
+
+var slice3 = file.slice(120, 135);
+// slice2 and slice3 are equivalent.
+</code></pre>
+
+<p><strong>Supported Platforms</strong></p>
+
+<ul>
+<li>Android</li>
+<li>iOS</li>
+</ul>
+<hr>
+<h1><a name="FileReader">FileReader</a></h1>
+
+<p>The <code><a href="cordova_file_file.md.html#FileReader">FileReader</a></code> allows basic access to a file.</p>
+
+<h2>
+<a name="FileReader_properties">Properties</a>
+</h2>
+
+<ul>
+<li><p><strong>readyState</strong>: One of the reader's three possible states, either <code>EMPTY</code>, <code>LOADING</code> or <code>DONE</code>.</p></li>
+<li><p><strong>result</strong>: The contents of the file that have been read. <em>(DOMString)</em></p></li>
+<li><p><strong>error</strong>: An object containing errors. <em>(<a href="cordova_file_file.md.html#FileError">FileError</a>)</em></p></li>
+<li><p><strong>onloadstart</strong>: Called when the read starts. <em>(Function)</em></p></li>
+<li><p><strong>onload</strong>: Called when the read has successfully completed. <em>(Function)</em></p></li>
+<li><p><strong>onabort</strong>: Called when the read has been aborted. For instance, by invoking the <code>abort()</code> method. <em>(Function)</em></p></li>
+<li><p><strong>onerror</strong>: Called when the read has failed. <em>(Function)</em></p></li>
+<li><p><strong>onloadend</strong>: Called when the request has completed (either in success or failure). <em>(Function)</em></p></li>
+</ul>
+<p><strong>NOTE:</strong> The following porperty is not supported:</p>
+
+<ul>
+<li>
+<strong>onprogress</strong>: Called while reading the file, reporting progress in terms of <code>progress.loaded</code>/<code>progress.total</code>. <em>(Function)</em>
+</li>
+</ul>
+<h2>
+<a name="FileReader_methods">Methods</a>
+</h2>
+
+<ul>
+<li><p><strong>abort</strong>: Aborts reading file.</p></li>
+<li><p><strong>readAsDataURL</strong>: Read file and return data as a base64-encoded data URL.</p></li>
+<li><p><strong>readAsText</strong>: Reads text file.</p></li>
+<li><p><strong>readAsBinaryString</strong>: Reads file as binary and returns a binary string.</p></li>
+<li><p><strong>readAsArrayBuffer</strong>: Reads file as an <code>ArrayBuffer</code>.</p></li>
+</ul>
+<h2>
+<a name="FileReader_details">Details</a>
+</h2>
+
+<p>The <code><a href="cordova_file_file.md.html#FileReader">FileReader</a></code> object offers a way to read files from the device's
+file system. Files can be read as text or as a base64 data-encoded
+string. Event listeners receive the <code>loadstart</code>, <code>progress</code>, <code>load</code>,
+<code>loadend</code>, <code>error</code>, and <code>abort</code> events.</p>
+
+<h2>
+<a name="FileReader_supported_platforms">Supported Platforms</a>
+</h2>
+
+<ul>
+<li>Android</li>
+<li>BlackBerry WebWorks (OS 5.0 and higher)</li>
+<li>iOS</li>
+<li>Windows Phone 7 and 8</li>
+<li>Windows 8</li>
+</ul>
+<h2>
+<a name="FileReader_readasdataurl">readAsDataURL</a>
+</h2>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>file</strong>: the file object to read.</li>
+</ul>
+<h2>
+<a name="FileReader_quick_example">Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function win(file) {
+ var reader = new <a href="cordova_file_file.md.html#FileReader">FileReader</a>();
+ reader.onloadend = function (evt) {
+ console.log("read success");
+ console.log(evt.target.result);
+ };
+ reader.readAsDataURL(file);
+};
+
+var fail = function (error) {
+ console.log(error.code);
+};
+
+entry.file(win, fail);
+</code></pre>
+
+<h2>
+<a name="FileReader_readastext">readAsText</a>
+</h2>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>file</strong>: the file object to read.</p></li>
+<li><p><strong>encoding</strong>: the encoding to use to encode the file's content. Default is UTF8.</p></li>
+</ul>
+<h2>
+<a name="FileReader_quick_example">Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function win(file) {
+ var reader = new <a href="cordova_file_file.md.html#FileReader">FileReader</a>();
+ reader.onloadend = function (evt) {
+ console.log("read success");
+ console.log(evt.target.result);
+ };
+ reader.readAsText(file);
+};
+
+var fail = function (error) {
+ console.log(error.code);
+};
+
+entry.file(win, fail);
+</code></pre>
+
+<h2>
+<a name="FileReader_abort">abort</a>
+</h2>
+
+<pre class="prettyprint"><code>function win(file) {
+ var reader = new <a href="cordova_file_file.md.html#FileReader">FileReader</a>();
+ reader.onloadend = function(evt) {
+ console.log("read success");
+ console.log(evt.target.result);
+ };
+ reader.readAsText(file);
+ reader.abort();
+};
+
+function fail(error) {
+ console.log(error.code);
+}
+
+entry.file(win, fail);
+</code></pre>
+
+<h2>
+<a name="FileReader_full_example">Full Example</a>
+</h2>
+
+<pre class="prettyprint"><code><!DOCTYPE html>
+<html>
+ <head>
+ <title><a href="cordova_file_file.md.html#FileReader">FileReader</a> Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for device API libraries to load
+ //
+ document.<a href="cordova_inappbrowser_inappbrowser.md.html#addEventListener">addEventListener</a>("<a href="cordova_events_events.md.html#deviceready">deviceready</a>", onDeviceReady, false);
+
+ // device APIs are available
+ //
+ function onDeviceReady() {
+ window.<a href="cordova_file_file.md.html#requestFileSystem">requestFileSystem</a>(<a href="cordova_file_file.md.html#LocalFileSystem">LocalFileSystem</a>.PERSISTENT, 0, gotFS, fail);
+ }
+
+ function gotFS(fileSystem) {
+ fileSystem.root.getFile("readme.txt", null, gotFileEntry, fail);
+ }
+
+ function gotFileEntry(fileEntry) {
+ fileEntry.file(gotFile, fail);
+ }
+
+ function gotFile(file){
+ readDataUrl(file);
+ readAsText(file);
+ }
+
+ function readDataUrl(file) {
+ var reader = new <a href="cordova_file_file.md.html#FileReader">FileReader</a>();
+ reader.onloadend = function(evt) {
+ console.log("Read as data URL");
+ console.log(evt.target.result);
+ };
+ reader.readAsDataURL(file);
+ }
+
+ function readAsText(file) {
+ var reader = new <a href="cordova_file_file.md.html#FileReader">FileReader</a>();
+ reader.onloadend = function(evt) {
+ console.log("Read as text");
+ console.log(evt.target.result);
+ };
+ reader.readAsText(file);
+ }
+
+ function fail(error) {
+ console.log(error.code);
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Read <a href="cordova_file_file.md.html#File">File</a></p>
+ </body>
+</html>
+</code></pre>
+
+<h2>
+<a name="FileReader_ios_quirks">iOS Quirks</a>
+</h2>
+
+<ul>
+<li>The <strong>encoding</strong> parameter is not supported, and UTF8 encoding is always in effect.</li>
+</ul>
+<h2>
+<a name="FileReader_readasbinarystring">readAsBinaryString</a>
+</h2>
+
+<p>Currently supported on iOS and Android only.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>file</strong>: the file object to read.</li>
+</ul>
+<h2>
+<a name="FileReader_quick_example">Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function win(file) {
+ var reader = new <a href="cordova_file_file.md.html#FileReader">FileReader</a>();
+ reader.onloadend = function (evt) {
+ console.log("read success");
+ console.log(evt.target.result);
+ };
+ reader.readAsBinaryString(file);
+};
+
+var fail = function (error) {
+ console.log(error.code);
+};
+
+entry.file(win, fail);
+</code></pre>
+
+<h2>
+<a name="FileReader_readasarraybuffer">readAsArrayBuffer</a>
+</h2>
+
+<p>Currently supported on iOS and Android only.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>file</strong>: the file object to read.</li>
+</ul>
+<h2>
+<a name="FileReader_quick_example">Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function win(file) {
+ var reader = new <a href="cordova_file_file.md.html#FileReader">FileReader</a>();
+ reader.onloadend = function (evt) {
+ console.log("read success");
+ console.log(new Uint8Array(evt.target.result));
+ };
+ reader.readAsArrayBuffer(file);
+};
+
+var fail = function (error) {
+ console.log(error.code);
+};
+
+entry.file(win, fail);
+</code></pre>
+
+<hr>
+<h1><a name="FileWriter">FileWriter</a></h1>
+
+<p>As object that allows you to create and write data to a file.</p>
+
+<h2>
+<a name="FileWriter_properties">Properties</a>
+</h2>
+
+<ul>
+<li><p><strong>readyState</strong>: One of the three possible states, either <code>INIT</code>, <code>WRITING</code>, or <code>DONE</code>.</p></li>
+<li><p><strong>fileName</strong>: The name of the file to be written. <em>(DOMString)</em></p></li>
+<li><p><strong>length</strong>: The length of the file to be written. <em>(long)</em></p></li>
+<li><p><strong>position</strong>: The current position of the file pointer. <em>(long)</em></p></li>
+<li><p><strong>error</strong>: An object containing errors. <em>(<a href="cordova_file_file.md.html#FileError">FileError</a>)</em></p></li>
+<li><p><strong>onwritestart</strong>: Called when the write starts. <em>(Function)</em></p></li>
+<li><p><strong>onwrite</strong>: Called when the request has completed successfully. <em>(Function)</em></p></li>
+<li><p><strong>onabort</strong>: Called when the write has been aborted. For instance, by invoking the abort() method. <em>(Function)</em></p></li>
+<li><p><strong>onerror</strong>: Called when the write has failed. <em>(Function)</em></p></li>
+<li><p><strong>onwriteend</strong>: Called when the request has completed (either in success or failure). <em>(Function)</em></p></li>
+</ul>
+<p>The following property is <em>not</em> supported:</p>
+
+<ul>
+<li>
+<p><strong>onprogress</strong>: Called while writing the file, reporting progress in terms of <code>progress.loaded</code>/<code>progress.total</code>. <em>(Function)</em></p>
+
+<h2>Methods</h2>
+</li>
+<li><p><strong>abort</strong>: Aborts writing the file.</p></li>
+<li><p><strong>seek</strong>: Moves the file pointer to the specified byte.</p></li>
+<li><p><strong>truncate</strong>: Shortens the file to the specified length.</p></li>
+<li><p><strong>write</strong>: Writes data to the file.</p></li>
+</ul>
+<h2>
+<a name="FileWriter_details">Details</a>
+</h2>
+
+<p>The <code><a href="cordova_file_file.md.html#FileWriter">FileWriter</a></code> object offers a way to write UTF-8 encoded files to
+the device file system. Applications respond to <code>writestart</code>,
+<code>progress</code>, <code>write</code>, <code>writeend</code>, <code>error</code>, and <code>abort</code> events.</p>
+
+<p>Each <code><a href="cordova_file_file.md.html#FileWriter">FileWriter</a></code> corresponds to a single file, to which data can be
+written many times. The <code><a href="cordova_file_file.md.html#FileWriter">FileWriter</a></code> maintains the file's <code>position</code>
+and <code>length</code> attributes, which allow the app to <code>seek</code> and <code>write</code>
+anywhere in the file. By default, the <code><a href="cordova_file_file.md.html#FileWriter">FileWriter</a></code> writes to the
+beginning of the file, overwriting existing data. Set the optional
+<code>append</code> boolean to <code>true</code> in the <code><a href="cordova_file_file.md.html#FileWriter">FileWriter</a></code>'s constructor to
+write to the end of the file.</p>
+
+<p>Text data is supported by all platforms listed below. Text is encoded as UTF-8 before being written to the filesystem. Some platforms also support binary data, which can be passed in as either an ArrayBuffer or a Blob.</p>
+
+<h2>
+<a name="FileWriter_supported_platforms">Supported Platforms</a>
+</h2>
+
+<p>Text and Binary Support:</p>
+
+<ul>
+<li>Android</li>
+<li>iOS</li>
+</ul>
+<p>Text-only Support:</p>
+
+<ul>
+<li>BlackBerry WebWorks (OS 5.0 and higher)</li>
+<li>Windows Phone 7 and 8</li>
+<li>Windows 8</li>
+</ul>
+<h2>
+<a name="FileWriter_seek_quick_example">Seek Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function win(writer) {
+ // fast forwards file pointer to end of file
+ writer.seek(writer.length);
+};
+
+var fail = function(evt) {
+ console.log(error.code);
+};
+
+entry.createWriter(win, fail);
+</code></pre>
+
+<h2>
+<a name="FileWriter_truncate_quick_example">Truncate Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function win(writer) {
+ writer.truncate(10);
+};
+
+var fail = function(evt) {
+ console.log(error.code);
+};
+
+entry.createWriter(win, fail);
+</code></pre>
+
+<h2>
+<a name="FileWriter_write_quick_example">Write Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function win(writer) {
+ writer.onwrite = function(evt) {
+ console.log("write success");
+ };
+ writer.write("some sample text");
+};
+
+var fail = function(evt) {
+ console.log(error.code);
+};
+
+entry.createWriter(win, fail);
+</code></pre>
+
+<h2>
+<a name="FileWriter_binary_write_quick_example">Binary Write Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function win(writer) {
+ var data = new ArrayBuffer(5),
+ dataView = new Int8Array(data);
+ for (i=0; i < 5; i++) {
+ dataView[i] = i;
+ }
+ writer.onwrite = function(evt) {
+ console.log("write success");
+ };
+ writer.write(data);
+};
+
+var fail = function(evt) {
+ console.log(error.code);
+};
+
+entry.createWriter(win, fail);
+</code></pre>
+
+<h2>
+<a name="FileWriter_append_quick_example">Append Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function win(writer) {
+ writer.onwrite = function(evt) {
+ console.log("write success");
+};
+writer.seek(writer.length);
+ writer.write("appended text");
+};
+
+var fail = function(evt) {
+ console.log(error.code);
+};
+
+entry.createWriter(win, fail);
+</code></pre>
+
+<h2>
+<a name="FileWriter_abort_quick_example">Abort Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function win(writer) {
+ writer.onwrite = function(evt) {
+ console.log("write success");
+ };
+ writer.write("some sample text");
+ writer.abort();
+};
+
+var fail = function(evt) {
+ console.log(error.code);
+};
+
+entry.createWriter(win, fail);
+</code></pre>
+
+<h2>
+<a name="FileWriter_full_example">Full Example</a>
+</h2>
+
+<pre class="prettyprint"><code><!DOCTYPE html>
+<html>
+ <head>
+ <title><a href="cordova_file_file.md.html#FileWriter">FileWriter</a> Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for device API libraries to load
+ //
+ document.<a href="cordova_inappbrowser_inappbrowser.md.html#addEventListener">addEventListener</a>("<a href="cordova_events_events.md.html#deviceready">deviceready</a>", onDeviceReady, false);
+
+ // device APIs are available
+ //
+ function onDeviceReady() {
+ window.<a href="cordova_file_file.md.html#requestFileSystem">requestFileSystem</a>(<a href="cordova_file_file.md.html#LocalFileSystem">LocalFileSystem</a>.PERSISTENT, 0, gotFS, fail);
+ }
+
+ function gotFS(fileSystem) {
+ fileSystem.root.getFile("readme.txt", {create: true, exclusive: false}, gotFileEntry, fail);
+ }
+
+ function gotFileEntry(fileEntry) {
+ fileEntry.createWriter(gotFileWriter, fail);
+ }
+
+ function gotFileWriter(writer) {
+ writer.onwriteend = function(evt) {
+ console.log("contents of file now 'some sample text'");
+ writer.truncate(11);
+ writer.onwriteend = function(evt) {
+ console.log("contents of file now 'some sample'");
+ writer.seek(4);
+ writer.write(" different text");
+ writer.onwriteend = function(evt){
+ console.log("contents of file now 'some different text'");
+ }
+ };
+ };
+ writer.write("some sample text");
+ }
+
+ function fail(error) {
+ console.log(error.code);
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Write <a href="cordova_file_file.md.html#File">File</a></p>
+ </body>
+</html>
+</code></pre>
+
+<hr>
+<h1><a name="FileSystem">FileSystem</a></h1>
+
+<p>This object represents a file system.</p>
+
+<h2>
+<a name="FileSystem_properties">Properties</a>
+</h2>
+
+<ul>
+<li><p><strong>name</strong>: The name of the file system. <em>(DOMString)</em></p></li>
+<li><p><strong>root</strong>: The root directory of the file system. <em>(<a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>)</em></p></li>
+</ul>
+<h2>
+<a name="FileSystem_details">Details</a>
+</h2>
+
+<p>The <code><a href="cordova_file_file.md.html#FileSystem">FileSystem</a></code> object represents information about the file system.
+The name of the file system is unique across the list of exposed
+file systems. The root property contains a <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code> object
+that represents the file system's root directory.</p>
+
+<h2>
+<a name="FileSystem_supported_platforms">Supported Platforms</a>
+</h2>
+
+<ul>
+<li>Android</li>
+<li>BlackBerry WebWorks (OS 5.0 and higher)</li>
+<li>iOS</li>
+<li>Windows Phone 7 and 8</li>
+<li>Windows 8</li>
+</ul>
+<h2>
+<a name="FileSystem_file_system_quick_example">
+File System Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function onSuccess(fileSystem) {
+ console.log(fileSystem.name);
+ console.log(fileSystem.root.name);
+}
+
+// request the persistent file system
+window.<a href="cordova_file_file.md.html#requestFileSystem">requestFileSystem</a>(<a href="cordova_file_file.md.html#LocalFileSystem">LocalFileSystem</a>.PERSISTENT, 0, onSuccess, null);
+</code></pre>
+
+<h2>
+<a name="FileSystem_full_example">Full Example</a>
+</h2>
+
+<pre class="prettyprint"><code><!DOCTYPE html>
+<html>
+ <head>
+ <title><a href="cordova_file_file.md.html#File">File</a> System Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for device API libraries to load
+ //
+ document.<a href="cordova_inappbrowser_inappbrowser.md.html#addEventListener">addEventListener</a>("<a href="cordova_events_events.md.html#deviceready">deviceready</a>", onDeviceReady, false);
+
+ // device APIs are available
+ //
+ function onDeviceReady() {
+ window.<a href="cordova_file_file.md.html#requestFileSystem">requestFileSystem</a>(<a href="cordova_file_file.md.html#LocalFileSystem">LocalFileSystem</a>.PERSISTENT, 0, onFileSystemSuccess, fail);
+ }
+
+ function onFileSystemSuccess(fileSystem) {
+ console.log(fileSystem.name);
+ console.log(fileSystem.root.name);
+ }
+
+ function fail(evt) {
+ console.log(evt.target.error.code);
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p><a href="cordova_file_file.md.html#File">File</a> System</p>
+ </body>
+</html>
+</code></pre>
+
+<hr>
+<h1><a name="FileEntry">FileEntry</a></h1>
+
+<p>Represents a file on a file system, as defined in the
+<a class="external" href="http://www.w3.org/TR/file-system-api/">W3C Directories and Systems</a>
+specification.</p>
+
+<h2>
+<a name="FileEntry_properties">Properties</a>
+</h2>
+
+<ul>
+<li><p><strong>isFile</strong>: Always <code>true</code>. <em>(boolean)</em></p></li>
+<li><p><strong>isDirectory</strong>: Always <code>false</code>. <em>(boolean)</em></p></li>
+<li><p><strong>name</strong>: The name of the <code><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></code>, excluding the path leading to it. <em>(DOMString)</em></p></li>
+<li><p><strong>fullPath</strong>: The full absolute path from the root to the <code><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></code>. <em>(DOMString)</em></p></li>
+</ul>
+<p><strong>NOTE:</strong> The following attribute is defined by the W3C specification,
+but is <em>not</em> supported:</p>
+
+<ul>
+<li>
+<strong>filesystem</strong>: The file system on which the <code><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></code> resides. <em>(<a href="cordova_file_file.md.html#FileSystem">FileSystem</a>)</em>
+</li>
+</ul>
+<h2>
+<a name="FileEntry_methods">Methods</a>
+</h2>
+
+<ul>
+<li><p><strong>getMetadata</strong>: Look up metadata about a file.</p></li>
+<li><p><strong>setMetadata</strong>: Set metadata on a file.</p></li>
+<li><p><strong>moveTo</strong>: Move a file to a different location on the file system.</p></li>
+<li><p><strong>copyTo</strong>: Copy a file to a different location on the file system.</p></li>
+<li><p><strong>toURL</strong>: Return a URL that can be used to locate a file.</p></li>
+<li><p><strong>remove</strong>: Delete a file.</p></li>
+<li><p><strong>getParent</strong>: Look up the parent directory.</p></li>
+<li><p><strong>createWriter</strong>: Creates a <code><a href="cordova_file_file.md.html#FileWriter">FileWriter</a></code> object that can be used to write to a file.</p></li>
+<li><p><strong>file</strong>: Creates a <code><a href="cordova_file_file.md.html#File">File</a></code> object containing file properties.</p></li>
+</ul>
+<h2>
+<a name="FileEntry_supported_platforms">Supported Platforms</a>
+</h2>
+
+<ul>
+<li>Android</li>
+<li>BlackBerry WebWorks (OS 5.0 and higher)</li>
+<li>iOS</li>
+<li>Windows Phone 7 and 8</li>
+<li>Windows 8</li>
+</ul>
+<h2>
+<a name="FileEntry_getmetadata">getMetadata</a>
+</h2>
+
+<p>Look up metadata about a file.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>successCallback</strong>: A callback that is passed a <code><a href="cordova_file_file.md.html#Metadata">Metadata</a></code> object. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when retrieving the <code><a href="cordova_file_file.md.html#Metadata">Metadata</a></code>. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(metadata) {
+ console.log("Last Modified: " + metadata.modificationTime);
+}
+
+function fail(error) {
+ alert(error.code);
+}
+
+// Request the metadata object for this entry
+entry.getMetadata(success, fail);
+</code></pre>
+
+<h2>
+<a name="FileEntry_setmetadata">setMetadata</a>
+</h2>
+
+<p>Set metadata on a file.</p>
+
+<p><strong>Currently works only on iOS.</strong></p>
+
+<ul>
+<li>this will set the extended attributes of a file.</li>
+</ul>
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>successCallback</strong>: A callback that executes when the metadata is set. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes when the metadata is not successfully set. <em>(Function)</em></p></li>
+<li><p><strong>metadataObject</strong>: An object that contains the metadata's keys and values. <em>(Object)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success() {
+ console.log("The metadata was successfully set.");
+}
+
+function fail() {
+ alert("There was an error in setting the metadata");
+}
+
+// Set the metadata
+entry.setMetadata(success, fail, { "com.apple.MobileBackup": 1});
+</code></pre>
+
+<p><strong>iOS Quirk</strong></p>
+
+<ul>
+<li>Only the <code>com.apple.MobileBackup</code> extended attribute is supported. Set the value to <code>1</code> to prevent the file from being backed up to iCloud. Set the value to <code>0</code> to re-enable the file to be backed up to iCloud.</li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function setFileMetadata(localFileSystem, filePath, metadataKey, metadataValue)
+{
+ var onSetMetadataWin = function() {
+ console.log("success setting metadata")
+ }
+ var onSetMetadataFail = function() {
+ console.log("error setting metadata")
+ }
+
+ var onGetFileWin = function(parent) {
+ var data = {};
+ data[metadataKey] = metadataValue;
+ parent.setMetadata(onSetMetadataWin, onSetMetadataFail, data);
+ }
+ var onGetFileFail = function() {
+ console.log("error getting file")
+ }
+
+ var onFSWin = function(fileSystem) {
+ fileSystem.root.getFile(filePath, {create: true, exclusive: false}, onGetFileWin, onGetFileFail);
+ }
+
+ var onFSFail = function(evt) {
+ console.log(evt.target.error.code);
+ }
+
+ window.<a href="cordova_file_file.md.html#requestFileSystem">requestFileSystem</a>(localFileSystem, 0, onFSWin, onFSFail);
+}
+
+ setFileMetadata(<a href="cordova_file_file.md.html#LocalFileSystem">LocalFileSystem</a>.PERSISTENT, "Backups/sqlite.db", "com.apple.MobileBackup", 1);
+</code></pre>
+
+<h2>
+<a name="FileEntry_moveto">moveTo</a>
+</h2>
+
+<p>Move a file to a different location on the file system. An error
+results if the app attempts to:</p>
+
+<ul>
+<li><p>move a file into its parent if a name different from its current one isn't provided;</p></li>
+<li><p>move a file to a path occupied by a directory;</p></li>
+</ul>
+<p>In addition, moving a file on top of an existing file attempts to
+delete and replace that file.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>parent</strong>: The parent directory to which to move the file. <em>(<a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>)</em></p></li>
+<li><p><strong>newName</strong>: The new name of the file. Defaults to the current name if unspecified. <em>(DOMString)</em></p></li>
+<li><p><strong>successCallback</strong>: A callback that is passed the new file's <code><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></code> object. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when attempting to move the file. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(entry) {
+ console.log("New Path: " + entry.fullPath);
+}
+
+function fail(error) {
+ alert(error.code);
+}
+
+function moveFile(entry) {
+ var parent = document.getElementById('parent').value,
+ parentName = parent.substring(parent.lastIndexOf('/')+1),
+ parentEntry = new <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>(parentName, parent);
+
+ // move the file to a new directory and rename it
+ entry.moveTo(parentEntry, "newFile.txt", success, fail);
+}
+</code></pre>
+
+<h2>
+<a name="FileEntry_copyto">copyTo</a>
+</h2>
+
+<p>Copy a file to a new location on the file system. An error results if
+the app attempts to:</p>
+
+<ul>
+<li>copy a file into its parent if a name different from its current one is not provided.</li>
+</ul>
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>parent</strong>: The parent directory to which to copy the file. <em>(<a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>)</em></p></li>
+<li><p><strong>newName</strong>: The new name of the file. Defaults to the current name if unspecified. <em>(DOMString)</em></p></li>
+<li><p><strong>successCallback</strong>: A callback that is passed the new file's <code><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></code> object. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when attempting to copy the file. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function win(entry) {
+ console.log("New Path: " + entry.fullPath);
+}
+
+function fail(error) {
+ alert(error.code);
+}
+
+function copyFile(entry) {
+ var parent = document.getElementById('parent').value,
+ parentName = parent.substring(parent.lastIndexOf('/')+1),
+ parentEntry = new <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>(parentName, parent);
+
+ // copy the file to a new directory and rename it
+ entry.copyTo(parentEntry, "file.copy", success, fail);
+}
+</code></pre>
+
+<h2>
+<a name="FileEntry_tourl">toURL</a>
+</h2>
+
+<p>Returns a URL that can be used to locate the file.</p>
+
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>// Request the URL for this entry
+var fileURL = entry.toURL();
+console.log(fileURL);
+</code></pre>
+
+<h2>
+<a name="FileEntry_remove">remove</a>
+</h2>
+
+<p>Deletes a file.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>successCallback</strong>: A callback that executes after the file has been deleted. Invoked with no parameters. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when attempting to delete the file. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(entry) {
+ console.log("Removal succeeded");
+}
+
+function fail(error) {
+ alert('Error removing file: ' + error.code);
+}
+
+// remove the file
+entry.remove(success, fail);
+</code></pre>
+
+<h2>
+<a name="FileEntry_getparent">getParent</a>
+</h2>
+
+<p>Look up the parent <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code> containing the file.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>successCallback</strong>: A callback that is passed the file's parent <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code>. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when attempting to retrieve the parent <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code>. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(parent) {
+ console.log("Parent Name: " + parent.name);
+}
+
+function fail(error) {
+ alert(error.code);
+}
+
+// Get the parent <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>
+entry.getParent(success, fail);
+</code></pre>
+
+<h2>
+<a name="FileEntry_createwriter">createWriter</a>
+</h2>
+
+<p>Create a <code><a href="cordova_file_file.md.html#FileWriter">FileWriter</a></code> object associated with the file represented by the <code><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></code>.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>successCallback</strong>: A callback that is passed a <code><a href="cordova_file_file.md.html#FileWriter">FileWriter</a></code> object. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs while attempting to create the <a href="cordova_file_file.md.html#FileWriter">FileWriter</a>. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(writer) {
+ writer.write("Some text to the file");
+}
+
+function fail(error) {
+ alert(error.code);
+}
+
+// create a <a href="cordova_file_file.md.html#FileWriter">FileWriter</a> to write to the file
+entry.createWriter(success, fail);
+</code></pre>
+
+<h2>
+<a name="FileEntry_file">file</a>
+</h2>
+
+<p>Return a <code><a href="cordova_file_file.md.html#File">File</a></code> object that represents the current state of the file
+that this <code><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></code> represents.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>successCallback</strong>: A callback that is passed a <code><a href="cordova_file_file.md.html#File">File</a></code> object. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when creating the <code><a href="cordova_file_file.md.html#File">File</a></code> object, such as when the file no longer exists. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(file) {
+ console.log("<a href="cordova_file_file.md.html#File">File</a> size: " + file.size);
+}
+
+function fail(error) {
+ alert("Unable to retrieve file properties: " + error.code);
+}
+
+// obtain properties of a file
+entry.file(success, fail);
+</code></pre>
+
+<hr>
+<h1><a name="DirectoryEntry">DirectoryEntry</a></h1>
+
+<p>This object represents a directory on a file system, as defined by the
+<a class="external" href="http://www.w3.org/TR/file-system-api/">W3C Directories and Systems</a>
+specification.</p>
+
+<h2>
+<a name="DirectoryEntry_properties">Properties</a>
+</h2>
+
+<ul>
+<li><p><strong>isFile</strong>: Always <code>false</code>. <em>(boolean)</em></p></li>
+<li><p><strong>isDirectory</strong>: Always <code>true</code>. <em>(boolean)</em></p></li>
+<li><p><strong>name</strong>: The name of the <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code>, excluding the path leading to it. <em>(DOMString)</em></p></li>
+<li><p><strong>fullPath</strong>: The full absolute path from the root to the <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code>. <em>(DOMString)</em></p></li>
+</ul>
+<p><strong>NOTE:</strong> The following attribute is defined by the W3C specification,
+but is <em>not</em> supported:</p>
+
+<ul>
+<li>
+<strong>filesystem</strong>: The file system on which the <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code> resides. <em>(<a href="cordova_file_file.md.html#FileSystem">FileSystem</a>)</em>
+</li>
+</ul>
+<h2>
+<a name="DirectoryEntry_methods">Methods</a>
+</h2>
+
+<p>The following methods can be invoked on a <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code> object:</p>
+
+<ul>
+<li><p><strong>getMetadata</strong>: Look up metadata about a directory.</p></li>
+<li><p><strong>setMetadata</strong>: Set metadata on a directory.</p></li>
+<li><p><strong>moveTo</strong>: Move a directory to a different location on the file system.</p></li>
+<li><p><strong>copyTo</strong>: Copy a directory to a different location on the file system.</p></li>
+<li><p><strong>toURL</strong>: Return a URL to help locate a directory.</p></li>
+<li><p><strong>remove</strong>: Delete a directory. The directory must be empty.</p></li>
+<li><p><strong>getParent</strong>: Look up the parent directory.</p></li>
+<li><p><strong>createReader</strong>: Create a new <code><a href="cordova_file_file.md.html#DirectoryReader">DirectoryReader</a></code> that can read entries from a directory.</p></li>
+<li><p><strong>getDirectory</strong>: Create or look up a directory.</p></li>
+<li><p><strong>getFile</strong>: Create or look up a file.</p></li>
+<li><p><strong>removeRecursively</strong>: Delete a directory and all of its contents.</p></li>
+</ul>
+<h2>
+<a name="DirectoryEntry_supported_platforms">Supported Platforms</a>
+</h2>
+
+<ul>
+<li>Android</li>
+<li>BlackBerry WebWorks (OS 5.0 and higher)</li>
+<li>iOS</li>
+<li>Windows Phone 7 and 8</li>
+<li>Windows 8</li>
+</ul>
+<h2>
+<a name="DirectoryEntry_getmetadata">getMetadata</a>
+</h2>
+
+<p>Look up metadata about a directory.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>successCallback</strong>: A callback function to execute with a <code><a href="cordova_file_file.md.html#Metadata">Metadata</a></code> object. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback function to execute if an error occurs when retrieving the <code><a href="cordova_file_file.md.html#Metadata">Metadata</a></code>. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(metadata) {
+ console.log("Last Modified: " + metadata.modificationTime);
+}
+
+function fail(error) {
+ alert(error.code);
+}
+
+// Request the metadata object for this entry
+entry.getMetadata(success, fail);
+</code></pre>
+
+<h2>
+<a name="DirectoryEntry_setmetadata">setMetadata</a>
+</h2>
+
+<p>Sets a directory's extended attributes, or metadata. <em>Currently works
+only on iOS.</em></p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>successCallback</strong>: A callback that executes when the metadata is successfully set. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes when the metadata fails to be set. <em>(Function)</em></p></li>
+<li><p><strong>metadataObject</strong>: An object that contains the metadata's keys and values. <em>(Object)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success() {
+ console.log("The metadata was successfully set.");
+}
+
+function fail() {
+ alert("There was an error in setting the metadata");
+}
+
+// Set the metadata
+entry.setMetadata(success, fail, { "com.apple.MobileBackup": 1});
+</code></pre>
+
+<p><strong>iOS Quirk</strong></p>
+
+<ul>
+<li>Only the <code>com.apple.MobileBackup</code> extended attribute is supported. Set the value to <code>1</code> to prevent the directory from being backed up to iCloud. Set the value to <code>0</code> to re-enable the directory to be backed up to iCloud.</li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function setFolderMetadata(localFileSystem, subFolder, metadataKey, metadataValue)
+{
+ var onSetMetadataWin = function() {
+ console.log("success setting metadata")
+ }
+ var onSetMetadataFail = function() {
+ console.log("error setting metadata")
+ }
+
+ var onGetDirectoryWin = function(parent) {
+ var data = {};
+ data[metadataKey] = metadataValue;
+ parent.setMetadata(onSetMetadataWin, onSetMetadataFail, data);
+ }
+ var onGetDirectoryFail = function() {
+ console.log("error getting dir")
+ }
+
+ var onFSWin = function(fileSystem) {
+ fileSystem.root.getDirectory(subFolder, {create: true, exclusive: false}, onGetDirectoryWin, onGetDirectoryFail);
+ }
+
+ var onFSFail = function(evt) {
+ console.log(evt.target.error.code);
+ }
+
+ window.<a href="cordova_file_file.md.html#requestFileSystem">requestFileSystem</a>(localFileSystem, 0, onFSWin, onFSFail);
+}
+
+ setFolderMetadata(<a href="cordova_file_file.md.html#LocalFileSystem">LocalFileSystem</a>.PERSISTENT, "Backups", "com.apple.MobileBackup", 1);
+</code></pre>
+
+<h2>
+<a name="DirectoryEntry_moveto">moveTo</a>
+</h2>
+
+<p>Move a directory to a different location on the file system. An error results if the app attempts to:</p>
+
+<ul>
+<li><p>move a directory inside itself or to any child at any depth.</p></li>
+<li><p>move a directory into its parent if a name different from its current directory is not provided.</p></li>
+<li><p>move a directory to a path occupied by a file.</p></li>
+<li><p>move a directory to a path occupied by a directory that is not empty.</p></li>
+</ul>
+<p>Moving a directory on top of an existing empty directory attempts to
+delete and replace that directory.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>parent</strong>: The parent directory to which to move the directory. <em>(<a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>)</em></p></li>
+<li><p><strong>newName</strong>: The new name of the directory. Defaults to the current name if unspecified. <em>(DOMString)</em></p></li>
+<li><p><strong>successCallback</strong>: A callback that executes with the <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code> object for the new directory. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when attempting to move the directory. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(entry) {
+ console.log("New Path: " + entry.fullPath);
+}
+
+function fail(error) {
+ alert(error.code);
+}
+
+function moveDir(entry) {
+ var parent = document.getElementById('parent').value,
+ parentName = parent.substring(parent.lastIndexOf('/')+1),
+ newName = document.getElementById('newName').value,
+ parentEntry = new <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>(parentName, parent);
+
+ // move the directory to a new directory and rename it
+ entry.moveTo(parentEntry, newName, success, fail);
+}
+</code></pre>
+
+<h2>
+<a name="DirectoryEntry_copyto">copyTo</a>
+</h2>
+
+<p>Copy a directory to a different location on the file system. An error results if the app attempts to:</p>
+
+<ul>
+<li><p>copy a directory inside itself at any depth.</p></li>
+<li><p>copy a directory into its parent if a name different from its current directory is not provided.</p></li>
+</ul>
+<p>Directory copies are always recursive, and copy all contents of the directory.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>parent</strong>: The parent directory to which to copy the directory. <em>(<a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>)</em></p></li>
+<li><p><strong>newName</strong>: The new name of the directory. Defaults to the current name if unspecified. <em>(DOMString)</em></p></li>
+<li><p><strong>successCallback</strong>: A callback that executes with the <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code> object for the new directory. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when attempting to copy the underlying directory. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function win(entry) {
+ console.log("New Path: " + entry.fullPath);
+}
+
+function fail(error) {
+ alert(error.code);
+}
+
+function copyDir(entry) {
+ var parent = document.getElementById('parent').value,
+ parentName = parent.substring(parent.lastIndexOf('/')+1),
+ newName = document.getElementById('newName').value,
+ parentEntry = new <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>(parentName, parent);
+
+ // copy the directory to a new directory and rename it
+ entry.copyTo(parentEntry, newName, success, fail);
+}
+</code></pre>
+
+<h2>
+<a name="DirectoryEntry_tourl">toURL</a>
+</h2>
+
+<p>Returns a URL that can be used to locate the directory.</p>
+
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>// Get the URL for this directory
+var dirURL = entry.toURL();
+console.log(dirURL);
+</code></pre>
+
+<h2>
+<a name="DirectoryEntry_remove">remove</a>
+</h2>
+
+<p>Deletes a directory. An error results if the app attempts to:</p>
+
+<ul>
+<li><p>delete a directory that is not empty.</p></li>
+<li><p>delete the root directory of a filesystem.</p></li>
+</ul>
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>successCallback</strong>: A callback that executes after the directory is deleted. Invoked with no parameters. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when attempting to delete the directory. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(entry) {
+ console.log("Removal succeeded");
+}
+
+function fail(error) {
+ alert('Error removing directory: ' + error.code);
+}
+
+// remove this directory
+entry.remove(success, fail);
+</code></pre>
+
+<h2>
+<a name="DirectoryEntry_getparent">getParent</a>
+</h2>
+
+<p>Look up the parent <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code> containing the directory.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>successCallback</strong>: A callback that is passed the directory's parent <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code>. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when attempting to retrieve the parent <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code>. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(parent) {
+ console.log("Parent Name: " + parent.name);
+}
+
+function fail(error) {
+ alert('Failed to get parent directory: ' + error.code);
+}
+
+// Get the parent <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>
+entry.getParent(success, fail);
+</code></pre>
+
+<h2>
+<a name="DirectoryEntry_createreader">createReader</a>
+</h2>
+
+<p>Creates a new <a href="cordova_file_file.md.html#DirectoryReader">DirectoryReader</a> to read entries in a directory.</p>
+
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>// create a directory reader
+var directoryReader = entry.createReader();
+</code></pre>
+
+<h2>
+<a name="DirectoryEntry_getdirectory">getDirectory</a>
+</h2>
+
+<p>Creates or looks up an existing directory. An error results if the app attempts to:</p>
+
+<ul>
+<li>create a directory whose immediate parent does not yet exist.</li>
+</ul>
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>path</strong>: The path to the directory to be looked up or created. Either an absolute path, or a relative path from this <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code>. <em>(DOMString)</em></p></li>
+<li><p><strong>options</strong>: Options to specify whether the directory is to be created if it doesn't exist. <em>(<a href="cordova_file_file.md.html#Flags">Flags</a>)</em></p></li>
+<li><p><strong>successCallback</strong>: A callback that executes with a <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code> object. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when creating or looking up the directory. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(dirEntry) {
+ console.log("Directory Name: " + dirEntry.name);
+}
+
+function fail(error) {
+ alert("Unable to create new directory: " + error.code);
+}
+
+// Retrieve an existing directory, or create it if it does not already exist
+entry.getDirectory("newDir", {create: true, exclusive: false}, success, fail);
+</code></pre>
+
+<h2>
+<a name="DirectoryEntry_getfile">getFile</a>
+</h2>
+
+<p>Creates or looks up a file. An error results if the app attempts to:</p>
+
+<ul>
+<li>create a file whose immediate parent does not yet exist.</li>
+</ul>
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>path</strong>: The path to the file to be looked up or created. Either an absolute path, or a relative path from this <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code>. <em>(DOMString)</em></p></li>
+<li><p><strong>options</strong>: Options to specify whether the file is created if it doesn't exist. <em>(<a href="cordova_file_file.md.html#Flags">Flags</a>)</em></p></li>
+<li><p><strong>successCallback</strong>: A callback that is passed a <code><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></code> object. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when creating or looking up the file. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(fileEntry) {
+ console.log("<a href="cordova_file_file.md.html#File">File</a> Name: " + fileEntry.name);
+}
+
+function fail(error) {
+ alert("Failed to retrieve file: " + error.code);
+}
+
+// Retrieve an existing file, or create it if it does not exist
+entry.getFile("newFile.txt", {create: true, exclusive: false}, success, fail);
+</code></pre>
+
+<h2>
+<a name="DirectoryEntry_removerecursively">removeRecursively</a>
+</h2>
+
+<p>Deletes a directory and all of its contents. In the event of an error (such as trying to delete
+a directory containing a file that cannot be removed), some of the contents of the directory may
+be deleted. An error results if the app attempts to:</p>
+
+<ul>
+<li>delete the root directory of a filesystem.</li>
+</ul>
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>successCallback</strong>: A callback that executes after the <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code> has been deleted. Invoked with no parameters. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when attempting to delete the <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code>. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(parent) {
+ console.log("Remove Recursively Succeeded");
+}
+
+function fail(error) {
+ alert("Failed to remove directory or it's contents: " + error.code);
+}
+
+// remove the directory and all it's contents
+entry.removeRecursively(success, fail);
+</code></pre>
+
+<h2>
+<a name="DirectoryEntry_blackberry_quirks">BlackBerry Quirks</a>
+</h2>
+
+<p>May fail with a <code>ControlledAccessException</code> in the following cases:</p>
+
+<ul>
+<li>An app attempts to access a directory created by a previous installation of the app.</li>
+</ul>
+<blockquote>
+ <p>Solution: ensure temporary directories are cleaned manually, or by the application prior to reinstallation.</p>
+</blockquote>
+
+<ul>
+<li>If the device is connected by USB.</li>
+</ul>
+<blockquote>
+ <p>Solution: disconnect the USB cable from the device and run again.</p>
+</blockquote>
+
+<hr>
+<h1><a name="DirectoryReader">DirectoryReader</a></h1>
+
+<p>An object that lists files and directories within a directory, as
+defined in the
+<a class="external" href="http://www.w3.org/TR/file-system-api/">W3C Directories and Systems</a>
+specification.</p>
+
+<h2>
+<a name="DirectoryReader_methods">Methods</a>
+</h2>
+
+<ul>
+<li>
+<strong>readEntries</strong>: Read the entries in a directory.</li>
+</ul>
+<h2>
+<a name="DirectoryReader_supported_platforms">Supported Platforms</a>
+</h2>
+
+<ul>
+<li>Android</li>
+<li>BlackBerry WebWorks (OS 5.0 and higher)</li>
+<li>iOS</li>
+<li>Windows Phone 7 and 8</li>
+<li>Windows 8</li>
+</ul>
+<h2>
+<a name="DirectoryReader_readentries">readEntries</a>
+</h2>
+
+<p>Read the entries in this directory.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>successCallback</strong>: A callback that is passed an array of <code><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></code> and <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code> objects. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when retrieving the directory listing. Invoked with a <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object. <em>(Function)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>function success(entries) {
+ var i;
+ for (i=0; i<entries.length; i++) {
+ console.log(entries[i].name);
+ }
+}
+
+function fail(error) {
+ alert("Failed to list directory contents: " + error.code);
+}
+
+// Get a directory reader
+var directoryReader = dirEntry.createReader();
+
+// Get a list of all the entries in the directory
+directoryReader.readEntries(success,fail);
+</code></pre>
+
+<hr>
+<h1><a name="FileTransfer">FileTransfer</a></h1>
+
+<p>The <code><a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a></code> object allows you to upload or download files to
+and from a server.</p>
+
+<h2>
+<a name="FileTransfer_properties">Properties</a>
+</h2>
+
+<ul>
+<li>
+<strong>onprogress</strong>: Called with a <code>ProgressEvent</code> whenever a new chunk of data is transferred. <em>(Function)</em>
+</li>
+</ul>
+<h2>
+<a name="FileTransfer_methods">Methods</a>
+</h2>
+
+<ul>
+<li><p><strong>upload</strong>: sends a file to a server.</p></li>
+<li><p><strong>download</strong>: downloads a file from server.</p></li>
+<li><p><strong>abort</strong>: Aborts an in-progress transfer.</p></li>
+</ul>
+<h2>
+<a name="FileTransfer_details">Details</a>
+</h2>
+
+<p>The <code><a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a></code> object provides a way to upload files to a remote
+server using an HTTP multi-part POST request. Both HTTP and HTTPS
+protocols are supported. Optional parameters can be specified by
+passing a <code><a href="cordova_file_file.md.html#FileUploadOptions">FileUploadOptions</a></code> object to the <code>upload()</code> method. On
+successful upload, a <code><a href="cordova_file_file.md.html#FileUploadResult">FileUploadResult</a></code> object is passed to the
+success callback. If an error occurs, a <code><a href="cordova_file_file.md.html#FileTransferError">FileTransferError</a></code> object is
+passed to the error callback. It is also possible (only on iOS and
+Android) to download a file from a remote server and save it on the
+device.</p>
+
+<h2>
+<a name="FileTransfer_supported_platforms">Supported Platforms</a>
+</h2>
+
+<ul>
+<li>Android</li>
+<li>BlackBerry WebWorks (OS 5.0 and higher)</li>
+<li>iOS</li>
+<li>Windows Phone 7 and 8</li>
+<li>Windows 8</li>
+</ul>
+<h2>
+<a name="FileTransfer_upload">upload</a>
+</h2>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>filePath</strong>: Full path of the file on the device.</p></li>
+<li><p><strong>server</strong>: URL of the server to receive the file, as encoded by <code>encodeURI()</code>.</p></li>
+<li><p><strong>successCallback</strong>: A callback that is passed a <code><a href="cordova_file_file.md.html#Metadata">Metadata</a></code> object. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs retrieving the <code><a href="cordova_file_file.md.html#Metadata">Metadata</a></code>. Invoked with a <code><a href="cordova_file_file.md.html#FileTransferError">FileTransferError</a></code> object. <em>(Function)</em></p></li>
+<li><p><strong>options</strong>: Optional parameters such as file name and mimetype.</p></li>
+<li><p><strong>trustAllHosts</strong>: Optional parameter, defaults to <code>false</code>. If set to <code>true</code>, it accepts all security certificates. This is useful since Android rejects self-signed security certificates. Not recommended for production use. Supported on Android and iOS. <em>(boolean)</em></p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>// !! Assumes variable fileURI contains a valid URI to a text file on the device
+
+var win = function (r) {
+ console.log("Code = " + r.responseCode);
+ console.log("Response = " + r.response);
+ console.log("Sent = " + r.bytesSent);
+}
+
+var fail = function (error) {
+ alert("An error has occurred: Code = " + error.code);
+ console.log("upload error source " + error.source);
+ console.log("upload error target " + error.target);
+}
+
+var options = new <a href="cordova_file_file.md.html#FileUploadOptions">FileUploadOptions</a>();
+options.fileKey = "file";
+options.fileName = fileURI.substr(fileURI.lastIndexOf('/') + 1);
+options.mimeType = "text/plain";
+
+var params = {};
+params.value1 = "test";
+params.value2 = "param";
+
+options.params = params;
+
+var ft = new <a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>();
+ft.upload(fileURI, encodeURI("http://some.server.com/upload.php"), win, fail, options);
+</code></pre>
+
+<p><strong>Full Example</strong></p>
+
+<pre class="prettyprint"><code><!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+ <title><a href="cordova_file_file.md.html#File">File</a> Transfer Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="cordova.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for device API libraries to load
+ //
+ document.<a href="cordova_inappbrowser_inappbrowser.md.html#addEventListener">addEventListener</a>("<a href="cordova_events_events.md.html#deviceready">deviceready</a>", onDeviceReady, false);
+
+ // device APIs are available
+ //
+ function onDeviceReady() {
+ // Retrieve image file location from specified source
+ navigator.<a href="cordova_camera_camera.md.html#camera.getPicture">camera.getPicture</a>(
+ uploadPhoto,
+ function(message) { alert('get picture failed'); },
+ {
+ quality : 50,
+ destinationType : navigator.camera.DestinationType.FILE_URI,
+ sourceType : navigator.camera.PictureSourceType.PHOTOLIBRARY
+ }
+ );
+ }
+
+ function uploadPhoto(imageURI) {
+ var options = new <a href="cordova_file_file.md.html#FileUploadOptions">FileUploadOptions</a>();
+ options.fileKey="file";
+ options.fileName=imageURI.substr(imageURI.lastIndexOf('/')+1);
+ options.mimeType="image/jpeg";
+
+ var params = {};
+ params.value1 = "test";
+ params.value2 = "param";
+
+ options.params = params;
+
+ var ft = new <a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>();
+ ft.upload(imageURI, encodeURI("http://some.server.com/upload.php"), win, fail, options);
+ }
+
+ function win(r) {
+ console.log("Code = " + r.responseCode);
+ console.log("Response = " + r.response);
+ console.log("Sent = " + r.bytesSent);
+ }
+
+ function fail(error) {
+ alert("An error has occurred: Code = " + error.code);
+ console.log("upload error source " + error.source);
+ console.log("upload error target " + error.target);
+ }
+
+ </script>
+</head>
+<body>
+ <h1>Example</h1>
+ <p>Upload <a href="cordova_file_file.md.html#File">File</a></p>
+</body>
+</html>
+</code></pre>
+
+<p><strong>Setting Upload Headers</strong></p>
+
+<p>Supported on Android and iOS</p>
+
+<pre class="prettyprint"><code>function win(r) {
+ console.log("Code = " + r.responseCode);
+ console.log("Response = " + r.response);
+ console.log("Sent = " + r.bytesSent);
+}
+
+function fail(error) {
+ alert("An error has occurred: Code = " + error.code);
+ console.log("upload error source " + error.source);
+ console.log("upload error target " + error.target);
+}
+
+var uri = encodeURI("http://some.server.com/upload.php");
+
+var options = new <a href="cordova_file_file.md.html#FileUploadOptions">FileUploadOptions</a>();
+options.fileKey="file";
+options.fileName=fileURI.substr(fileURI.lastIndexOf('/')+1);
+options.mimeType="text/plain";
+
+var headers={'headerParam':'headerValue'};
+
+options.headers = headers;
+
+var ft = new <a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>();
+ft.upload(fileURI, uri, win, fail, options);
+</code></pre>
+
+<p><strong>Android Quirks</strong></p>
+
+<p>Set the <code>chunkedMode</code> option to <code>false</code> to prevent problems uploading
+to a Nginx server.</p>
+
+<h2>
+<a name="FileTransfer_download">download</a>
+</h2>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li><p><strong>source</strong>: URL of the server to download the file, as encoded by <code>encodeURI()</code>.</p></li>
+<li><p><strong>target</strong>: Full path of the file on the device.</p></li>
+<li><p><strong>successCallback</strong>: A callback that is passed a <code><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></code> object. <em>(Function)</em></p></li>
+<li><p><strong>errorCallback</strong>: A callback that executes if an error occurs when retrieving the <code><a href="cordova_file_file.md.html#Metadata">Metadata</a></code>. Invoked with a <code><a href="cordova_file_file.md.html#FileTransferError">FileTransferError</a></code> object. <em>(Function)</em></p></li>
+<li><p><strong>trustAllHosts</strong>: Optional parameter, defaults to <code>false</code>. If set to <code>true</code> then it will accept all security certificates. This is useful as Android rejects self signed security certificates. Not recommended for production use. Supported on Android and iOS. <em>(boolean)</em></p></li>
+<li><p><strong>options</strong>: Optional parameters, currently only supports headers (such as Authorization (Basic Authentication), etc).</p></li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>// !! Assumes filePath is a valid path on the device
+
+var fileTransfer = new <a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>();
+var uri = encodeURI("http://some.server.com/download.php");
+
+fileTransfer.download(
+ uri,
+ filePath,
+ function(entry) {
+ console.log("download complete: " + entry.fullPath);
+ },
+ function(error) {
+ console.log("download error source " + error.source);
+ console.log("download error target " + error.target);
+ console.log("upload error code" + error.code);
+ },
+ false,
+ {
+ headers: {
+ "Authorization": "Basic dGVzdHVzZXJuYW1lOnRlc3RwYXNzd29yZA=="
+ }
+ }
+);
+</code></pre>
+
+<h2>
+<a name="FileTransfer_abort">abort</a>
+</h2>
+
+<p>Aborts an in-progress transfer. The onerror callback is passed a <a href="cordova_file_file.md.html#FileTransferError">FileTransferError</a> object which has an error code of <a href="cordova_file_file.md.html#FileTransferError">FileTransferError</a>.ABORT_ERR.</p>
+
+<p><strong>Supported Platforms</strong></p>
+
+<ul>
+<li>Android</li>
+<li>iOS</li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code>// !! Assumes variable fileURI contains a valid URI to a text file on the device
+
+var win = function(r) {
+ console.log("Should not be called.");
+}
+
+var fail = function(error) {
+ // error.code == <a href="cordova_file_file.md.html#FileTransferError">FileTransferError</a>.ABORT_ERR
+ alert("An error has occurred: Code = " + error.code);
+ console.log("upload error source " + error.source);
+ console.log("upload error target " + error.target);
+}
+
+var options = new <a href="cordova_file_file.md.html#FileUploadOptions">FileUploadOptions</a>();
+options.fileKey="file";
+options.fileName="myphoto.jpg";
+options.mimeType="image/jpeg";
+
+var ft = new <a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>();
+ft.upload(fileURI, encodeURI("http://some.server.com/upload.php"), win, fail, options);
+ft.abort();
+</code></pre>
+
+<h2>
+<a name="FileTransfer_onprogress">onprogress</a>
+</h2>
+
+<p>Called with a ProgressEvent whenever a new chunk of data is transferred.</p>
+
+<p><strong>Supported Platforms</strong></p>
+
+<ul>
+<li>Android</li>
+<li>iOS</li>
+</ul>
+<p><strong>Example</strong></p>
+
+<pre class="prettyprint"><code>fileTransfer.onprogress = function(progressEvent) {
+ if (progressEvent.lengthComputable) {
+ loadingStatus.setPercentage(progressEvent.loaded / progressEvent.total);
+ } else {
+ loadingStatus.increment();
+ }
+};
+fileTransfer.download(...); // or fileTransfer.upload(...);
+</code></pre>
+
+<p><strong>Quirks</strong>
+- On both Android an iOS, lengthComputable is <code>false</code> for downloads that use gzip encoding.</p>
+
+<hr>
+<h1><a name="FileUploadOptions">FileUploadOptions</a></h1>
+
+<p>A <code><a href="cordova_file_file.md.html#FileUploadOptions">FileUploadOptions</a></code> object can be passed to the <code><a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a></code>
+object's <code>upload()</code> method to specify additional parameters to the
+upload script.</p>
+
+<h2>
+<a name="FileUploadOptions_properties">Properties</a>
+</h2>
+
+<ul>
+<li><p><strong>fileKey</strong>: The name of the form element. Defaults to <code>file</code>. (DOMString)</p></li>
[... 350 lines stripped ...]