cordova-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From i..@apache.org
Subject [3/3] git commit: CB-6057: Add notes for plugin authors about dealing with cdvfile:// URLs
Date Thu, 20 Feb 2014 15:48:11 GMT
CB-6057: Add notes for plugin authors about dealing with cdvfile:// URLs


Project: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file/repo
Commit: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file/commit/a1ab728b
Tree: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file/tree/a1ab728b
Diff: http://git-wip-us.apache.org/repos/asf/cordova-plugin-file/diff/a1ab728b

Branch: refs/heads/dev
Commit: a1ab728bf9f7a2f485c32f821032dc58ca39198e
Parents: a81b3f4
Author: Ian Clelland <iclelland@chromium.org>
Authored: Thu Feb 20 10:05:02 2014 -0500
Committer: Ian Clelland <iclelland@chromium.org>
Committed: Thu Feb 20 10:47:42 2014 -0500

----------------------------------------------------------------------
 doc/plugins.md | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 104 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/cordova-plugin-file/blob/a1ab728b/doc/plugins.md
----------------------------------------------------------------------
diff --git a/doc/plugins.md b/doc/plugins.md
new file mode 100644
index 0000000..f697b7e
--- /dev/null
+++ b/doc/plugins.md
@@ -0,0 +1,104 @@
+Notes for plugin developers
+===========================
+
+These notes are primarily intended for Android and iOS developers who want to write plugins
which interface with the file system using the File plugin.
+
+Working with Cordova file system URLs
+-------------------------------------
+
+Since version 1.0.0, this plugin has used URLs with a `cdvfile` scheme for all communication
over the bridge, rather than exposing raw device file system paths to JavaScript. 
+
+On the JavaScript side, this means that FileEntry and DirectoryEntry objects have a fullPath
attribute which is relative to the root of the HTML file system. If your plugin's JavaScript
API accepts a FileEntry or DirectoryEntry object, you should call `.toURL()` on that object
before passing it across the bridge to native code.
+
+### Converting cdvfile:// URLs to fileystem paths
+
+Plugins which need to write to the filesystem may want to convert a received file system
URL to an actual filesystem location. There are multiple ways of doing this, depending on
the native platform.
+
+It is important to remember that not all `cdvfile://` URLs are mappable to real files on
the device. Some URLs can refer to assets on device which are not represented by files, or
can even refer to remote resources. Because of these possibilities, plugins should always
test whether they get a meaningful result back when trying to convert URLs to paths.
+
+#### Android
+
+On Android, the simplest method to convert a `cdvfile://` URL to a filesystem path is to
use `org.apache.cordova.CordovaResourceApi`. `CordovaResourceApi` has several methods which
can handle `cdvfile://` URLs:
+
+    // webView is a member of the Plugin class
+    CordovaResourceApi resourceApi = webView.getResourceApi();
+
+    // Obtain a file:/// URL representing this file on the device,
+    // or the same URL unchanged if it cannot be mapped to a file
+    URI fileURI = resourceApi.remapUri(cdvfileURL);
+
+    // Obtain a File object, or null if the file cannot be mapped
+    File deviceFile = resourceApi.mapUriToFile(cdvfileURL);
+
+It is also possible to use the File plugin directly:
+
+    import org.apache.cordova.file.FileUtils;
+    import org.apache.cordova.file.FileSystem;
+    import java.net.MalformedURLException;
+
+    // Get the File plugin from the plugin manager
+    FileUtils filePlugin = (FileUtils)webView.pluginManager.getPlugin("File");
+
+    // Given a URL, get a path for it
+    try {
+        String path = filePlugin.filesystemPathForURL(cdvfileURL);
+    } catch (MalformedURLException e) {
+        // The filesystem url wasn't recognized
+    }
+
+To convert from a path to a `cdvfile://` URL:
+
+    import org.apache.cordova.file.LocalFilesystemURL;
+
+    // Get a LocalFilesystemURL object for a device path,
+    // or null if it cannot be represented as a cdvfile URL.
+    LocalFilesystemURL url = filePlugin.filesystemURLforLocalPath(path);
+    // Get the string representation of the URL object
+    String cdvfileURL = url.toString();
+
+If your plugin creates a file, and you want to return a FileEntry object for it, use the
File plugin:
+
+    // Return a JSON structure suitable for returning to JavaScript,
+    // or null if this file is not representable as a cdvfile URL.
+    JSONObject entry = filePlugin.getEntryForFile(file);
+
+#### iOS
+
+Cordova on iOS does not use the same `CordovaResourceApi` concept as Android. On iOS, you
should use the File plugin to convert between URLs and filesystem paths.
+
+    // Get a CDVFilesystem URL object from a URL string
+    CDVFilesystemURL* url = [CDVFilesystemURL fileSystemURLWithString:cdvfileURL];
+    // Get a path for the URL object, or nil if it cannot be mapped to a file
+    NSString* path = [filePlugin filesystemPathForURL:url];
+    
+
+    // Get a CDVFilesystem URL object for a device path, or
+    // nil if it cannot be represented as a cdvfile URL.
+    CDVFilesystemURL* url = [filePlugin fileSystemURLforLocalPath:path];
+    // Get the string representation of the URL object
+    NSString* cdvfileURL = [url absoluteString];
+
+If your plugin creates a file, and you want to return a FileEntry object for it, use the
File plugin:
+
+    // Get a CDVFilesystem URL object for a device path, or
+    // nil if it cannot be represented as a cdvfile URL.
+    CDVFilesystemURL* url = [filePlugin fileSystemURLforLocalPath:path];
+    // Get a structure to return to JavaScript
+    NSDictionary* entry = [filePlugin makeEntryForLocalURL:url]
+
+#### JavaScript
+
+In JavaScript, to get a `cdvfile://` URL from a FileEntry or DirectoryEntry object, simply
call `.toURL()` on it:
+
+    var cdvfileURL = entry.toURL();
+
+In plugin response handlers, to convert from a returned FileEntry structure to an actual
Entry object, your handler code should import the File plugin and create a new object:
+
+    // create appropriate Entry object
+    var entry;
+    if (entryStruct.isDirectory) {
+        entry = new DirectoryEntry(entryStruct.name, entryStruct.fullPath, new FileSystem(entryStruct.filesystemName));
+    } else {
+        entry = new FileEntry(entryStruct.name, entryStruct.fullPath, new FileSystem(entryStruct.filesystemName));
+    }
+


Mime
View raw message