CB-6022: Add backwards-compatibility notes to doc Also change "URI" and "path" references to "URL" where appropriate for consistency.
Project: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer/repo Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer/commit/31ac00d3 Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer/tree/31ac00d3 Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer/diff/31ac00d3 Branch: refs/heads/master Commit: 31ac00d3ae35f9ca280cf4e6c9edc9df23ea95b5 Parents: 9149468 Author: Ian Clelland <[email protected]> Authored: Thu Feb 13 09:49:09 2014 -0500 Committer: Ian Clelland <[email protected]> Committed: Thu Feb 13 09:49:09 2014 -0500 ---------------------------------------------------------------------- doc/index.md | 47 ++++++++++++++++++++++++++++++++++------------- 1 file changed, 34 insertions(+), 13 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/cordova-plugin-file-transfer/blob/31ac00d3/doc/index.md ---------------------------------------------------------------------- diff --git a/doc/index.md b/doc/index.md index 76a5f52..eb4db58 100644 --- a/doc/index.md +++ b/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.
