You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@cordova.apache.org by mw...@apache.org on 2012/07/13 00:09:52 UTC
[5/64] Add generated HTML documentation.
http://git-wip-us.apache.org/repos/asf/incubator-cordova-docs/blob/62a5f4d2/www/cordova_file_file.md.html
----------------------------------------------------------------------
diff --git a/www/cordova_file_file.md.html b/www/cordova_file_file.md.html
new file mode 100644
index 0000000..3089c67
--- /dev/null
+++ b/www/cordova_file_file.md.html
@@ -0,0 +1,2271 @@
+<!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="English" value="en"><option selected 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_permissions"> - Permissions</option>
+<option value="File">File</option>
+<option value="File_properties"> - Properties</option>
+<option value="File_details"> - Details</option>
+<option value="File_supported_platforms"> - Supported Platforms</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_read_as_data_url"> - Read As Data URL </option>
+<option value="FileReader_quick_example"> - Quick Example</option>
+<option value="FileReader_read_as_text"> - Read As Text</option>
+<option value="FileReader_quick_example"> - Quick Example</option>
+<option value="FileReader_abort_quick_example"> - Abort Quick Example</option>
+<option value="FileReader_full_example"> - Full Example</option>
+<option value="FileReader_ios_quirks"> - iOS Quirks</option>
+<option value="FileWriter">FileWriter</option>
+<option value="FileWriter_properties"> - Properties</option>
+<option value="FileWriter_methods"> - Methods</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_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="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_ios_quirks"> - iOS Quirks</option>
+<option value="FileTransfer_download"> - download</option>
+<option value="FileUploadOptions">FileUploadOptions</option>
+<option value="FileUploadOptions_properties"> - Properties</option>
+<option value="FileUploadOptions_description"> - Description</option>
+<option value="FileUploadOptions_ios_quirk"> - iOS Quirk</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="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>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_media_media.md.html#Media">Media</a></li>
+<li><a href="cordova_notification_notification.md.html#Notification">Notification</a></li>
+<li><a href="cordova_storage_storage.md.html#Storage">Storage</a></li>
+</ul>
+<h1>Guides</h1>
+<ul>
+<li><a href="guide_getting-started_index.md.html#Getting%20Started%20Guides">Getting Started Guides</a></li>
+<li><a href="guide_command-line_index.md.html#Command-Line%20Usage">Command-Line Usage</a></li>
+<li><a href="guide_upgrading_index.md.html#Upgrading%20Guides">Upgrading Guides</a></li>
+<li><a href="guide_whitelist_index.md.html#Domain%20Whitelist%20Guide">Domain Whitelist Guide</a></li>
+<li><a href="guide_cordova-webview_index.md.html#Embedding%20WebView">Embedding WebView</a></li>
+<li><a href="_index.html">Keyword Index</a></li>
+</ul>
+</div>
+
+ <div id="scrollable">
+ <div id="content">
+ <h1><a name="File">File</a></h1>
+
+<blockquote>
+ <p>This API is based on the W3C <a class="external" href="http://www.w3.org/TR/FileAPI"></a><a href="cordova_file_file.md.html#File">File</a> API. An API to read, write and navigate file system hierarchies.</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_permissions">Permissions</a>
+</h2>
+
+<h3>Android</h3>
+
+<h4>app/res/xml/plugins.xml</h4>
+
+<pre class="prettyprint"><code><plugin name="<a href="cordova_file_file.md.html#File">File</a>" value="org.apache.cordova.FileUtils" />
+<plugin name="<a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>" value="org.apache.cordova.<a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>" />
+</code></pre>
+
+<h4>app/AndroidManifest.xml</h4>
+
+<pre class="prettyprint"><code><uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+</code></pre>
+
+<h3>Bada</h3>
+
+<pre class="prettyprint"><code>No permissions are required.
+</code></pre>
+
+<h3>BlackBerry WebWorks</h3>
+
+<h4>www/plugins.xml</h4>
+
+<pre class="prettyprint"><code><plugin name="<a href="cordova_file_file.md.html#File">File</a>" value="org.apache.cordova.file.FileManager" />
+<plugin name="<a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>" value="org.apache.cordova.http.<a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>" />
+</code></pre>
+
+<h4>www/config.xml</h4>
+
+<pre class="prettyprint"><code><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>
+
+<h3>iOS</h3>
+
+<h4>App/Supporting Files/Cordova.plist</h4>
+
+<pre class="prettyprint"><code><key>Plugins</key>
+<dict>
+ <key><a href="cordova_file_file.md.html#File">File</a></key>
+ <string>CDVFile</string>
+</dict>
+
+<key>Plugins</key>
+<dict>
+ <key><a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a></key>
+ <string>CDVFileTransfer</string>
+</dict>
+</code></pre>
+
+<h3>webOS</h3>
+
+<pre class="prettyprint"><code>No permissions are required.
+</code></pre>
+
+<h3>Windows Phone</h3>
+
+<pre class="prettyprint"><code>No permissions are required.
+</code></pre>
+
+<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>
+<strong>name:</strong> The name of the file. <em>(DOMString)</em>
+</li>
+<li>
+<strong>fullPath:</strong> The full path of the file including the file name. <em>(DOMString)</em>
+</li>
+<li>
+<strong>type:</strong> The mime type of the file. <em>(DOMString)</em>
+</li>
+<li>
+<strong>lastModifiedDate:</strong> The last time the file was modified. <em>(Date)</em>
+</li>
+<li>
+<strong>size:</strong> The size of the file in bytes. <em>(long)</em>
+</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 <a href="cordova_file_file.md.html#File">File</a> object by calling the <strong>file</strong> method of a <code><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></code> object.</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 ( Mango )</li>
+</ul>
+<hr>
+<h1><a name="FileReader">FileReader</a></h1>
+
+<p><a href="cordova_file_file.md.html#FileReader">FileReader</a> is an object that allows one to read a file.</p>
+
+<h2>
+<a name="FileReader_properties">Properties</a>
+</h2>
+
+<ul>
+<li>
+<strong>readyState:</strong> One of the three states the reader can be in EMPTY, LOADING or DONE.</li>
+<li>
+<strong>result:</strong> The contents of the file that has been read. <em>(DOMString)</em>
+</li>
+<li>
+<strong>error:</strong> An object containing errors. <em>(<a href="cordova_file_file.md.html#FileError">FileError</a>)</em>
+</li>
+<li>
+<strong>onloadstart:</strong> Called when the read starts. . <em>(Function)</em>
+</li>
+<li>
+<strong>onprogress:</strong> Called while reading the file, reports progress (progess.loaded/progress.total). <em>(Function)</em> -NOT SUPPORTED</li>
+<li>
+<strong>onload:</strong> Called when the read has successfully completed. <em>(Function)</em>
+</li>
+<li>
+<strong>onabort:</strong> Called when the read has been aborted. For instance, by invoking the abort() method. <em>(Function)</em>
+</li>
+<li>
+<strong>onerror:</strong> Called when the read has failed. <em>(Function)</em>
+</li>
+<li>
+<strong>onloadend:</strong> Called when the request has completed (either in success or failure). <em>(Function)</em>
+</li>
+</ul>
+<h2>
+<a name="FileReader_methods">Methods</a>
+</h2>
+
+<ul>
+<li>
+<strong>abort</strong>: Aborts reading file. </li>
+<li>
+<strong>readAsDataURL</strong>: Read file and return data as a base64 encoded data url.</li>
+<li>
+<strong>readAsText</strong>: Reads text file.</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 is a way to read files from the devices file system. Files can be read as text or as a base64 data encoded string. Users register their own event listners to receive the loadstart, progress, load, loadend, error and abort 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 ( Mango )</li>
+</ul>
+<h2>
+<a name="FileReader_read_as_data_url">Read As Data URL </a>
+</h2>
+
+<p><strong>Parameters:</strong>
+- file - the file object to read</p>
+
+<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(evt) {
+ console.log(error.code);
+};
+
+entry.file(win, fail);
+</code></pre>
+
+<h2>
+<a name="FileReader_read_as_text">Read As Text</a>
+</h2>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>file - the file object to read</li>
+<li>encoding - the encoding to use to encode the file's content. Default is UTF8.</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(evt) {
+ console.log(error.code);
+};
+
+entry.file(win, fail);
+</code></pre>
+
+<h2>
+<a name="FileReader_abort_quick_example">Abort 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);
+ 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-1.9.0.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for Cordova to load
+ //
+ function onLoad() {
+ document.addEventListener("<a href="cordova_events_events.md.html#deviceready">deviceready</a>", onDeviceReady, false);
+ }
+
+ // Cordova is ready
+ //
+ function onDeviceReady() {
+ window.requestFileSystem(<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(evt) {
+ console.log(evt.target.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>
+<strong>encoding</strong> parameter is not supported, UTF8 encoding is always used.</li>
+</ul>
+<hr>
+<h1><a name="FileWriter">FileWriter</a></h1>
+
+<p><a href="cordova_file_file.md.html#FileWriter">FileWriter</a> is an object that allows one to write a file.</p>
+
+<h2>
+<a name="FileWriter_properties">Properties</a>
+</h2>
+
+<ul>
+<li>
+<strong>readyState:</strong> One of the three states the reader can be in INIT, WRITING or DONE.</li>
+<li>
+<strong>fileName:</strong> The name of the file to be written. <em>(DOMString)</em>
+</li>
+<li>
+<strong>length:</strong> The length of the file to be written. <em>(long)</em>
+</li>
+<li>
+<strong>position:</strong> The current position of the file pointer. <em>(long)</em>
+</li>
+<li>
+<strong>error:</strong> An object containing errors. <em>(<a href="cordova_file_file.md.html#FileError">FileError</a>)</em>
+</li>
+<li>
+<strong>onwritestart:</strong> Called when the write starts. . <em>(Function)</em>
+</li>
+<li>
+<strong>onprogress:</strong> Called while writing the file, reports progress (progess.loaded/progress.total). <em>(Function)</em> -NOT SUPPORTED</li>
+<li>
+<strong>onwrite:</strong> Called when the request has completed successfully. <em>(Function)</em>
+</li>
+<li>
+<strong>onabort:</strong> Called when the write has been aborted. For instance, by invoking the abort() method. <em>(Function)</em>
+</li>
+<li>
+<strong>onerror:</strong> Called when the write has failed. <em>(Function)</em>
+</li>
+<li>
+<strong>onwriteend:</strong> Called when the request has completed (either in success or failure). <em>(Function)</em>
+</li>
+</ul>
+<h2>
+<a name="FileWriter_methods">Methods</a>
+</h2>
+
+<ul>
+<li>
+<strong>abort</strong>: Aborts writing file. </li>
+<li>
+<strong>seek</strong>: Moves the file pointer to the byte specified.</li>
+<li>
+<strong>truncate</strong>: Shortens the file to the length specified.</li>
+<li>
+<strong>write</strong>: Writes data to the file with a UTF-8 encoding.</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 is a way to write files to the device file system (UTF-8 encoded). Users register their own event listeners to receive the writestart, progress, write, writeend, error and abort events.</p>
+
+<p>A <a href="cordova_file_file.md.html#FileWriter">FileWriter</a> is created for a single file. You can use it to write to a file multiple times. The <a href="cordova_file_file.md.html#FileWriter">FileWriter</a> maintains the file's position and length attributes, so you can seek and write anywhere in the file. By default, the <a href="cordova_file_file.md.html#FileWriter">FileWriter</a> writes to the beginning of the file (will overwrite existing data). Set the optional append boolean to true in the <a href="cordova_file_file.md.html#FileWriter">FileWriter</a>'s constructor to begin writing to the end of the file.</p>
+
+<h2>
+<a name="FileWriter_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 ( Mango )</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_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-1.9.0.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for Cordova to load
+ //
+ document.addEventListener("<a href="cordova_events_events.md.html#deviceready">deviceready</a>", onDeviceReady, false);
+
+ // Cordova is ready
+ //
+ function onDeviceReady() {
+ window.requestFileSystem(<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>
+<strong>name:</strong> The name of the file system. <em>(DOMString)</em>
+</li>
+<li>
+<strong>root:</strong> The root directory of the file system. <em>(<a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>)</em>
+</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 will be 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 which represents the root directory of the file system.</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 ( Mango )</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.requestFileSystem(<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-1.9.0.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for Cordova to load
+ //
+ document.addEventListener("<a href="cordova_events_events.md.html#deviceready">deviceready</a>", onDeviceReady, false);
+
+ // Cordova is ready
+ //
+ function onDeviceReady() {
+ window.requestFileSystem(<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>This object represents a file on a file system. It is 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>
+<strong>isFile:</strong> Always true. <em>(boolean)</em>
+</li>
+<li>
+<strong>isDirectory:</strong> Always false. <em>(boolean)</em>
+</li>
+<li>
+<strong>name:</strong> The name of the <a href="cordova_file_file.md.html#FileEntry">FileEntry</a>, excluding the path leading to it. <em>(DOMString)</em>
+</li>
+<li>
+<strong>fullPath:</strong> The full absolute path from the root to the <a href="cordova_file_file.md.html#FileEntry">FileEntry</a>. <em>(DOMString)</em>
+</li>
+</ul>
+<p>NOTE: The following attributes are defined by the W3C specification, but are <strong>not supported</strong> by Cordova:</p>
+
+<ul>
+<li>
+<strong>filesystem:</strong> The file system on which the <a href="cordova_file_file.md.html#FileEntry">FileEntry</a> 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>
+<strong>getMetadata</strong>: Look up metadata about a file.</li>
+<li>
+<strong>setMetadata</strong>: Set metadata on a file.</li>
+<li>
+<strong>moveTo</strong>: Move a file to a different location on the file system.</li>
+<li>
+<strong>copyTo</strong>: Copy a file to a different location on the file system.</li>
+<li>
+<strong>toURL</strong>: Return a URL that can be used to locate a file.</li>
+<li>
+<strong>remove</strong>: Delete a file.</li>
+<li>
+<strong>getParent</strong>: Look up the parent directory.</li>
+<li>
+<strong>createWriter</strong>: Creates a <a href="cordova_file_file.md.html#FileWriter">FileWriter</a> object that can be used to write to a file.</li>
+<li>
+<strong>file</strong>: Creates a <a href="cordova_file_file.md.html#File">File</a> object containing file properties.</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 ( Mango )</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>
+<strong>successCallback</strong> - A callback that is called with a <a href="cordova_file_file.md.html#Metadata">Metadata</a> object. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs retrieving the <a href="cordova_file_file.md.html#Metadata">Metadata</a>. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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.
+<strong>Only works on iOS currently</strong> - this will set the extended attributes of a file.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>successCallback</strong> - A callback that is called when the metadata was successfully set. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called when the metadata was not successfully set. <em>(Function)</em>
+</li>
+<li>
+<strong>metadataObject</strong> - An object that contains the metadata keys and values. <em>(Object)</em>
+</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 <strong>"com.apple.MobileBackup"</strong> extended attribute is supported. Set the value to <strong>1</strong> to NOT enable the file to be backed up by iCloud. Set the value to <strong>0</strong> to re-enable the file to be backed up by iCloud.</li>
+</ul>
+<h2>
+<a name="FileEntry_moveto">moveTo</a>
+</h2>
+
+<p>Move a file to a different location on the file system. It is an error to attempt to:</p>
+
+<ul>
+<li>move a file into its parent if a name different from its current one isn't provided;</li>
+<li>move a file to a path occupied by a directory;</li>
+</ul>
+<p>In addition, an attempt to move a file on top of an existing file must attempt to delete and replace that file.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>parent</strong> - The parent directory to which to move the file. <em>(<a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>)</em>
+</li>
+<li>
+<strong>newName</strong> - The new name of the file. Defaults to the current name if unspecified. <em>(DOMString)</em>
+</li>
+<li>
+<strong>successCallback</strong> - A callback that is called with the <a href="cordova_file_file.md.html#FileEntry">FileEntry</a> object of the new file. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs when attempting to move the file. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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. It is an error to attempt 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>
+<strong>parent</strong> - The parent directory to which to copy the file. <em>(<a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>)</em>
+</li>
+<li>
+<strong>newName</strong> - The new name of the file. Defaults to the current name if unspecified. <em>(DOMString)</em>
+</li>
+<li>
+<strong>successCallback</strong> - A callback that is called with the <a href="cordova_file_file.md.html#FileEntry">FileEntry</a> object of the new file. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs when attempting to copy the file. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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>
+<strong>successCallback</strong> - A callback that is called after the file has been deleted. Invoked with no parameters. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs when attempting to delete the file. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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 <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a> containing the file.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>successCallback</strong> - A callback that is called with the file's parent <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs when attempting to retrieve the parent <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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 <a href="cordova_file_file.md.html#FileWriter">FileWriter</a> object associated with the file that the <a href="cordova_file_file.md.html#FileEntry">FileEntry</a> represents.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>successCallback</strong> - A callback that is called with a <a href="cordova_file_file.md.html#FileWriter">FileWriter</a> object. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs while attempting to create the <a href="cordova_file_file.md.html#FileWriter">FileWriter</a>. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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 <a href="cordova_file_file.md.html#File">File</a> object that represents the current state of the file that this <a href="cordova_file_file.md.html#FileEntry">FileEntry</a> represents.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>successCallback</strong> - A callback that is called with a <a href="cordova_file_file.md.html#File">File</a> object. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs when creating the <a href="cordova_file_file.md.html#File">File</a> object (e.g. the underlying file no longer exists). Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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. It is 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="DirectoryEntry_properties">Properties</a>
+</h2>
+
+<ul>
+<li>
+<strong>isFile:</strong> Always false. <em>(boolean)</em>
+</li>
+<li>
+<strong>isDirectory:</strong> Always true. <em>(boolean)</em>
+</li>
+<li>
+<strong>name:</strong> The name of the <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>, excluding the path leading to it. <em>(DOMString)</em>
+</li>
+<li>
+<strong>fullPath:</strong> The full absolute path from the root to the <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>. <em>(DOMString)</em>
+</li>
+</ul>
+<p>NOTE: The following attributes are defined by the W3C specification, but are <strong>not supported</strong> by Cordova:</p>
+
+<ul>
+<li>
+<strong>filesystem:</strong> The file system on which the <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a> 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 <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a> object:</p>
+
+<ul>
+<li>
+<strong>getMetadata</strong>: Look up metadata about a directory.</li>
+<li>
+<strong>setMetadata</strong>: Set metadata on a directory.</li>
+<li>
+<strong>moveTo</strong>: Move a directory to a different location on the file system.</li>
+<li>
+<strong>copyTo</strong>: Copy a directory to a different location on the file system.</li>
+<li>
+<strong>toURL</strong>: Return a URL that can be used to locate a directory.</li>
+<li>
+<strong>remove</strong>: Delete a directory. The directory must be empty.</li>
+<li>
+<strong>getParent</strong>: Look up the parent directory.</li>
+<li>
+<strong>createReader</strong>: Create a new <a href="cordova_file_file.md.html#DirectoryReader">DirectoryReader</a> that can read entries from a directory.</li>
+<li>
+<strong>getDirectory</strong>: Create or look up a directory.</li>
+<li>
+<strong>getFile</strong>: Create or look up a file.</li>
+<li>
+<strong>removeRecursively</strong>: Delete a directory and all of its contents.</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 ( Mango )</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>
+<strong>successCallback</strong> - A callback that is called with a <a href="cordova_file_file.md.html#Metadata">Metadata</a> object. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs retrieving the <a href="cordova_file_file.md.html#Metadata">Metadata</a>. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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>Set metadata on a directory.
+<strong>Only works on iOS currently</strong> - this will set the extended attributes of a directory.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>successCallback</strong> - A callback that is called when the metadata was successfully set. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called when the metadata was not successfully set. <em>(Function)</em>
+</li>
+<li>
+<strong>metadataObject</strong> - An object that contains the metadata keys and values. <em>(Object)</em>
+</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 <strong>"com.apple.MobileBackup"</strong> extended attribute is supported. Set the value to <strong>1</strong> to NOT enable the directory to be backed up by iCloud. Set the value to <strong>0</strong> to re-enable the directory to be backed up by iCloud.</li>
+</ul>
+<h2>
+<a name="DirectoryEntry_moveto">moveTo</a>
+</h2>
+
+<p>Move a directory to a different location on the file system. It is an error to attempt to:</p>
+
+<ul>
+<li>move a directory inside itself or to any child at any depth;</li>
+<li>move a directory into its parent if a name different from its current one is not provided;</li>
+<li>move a directory to a path occupied by a file;</li>
+<li>move a directory to a path occupied by a directory which is not empty.</li>
+</ul>
+<p>In addition, an attempt to move a directory on top of an existing empty directory must attempt to delete and replace that directory.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>parent</strong> - The parent directory to which to move the directory. <em>(<a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>)</em>
+</li>
+<li>
+<strong>newName</strong> - The new name of the directory. Defaults to the current name if unspecified. <em>(DOMString)</em>
+</li>
+<li>
+<strong>successCallback</strong> - A callback that is called with the <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a> object of the new directory. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs when attempting to move the directory. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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. It is an error to attempt to:</p>
+
+<ul>
+<li>copy a directory inside itself at any depth;</li>
+<li>copy a directory into its parent if a name different from its current one is not provided.</li>
+</ul>
+<p>Directory copies are always recursive - that is, they copy all contents of the directory.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>parent</strong> - The parent directory to which to copy the directory. <em>(<a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>)</em>
+</li>
+<li>
+<strong>newName</strong> - The new name of the directory. Defaults to the current name if unspecified. <em>(DOMString)</em>
+</li>
+<li>
+<strong>successCallback</strong> - A callback that is called with the <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a> object of the new directory. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs when attempting to copy the underlying directory. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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. It is an error to attempt to:</p>
+
+<ul>
+<li>delete a directory that is not empty;</li>
+<li>delete the root directory of a filesystem.</li>
+</ul>
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>successCallback</strong> - A callback that is called after the directory has been deleted. Invoked with no parameters. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs when attempting to delete the directory. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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 <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a> containing the directory.</p>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>successCallback</strong> - A callback that is called with the directory's parent <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs when attempting to retrieve the parent <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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. It is an error to attempt to:</p>
+
+<ul>
+<li>create a directory whose immediate parent does not yet exist.</li>
+</ul>
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>path</strong> - The path to the directory to be looked up or created. Either an absolute path, or a relative path from this <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>. <em>(DOMString)</em>
+</li>
+<li>
+<strong>options</strong> - Options to specify whether the directory is created if it doesn't exist. <em>(<a href="cordova_file_file.md.html#Flags">Flags</a>)</em>
+</li>
+<li>
+<strong>successCallback</strong> - A callback that is invoked with a <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a> object. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs creating or looking up the directory. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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("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. It is an error to attempt to:</p>
+
+<ul>
+<li>create a file whose immediate parent does not yet exist.</li>
+</ul>
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>path</strong> - The path to the file to be looked up or created. Either an absolute path, or a relative path from this <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>. <em>(DOMString)</em>
+</li>
+<li>
+<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>
+</li>
+<li>
+<strong>successCallback</strong> - A callback that is invoked with a <a href="cordova_file_file.md.html#FileEntry">FileEntry</a> object. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs creating or looking up the file. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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 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 (e.g. trying to delete
+a directory that contains a file that cannot be removed), some of the contents of the directory may
+be deleted. It is an error to attempt to:</p>
+
+<ul>
+<li>delete the root directory of a filesystem.</li>
+</ul>
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>successCallback</strong> - A callback that is called after the <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a> has been deleted. Invoked with no parameters. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs when attempting to delete the <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a>. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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>
+
+<hr>
+<h1><a name="DirectoryReader">DirectoryReader</a></h1>
+
+<p>An object that lists files and directories in a directory. Defined in the <a class="external" href="http://www.w3.org/TR/file-system-api/">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 ( Mango )</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>
+<strong>successCallback</strong> - A callback that is passed an array of <a href="cordova_file_file.md.html#FileEntry">FileEntry</a> and <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a> objects. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs retrieving the directory listing. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</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><a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a> is an object that allows you to upload files to a server or download files from a server.</p>
+
+<h2>
+<a name="FileTransfer_properties">Properties</a>
+</h2>
+
+<p>N/A</p>
+
+<h2>
+<a name="FileTransfer_methods">Methods</a>
+</h2>
+
+<ul>
+<li>
+<strong>upload</strong>: sends a file to a server. </li>
+<li>
+<strong>download</strong>: downloads a file from server.</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 <a href="cordova_file_file.md.html#FileUploadOptions">FileUploadOptions</a> object to the upload method. On successful upload, the success callback will be called with a <a href="cordova_file_file.md.html#FileUploadResult">FileUploadResult</a> object. If an error occurs, the error callback will be invoked with a <a href="cordova_file_file.md.html#FileTransferError">FileTransferError</a> object.
+It is also possible to download a file from remote and save it on the device (only iOS and Android).</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 ( Mango )</li>
+</ul>
+<h2>
+<a name="FileTransfer_upload">upload</a>
+</h2>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>filePath</strong> - Full path of the file on the device</li>
+<li>
+<strong>server</strong> - URL of the server to receive the file</li>
+<li>
+<strong>successCallback</strong> - A callback that is called with a <a href="cordova_file_file.md.html#Metadata">Metadata</a> object. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs retrieving the <a href="cordova_file_file.md.html#Metadata">Metadata</a>. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</li>
+<li>
+<strong>options</strong> - Optional parameters such as file name and mimetype</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 = new Object();
+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, "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-1.9.0.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for Cordova to load
+ //
+ document.addEventListener("<a href="cordova_events_events.md.html#deviceready">deviceready</a>", onDeviceReady, false);
+
+ // Cordova is ready
+ //
+ 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 = new Object();
+ 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, "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>
+
+<h2>
+<a name="FileTransfer_ios_quirks">iOS Quirks</a>
+</h2>
+
+<p>Setting headers for <a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a> Upload:</p>
+
+<p><strong>Quick Example</strong></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 = "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 params = new Object();
+params.headers={'headerParam':'headerValue'};
+
+options.params = params;
+
+var ft = new <a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>();
+ft.upload(fileURI, uri, win, fail, options);
+</code></pre>
+
+<h2>
+<a name="FileTransfer_download">download</a>
+</h2>
+
+<p><strong>Parameters:</strong></p>
+
+<ul>
+<li>
+<strong>source</strong> - URL of the server to receive the file</li>
+<li>
+<strong>target</strong> - Full path of the file on the device</li>
+<li>
+<strong>successCallback</strong> - A callback that is called with a <a href="cordova_file_file.md.html#FileEntry">FileEntry</a> object. <em>(Function)</em>
+</li>
+<li>
+<strong>errorCallback</strong> - A callback that is called if an error occurs retrieving the <a href="cordova_file_file.md.html#Metadata">Metadata</a>. Invoked with a <a href="cordova_file_file.md.html#FileError">FileError</a> object. <em>(Function)</em>
+</li>
+</ul>
+<p><strong>Quick Example</strong></p>
+
+<pre class="prettyprint"><code> // !! Assumes variable url contains a valid URI to a file on a server and filePath is a valid path on the device
+
+var fileTransfer = new <a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a>();
+
+fileTransfer.download(
+ url,
+ 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);
+ }
+);
+</code></pre>
+
+<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 <a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a> objects upload method in order to specify additional parameters to the upload script.</p>
+
+<h2>
+<a name="FileUploadOptions_properties">Properties</a>
+</h2>
+
+<ul>
+<li>
+<strong>fileKey:</strong> The name of the form element. If not set defaults to "file". (DOMString)</li>
+<li>
+<strong>fileName:</strong> The file name you want the file to be saved as on the server. If not set defaults to "image.jpg". (DOMString)</li>
+<li>
+<strong>mimeType:</strong> The mime type of the data you are uploading. If not set defaults to "image/jpeg". (DOMString)</li>
+<li>
+<strong>params:</strong> A set of optional key/value pairs to be passed along in the HTTP request. (Object)</li>
+<li>
+<strong>chunkedMode:</strong> Should the data be uploaded in chunked streaming mode. If not set defaults to "true". (Boolean)</li>
+</ul>
+<h2>
+<a name="FileUploadOptions_description">Description</a>
+</h2>
+
+<p>A <code><a href="cordova_file_file.md.html#FileUploadOptions">FileUploadOptions</a></code> object can be passed to the <a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a> objects upload method in order to specify additional parameters to the upload script.</p>
+
+<h2>
+<a name="FileUploadOptions_ios_quirk">iOS Quirk</a>
+</h2>
+
+<ul>
+<li>
+<strong>chunkedMode:</strong>
+This parameter is ignored on iOS.</li>
+</ul>
+<h2>
+<a name="FileUploadOptions_wp7_quirk">WP7 Quirk</a>
+</h2>
+
+<ul>
+<li>
+<strong>chunkedMode:</strong>
+This parameter is ignored on WP7.</li>
+</ul>
+<hr>
+<h1><a name="FileUploadResult">FileUploadResult</a></h1>
+
+<p>A <code><a href="cordova_file_file.md.html#FileUploadResult">FileUploadResult</a></code> object is returned via the success callback of the <a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a> upload method.</p>
+
+<h2>
+<a name="FileUploadResult_properties">Properties</a>
+</h2>
+
+<ul>
+<li>
+<strong>bytesSent:</strong> The number of bytes sent to the server as part of the upload. (long)</li>
+<li>
+<strong>responseCode:</strong> The HTTP response code returned by the server. (long)</li>
+<li>
+<strong>response:</strong> The HTTP response returned by the server. (DOMString)</li>
+</ul>
+<h2>
+<a name="FileUploadResult_description">Description</a>
+</h2>
+
+<p>The <code><a href="cordova_file_file.md.html#FileUploadResult">FileUploadResult</a></code> object is returned via the success callback of the <a href="cordova_file_file.md.html#FileTransfer">FileTransfer</a> upload method.</p>
+
+<h2>
+<a name="FileUploadResult_ios_quirks">iOS Quirks</a>
+</h2>
+
+<ul>
+<li>iOS does not include values for responseCode nor bytesSent in the success callback <a href="cordova_file_file.md.html#FileUploadResult">FileUploadResult</a> object.</li>
+</ul>
+<hr>
+<h1><a name="Flags">Flags</a></h1>
+
+<p>This object is used to supply arguments to the <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code> <strong>getFile</strong> and <strong>getDirectory</strong> methods, which look up or create files and directories, respectively.</p>
+
+<h2>
+<a name="Flags_properties">Properties</a>
+</h2>
+
+<ul>
+<li>
+<strong>create:</strong> Used to indicate that the file or directory should be created, if it does not exist. <em>(boolean)</em>
+</li>
+<li>
+<strong>exclusive:</strong> By itself, exclusive has no effect. Used with create, it causes the file or directory creation to fail if the target path already exists. <em>(boolean)</em>
+</li>
+</ul>
+<h2>
+<a name="Flags_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 ( Mango )</li>
+</ul>
+<h2>
+<a name="Flags_quick_example">Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>// Get the data directory, creating it if it doesn't exist.
+dataDir = fileSystem.root.getDirectory("data", {create: true});
+
+// Create the lock file, if and only if it doesn't exist.
+lockFile = dataDir.getFile("lockfile.txt", {create: true, exclusive: true});
+</code></pre>
+
+<hr>
+<h1><a name="LocalFileSystem">LocalFileSystem</a></h1>
+
+<p>This object provides a way to obtain root file systems.</p>
+
+<h2>
+<a name="LocalFileSystem_methods">Methods</a>
+</h2>
+
+<ul>
+<li>
+<strong>requestFileSystem:</strong> Requests a filesystem. <em>(Function)</em>
+</li>
+<li>
+<strong>resolveLocalFileSystemURI:</strong> Retrieve a <a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a> or <a href="cordova_file_file.md.html#FileEntry">FileEntry</a> using local URI. <em>(Function)</em>
+</li>
+</ul>
+<h2>
+<a name="LocalFileSystem_constants">Constants</a>
+</h2>
+
+<ul>
+<li>
+<code><a href="cordova_file_file.md.html#LocalFileSystem">LocalFileSystem</a>.PERSISTENT</code>: Used for storage that should not be removed by the user agent without application or user permission.</li>
+<li>
+<code><a href="cordova_file_file.md.html#LocalFileSystem">LocalFileSystem</a>.TEMPORARY</code>: Used for storage with no guarantee of persistence.</li>
+</ul>
+<h2>
+<a name="LocalFileSystem_details">Details</a>
+</h2>
+
+<p>The <code><a href="cordova_file_file.md.html#LocalFileSystem">LocalFileSystem</a></code> object methods are defined on the <strong>window</strong> object.</p>
+
+<h2>
+<a name="LocalFileSystem_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 ( Mango )</li>
+</ul>
+<h2>
+<a name="LocalFileSystem_request_file_system_quick_example">Request File System Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function onSuccess(fileSystem) {
+ console.log(fileSystem.name);
+}
+
+// request the persistent file system
+window.requestFileSystem(<a href="cordova_file_file.md.html#LocalFileSystem">LocalFileSystem</a>.PERSISTENT, 0, onSuccess, onError);
+</code></pre>
+
+<h2>
+<a name="LocalFileSystem_resolve_local_file_system_uri_quick_example">Resolve Local File System URI Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function onSuccess(fileEntry) {
+ console.log(fileEntry.name);
+}
+
+window.resolveLocalFileSystemURI("file:///example.txt", onSuccess, onError);
+</code></pre>
+
+<h2>
+<a name="LocalFileSystem_full_example">Full Example</a>
+</h2>
+
+<pre class="prettyprint"><code><!DOCTYPE html>
+<html>
+ <head>
+ <title>Local <a href="cordova_file_file.md.html#File">File</a> System Example</title>
+
+ <script type="text/javascript" charset="utf-8" src="cordova-1.9.0.js"></script>
+ <script type="text/javascript" charset="utf-8">
+
+ // Wait for Cordova to load
+ //
+ document.addEventListener("<a href="cordova_events_events.md.html#deviceready">deviceready</a>", onDeviceReady, false);
+
+ // Cordova is ready
+ //
+ function onDeviceReady() {
+ window.requestFileSystem(<a href="cordova_file_file.md.html#LocalFileSystem">LocalFileSystem</a>.PERSISTENT, 0, onFileSystemSuccess, fail);
+ window.resolveLocalFileSystemURI("file:///example.txt", onResolveSuccess, fail);
+ }
+
+ function onFileSystemSuccess(fileSystem) {
+ console.log(fileSystem.name);
+ }
+
+ function onResolveSuccess(fileEntry) {
+ console.log(fileEntry.name);
+ }
+
+ function fail(evt) {
+ console.log(evt.target.error.code);
+ }
+
+ </script>
+ </head>
+ <body>
+ <h1>Example</h1>
+ <p>Local <a href="cordova_file_file.md.html#File">File</a> System</p>
+ </body>
+</html>
+</code></pre>
+
+<hr>
+<h1><a name="Metadata">Metadata</a></h1>
+
+<p>This interface supplies information about the state of a file or directory.</p>
+
+<h2>
+<a name="Metadata_properties">Properties</a>
+</h2>
+
+<ul>
+<li>
+<strong>modificationTime:</strong> This is the time at which the file or directory was last modified. <em>(Date)</em>
+</li>
+</ul>
+<h2>
+<a name="Metadata_details">Details</a>
+</h2>
+
+<p>The <code><a href="cordova_file_file.md.html#Metadata">Metadata</a></code> object represents information about the state of a file or directory. You can get an instance of a <a href="cordova_file_file.md.html#Metadata">Metadata</a> object by calling the <strong>getMetadata</strong> method of a <code><a href="cordova_file_file.md.html#DirectoryEntry">DirectoryEntry</a></code> or <code><a href="cordova_file_file.md.html#FileEntry">FileEntry</a></code> object.</p>
+
+<h2>
+<a name="Metadata_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 ( Mango )</li>
+</ul>
+<h2>
+<a name="Metadata_quick_example">Quick Example</a>
+</h2>
+
+<pre class="prettyprint"><code>function win(metadata) {
+ console.log("Last Modified: " + metadata.modificationTime);
+}
+
+// Request the metadata object for this entry
+entry.getMetadata(win, null);
+</code></pre>
+
+<hr>
+<h1><a name="FileError">FileError</a></h1>
+
+<p>A '<a href="cordova_file_file.md.html#FileError">FileError</a>' object is set when an error occurs in any of the <a href="cordova_file_file.md.html#File">File</a> API methods. </p>
+
+<h2>
+<a name="FileError_properties">Properties</a>
+</h2>
+
+<ul>
+<li>
+<strong>code:</strong> One of the predefined error codes listed below.</li>
+</ul>
+<h2>
+<a name="FileError_constants">Constants</a>
+</h2>
+
+<ul>
+<li><code><a href="cordova_file_file.md.html#FileError">FileError</a>.NOT_FOUND_ERR</code></li>
+<li><code><a href="cordova_file_file.md.html#FileError">FileError</a>.SECURITY_ERR</code></li>
+<li><code><a href="cordova_file_file.md.html#FileError">FileError</a>.ABORT_ERR</code></li>
+<li><code><a href="cordova_file_file.md.html#FileError">FileError</a>.NOT_READABLE_ERR</code></li>
+<li><code><a href="cordova_file_file.md.html#FileError">FileError</a>.ENCODING_ERR</code></li>
+<li><code><a href="cordova_file_file.md.html#FileError">FileError</a>.NO_MODIFICATION_ALLOWED_ERR</code></li>
+<li><code><a href="cordova_file_file.md.html#FileError">FileError</a>.INVALID_STATE_ERR</code></li>
+<li><code><a href="cordova_file_file.md.html#FileError">FileError</a>.SYNTAX_ERR</code></li>
+<li><code><a href="cordova_file_file.md.html#FileError">FileError</a>.INVALID_MODIFICATION_ERR</code></li>
+<li><code><a href="cordova_file_file.md.html#FileError">FileError</a>.QUOTA_EXCEEDED_ERR</code></li>
+<li><code><a href="cordova_file_file.md.html#FileError">FileError</a>.TYPE_MISMATCH_ERR</code></li>
+<li><code><a href="cordova_file_file.md.html#FileError">FileError</a>.PATH_EXISTS_ERR</code></li>
+</ul>
+<h2>
+<a name="FileError_description">Description</a>
+</h2>
+
+<p>The <code><a href="cordova_file_file.md.html#FileError">FileError</a></code> object is the only parameter of any of the <a href="cordova_file_file.md.html#File">File</a> API's error callbacks. Developers must read the code property to determine the type of error.</p>
+
+<hr>
+<h1><a name="FileTransferError">FileTransferError</a></h1>
+
+<p>A <code><a href="cordova_file_file.md.html#FileTransferError">FileTransferError</a></code> object is returned via the error callback when an error occurs.</p>
+
+<h2>
+<a name="FileTransferError_properties">Properties</a>
+</h2>
+
+<ul>
+<li>
+<strong>code</strong> One of the predefined error codes listed below. (Number)</li>
+<li>
+<strong>source</strong> URI to the source (String)</li>
+<li>
+<strong>target</strong> URI to the target (String)</li>
+<li>
+<strong>http_status</strong> HTTP status code. This attribute is only available when a response code is received from the HTTP connection. (Number)</li>
+</ul>
+<h2>
+<a name="FileTransferError_constants">Constants</a>
+</h2>
+
+<ul>
+<li><code><a href="cordova_file_file.md.html#FileTransferError">FileTransferError</a>.FILE_NOT_FOUND_ERR</code></li>
+<li><code><a href="cordova_file_file.md.html#FileTransferError">FileTransferError</a>.INVALID_URL_ERR</code></li>
+<li><code><a href="cordova_file_file.md.html#FileTransferError">FileTransferError</a>.CONNECTION_ERR</code></li>
+</ul>
+<h2>
+<a name="FileTransferError_description">Description</a>
+</h2>
+
+<p>The <code><a href="cordova_file_file.md.html#FileTransferError">FileTransferError</a></code> object is returned via the error callback when an error occurs when uploading or downloading a file.</p>
+
+ </div>
+ </div>
+
+ <!-- Functionality and Syntax Highlighting -->
+ <script type="text/javascript" src="index.js"></script><script type="text/javascript" src="prettify/prettify.js"></script>
+</body>
+</html>