Cleaned up code, commented, preparing for HTTPS via CordovaHTTP

1 files changed, 323 insertions, 0 deletions

diff --git a/plugins/org.apache.cordova.file/docs/fileentry/fileentry.md b/plugins/org.apache.cordova.file/docs/fileentry/fileentry.md
new file mode 100644
index 00000000..f362833c
--- /dev/null
+++ b/plugins/org.apache.cordova.file/docs/fileentry/fileentry.md
@@ -0,0 +1,323 @@
+---
+license: Licensed to the Apache Software Foundation (ASF) under one
+         or more contributor license agreements.  See the NOTICE file
+         distributed with this work for additional information
+         regarding copyright ownership.  The ASF licenses this file
+         to you under the Apache License, Version 2.0 (the
+         "License"); you may not use this file except in compliance
+         with the License.  You may obtain a copy of the License at
+
+           http://www.apache.org/licenses/LICENSE-2.0
+
+         Unless required by applicable law or agreed to in writing,
+         software distributed under the License is distributed on an
+         "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+         KIND, either express or implied.  See the License for the
+         specific language governing permissions and limitations
+         under the License.
+---
+
+FileEntry
+==========
+
+Represents a file on a file system, as defined in the
+[W3C Directories and Systems](http://www.w3.org/TR/file-system-api/)
+specification.
+
+Properties
+----------
+
+- __isFile__: Always true. _(boolean)_
+- __isDirectory__: Always false. _(boolean)_
+- __name__: The name of the `FileEntry`, excluding the path leading to it. _(DOMString)_
+- __fullPath__: The full absolute path from the root to the `FileEntry`. _(DOMString)_
+
+__NOTE:__ The following attribute is defined by the W3C specification,
+but is _not_ supported:
+
+- __filesystem__: The file system on which the `FileEntry` resides. _(FileSystem)_
+
+Methods
+-------
+
+- __getMetadata__: Look up metadata about a file.
+- __setMetadata__: Set metadata on a file.
+- __moveTo__: Move a file to a different location on the file system.
+- __copyTo__: Copy a file to a different location on the file system.
+- __toURL__: Return a URL that can be used to locate a file.
+- __remove__: Delete a file.
+- __getParent__: Look up the parent directory.
+- __createWriter__: Creates a `FileWriter` object that can be used to write to a file.
+- __file__: Creates a `File` object containing file properties.
+
+Supported Platforms
+-------------------
+
+- Android
+- BlackBerry WebWorks (OS 5.0 and higher)
+- iOS
+- Windows Phone 7 and 8
+- Windows 8
+
+getMetadata
+----------------
+
+Look up metadata about a file.
+
+__Parameters:__
+
+- __successCallback__: A callback that is passed a `Metadata` object. _(Function)_
+- __errorCallback__: A callback that executes if an error occurs when retrieving the `Metadata`. Invoked with a `FileError` object. _(Function)_
+
+__Quick Example__
+
+    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);
+
+setMetadata
+----------------
+
+Set metadata on a file.
+
+__Currently works only on iOS.__
+- this will set the extended attributes of a file.
+
+__Parameters:__
+
+- __successCallback__: A callback that executes when the metadata is set. _(Function)_
+- __errorCallback__: A callback that executes when the metadata is not successfully set. _(Function)_
+- __metadataObject__: An object that contains the metadata's keys and values. _(Object)_
+
+__Quick Example__
+
+    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});
+
+__iOS Quirk__
+
+- Only the `com.apple.MobileBackup` extended attribute is supported. Set the value to `1` to prevent the file from being backed up to iCloud. Set the value to `0` to re-enable the file to be backed up to iCloud.
+
+__Quick Example__
+
+    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.requestFileSystem(localFileSystem, 0, onFSWin, onFSFail);
+    }
+
+        setFileMetadata(LocalFileSystem.PERSISTENT, "Backups/sqlite.db", "com.apple.MobileBackup", 1);
+
+moveTo
+------
+
+Move a file to a different location on the file system. An error
+results if the app attempts to:
+
+- move a file into its parent if a name different from its current one isn't provided;
+- move a file to a path occupied by a directory;
+
+In addition, moving a file on top of an existing file attempts to
+delete and replace that file.
+
+__Parameters:__
+
+- __parent__: The parent directory to which to move the file. _(DirectoryEntry)_
+- __newName__: The new name of the file. Defaults to the current name if unspecified. _(DOMString)_
+- __successCallback__: A callback that is passed the new files `FileEntry` object. _(Function)_
+- __errorCallback__: A callback that executes if an error occurs when attempting to move the file.  Invoked with a `FileError` object. _(Function)_
+
+__Quick Example__
+
+    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 DirectoryEntry(parentName, parent);
+
+        // move the file to a new directory and rename it
+        entry.moveTo(parentEntry, "newFile.txt", success, fail);
+    }
+
+copyTo
+------
+
+Copy a file to a new location on the file system.  An error results if
+the app attempts to:
+
+- copy a file into its parent if a name different from its current one is not provided.
+
+__Parameters:__
+
+- __parent__: The parent directory to which to copy the file. _(DirectoryEntry)_
+- __newName__: The new name of the file. Defaults to the current name if unspecified. _(DOMString)_
+- __successCallback__: A callback that is passed the new file's `FileEntry` object. _(Function)_
+- __errorCallback__: A callback that executes if an error occurs when attempting to copy the file.  Invoked with a `FileError` object. _(Function)_
+
+__Quick Example__
+
+    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 DirectoryEntry(parentName, parent);
+
+        // copy the file to a new directory and rename it
+        entry.copyTo(parentEntry, "file.copy", success, fail);
+    }
+
+toURL
+-----
+
+Returns a URL that can be used to locate the file.
+
+__Quick Example__
+
+    // Request the URL for this entry
+    var fileURL = entry.toURL();
+    console.log(fileURL);
+
+remove
+------
+
+Deletes a file.
+
+__Parameters:__
+
+- __successCallback__: A callback that executes after the file has been deleted.  Invoked with no parameters. _(Function)_
+- __errorCallback__: A callback that executes if an error occurs when attempting to delete the file.  Invoked with a `FileError` object. _(Function)_
+
+__Quick Example__
+
+    function success(entry) {
+        console.log("Removal succeeded");
+    }
+
+    function fail(error) {
+        alert('Error removing file: ' + error.code);
+    }
+
+    // remove the file
+    entry.remove(success, fail);
+
+getParent
+---------
+
+Look up the parent `DirectoryEntry` containing the file.
+
+__Parameters:__
+
+- __successCallback__: A callback that is passed the file's parent `DirectoryEntry`. _(Function)_
+- __errorCallback__: A callback that executes if an error occurs when attempting to retrieve the parent `DirectoryEntry`.  Invoked with a `FileError` object. _(Function)_
+
+__Quick Example__
+
+    function success(parent) {
+        console.log("Parent Name: " + parent.name);
+    }
+
+    function fail(error) {
+        alert(error.code);
+    }
+
+    // Get the parent DirectoryEntry
+    entry.getParent(success, fail);
+
+createWriter
+------------
+
+Create a `FileWriter` object associated with the file represented by the `FileEntry`.
+
+__Parameters:__
+
+- __successCallback__: A callback that is passed a `FileWriter` object. _(Function)_
+- __errorCallback__: A callback that executes if an error occurs while attempting to create the FileWriter.  Invoked with a `FileError` object. _(Function)_
+
+__Quick Example__
+
+    function success(writer) {
+        writer.write("Some text to the file");
+    }
+
+    function fail(error) {
+        alert(error.code);
+    }
+
+    // create a FileWriter to write to the file
+    entry.createWriter(success, fail);
+
+file
+----
+
+Return a `File` object that represents the current state of the file
+that this `FileEntry` represents.
+
+__Parameters:__
+
+- __successCallback__: A callback that is passed a `File` object. _(Function)_
+- __errorCallback__: A callback that executes if an error occurs when creating the `File` object, such as when the file no longer exists.  Invoked with a `FileError` object. _(Function)_
+
+__Quick Example__
+
+    function success(file) {
+        console.log("File size: " + file.size);
+    }
+
+    function fail(error) {
+        alert("Unable to retrieve file properties: " + error.code);
+    }
+
+    // obtain properties of a file
+    entry.file(success, fail);