goober-ionic/plugins/cordova-plugin-file/doc/plugins.md

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 fileURL = resourceApi.remapUri(Uri.parse(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));
}