CB-6022: Add backwards-compatibility notes to doc

Also change "URI" and "path" references to "URL" where appropriate for consistency.

doc/index.md

@@ -58,7 +58,7 @@ multi-part POST request, and to download files as well.
 
 __Parameters__:
 
-- __filePath__: Full path of the file on the device.
+- __fileURL__: Filesystem URL representing the file on the device. For backwards compatibility, this can also be the full path of the file on the device. (See [Backwards Compatibility Notes] below)
 
 - __server__: URL of the server to receive the file, as encoded by `encodeURI()`.
 
@@ -78,7 +78,8 @@ __Parameters__:
 
 ### Example
 
-    // !! Assumes variable fileURI contains a valid URI to a text file on the device
+    // !! Assumes variable fileURL contains a valid URL to a text file on the device,
+    //    for example, cdvfile://localhost/persistent/path/to/file.txt
 
     var win = function (r) {
         console.log("Code = " + r.responseCode);
@@ -94,7 +95,7 @@ __Parameters__:
 
     var options = new FileUploadOptions();
     options.fileKey = "file";
-    options.fileName = fileURI.substr(fileURI.lastIndexOf('/') + 1);
+    options.fileName = fileURL.substr(fileURL.lastIndexOf('/') + 1);
     options.mimeType = "text/plain";
 
     var params = {};
@@ -104,7 +105,7 @@ __Parameters__:
     options.params = params;
 
     var ft = new FileTransfer();
-    ft.upload(fileURI, encodeURI("http://some.server.com/upload.php"), win, fail, options);
+    ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail, options);
 
 ### Example with Upload Headers and Progress Events (Android and iOS only)
 
@@ -124,7 +125,7 @@ __Parameters__:
 
     var options = new FileUploadOptions();
     options.fileKey="file";
-    options.fileName=fileURI.substr(fileURI.lastIndexOf('/')+1);
+    options.fileName=fileURL.substr(fileURL.lastIndexOf('/')+1);
     options.mimeType="text/plain";
 
     var headers={'headerParam':'headerValue'};
@@ -139,7 +140,7 @@ __Parameters__:
           loadingStatus.increment();
         }
     };
-    ft.upload(fileURI, uri, win, fail, options);
+    ft.upload(fileURL, uri, win, fail, options);
 
 ## FileUploadResult
 
@@ -168,7 +169,7 @@ __Parameters__:
 
 - __source__: URL of the server to download the file, as encoded by `encodeURI()`.
 
-- __target__: Full path of the file on the device.
+- __target__: Filesystem url representing the file on the device. For backwards compatibility, this can also be the full path of the file on the device. (See [Backwards Compatibility Notes] below)
 
 - __successCallback__: A callback that is passed  a `FileEntry` object. _(Function)_
 
@@ -180,14 +181,15 @@ __Parameters__:
 
 ### Example
 
-    // !! Assumes filePath is a valid path on the device
+    // !! Assumes variable fileURL contains a valid URL to a path on the device,
+    //    for example, cdvfile://localhost/persistent/path/to/downloads/
 
     var fileTransfer = new FileTransfer();
     var uri = encodeURI("http://some.server.com/download.php");
 
     fileTransfer.download(
         uri,
-        filePath,
+        fileURL,
         function(entry) {
             console.log("download complete: " + entry.fullPath);
         },
@@ -210,7 +212,8 @@ Aborts an in-progress transfer. The onerror callback is passed a FileTransferErr
 
 ### Example
 
-    // !! Assumes variable fileURI contains a valid URI to a text file on the device
+    // !! Assumes variable fileURL contains a valid URL to a text file on the device,
+    //    for example, cdvfile://localhost/persistent/path/to/file.txt
 
     var win = function(r) {
         console.log("Should not be called.");
@@ -229,7 +232,7 @@ Aborts an in-progress transfer. The onerror callback is passed a FileTransferErr
     options.mimeType="image/jpeg";
 
     var ft = new FileTransfer();
-    ft.upload(fileURI, encodeURI("http://some.server.com/upload.php"), win, fail, options);
+    ft.upload(fileURL, encodeURI("http://some.server.com/upload.php"), win, fail, options);
     ft.abort();
 
 
@@ -241,9 +244,9 @@ A `FileTransferError` object is passed to an error callback when an error occurs
 
 - __code__: One of the predefined error codes listed below. (Number)
 
-- __source__: URI to the source. (String)
+- __source__: URL to the source. (String)
 
-- __target__: URI to the target. (String)
+- __target__: URL to the target. (String)
 
 - __http_status__: HTTP status code.  This attribute is only available when a response code is received from the HTTP connection. (Number)
 
@@ -254,3 +257,21 @@ A `FileTransferError` object is passed to an error callback when an error occurs
 - `FileTransferError.CONNECTION_ERR`
 - `FileTransferError.ABORT_ERR`
 
+## Backwards Compatibility Notes
+
+Previous versions of this plugin would only accept device-absolute-file-paths as the source for uploads, or as the target for downloads. These paths would typically be of the form
+
+    /var/mobile/Applications/<application UUID>/Documents/path/to/file  (iOS)
+    /storage/emulated/0/path/to/file                                    (Android)
+
+For backwards compatibility, these paths are still accepted, and if your application has recorded paths like these in persistent storage, then they can continue to be used.
+
+These paths were previously exposed in the `fullPath` property of `FileEntry` and `DirectoryEntry` objects returned by the File plugin. New versions of the File plugin, however, no longer expose these paths to JavaScript.
+
+If you are upgrading to a new (1.0.0 or newer) version of File, and you have previously been using `entry.fullPath` as arguments to `download()` or `upload()`, then you will need to change your code to use filesystem URLs instead.
+
+`FileEntry.toURL()` and `DirectoryEntry.toURL()` return a filesystem URL of the form
+
+    cdvfile://localhost/persistent/path/to/file
+
+which can be used in place of the absolute file path in both `download()` and `upload()` methods.