1<!---
  2    Licensed to the Apache Software Foundation (ASF) under one
  3    or more contributor license agreements.  See the NOTICE file
  4    distributed with this work for additional information
  5    regarding copyright ownership.  The ASF licenses this file
  6    to you under the Apache License, Version 2.0 (the
  7    "License"); you may not use this file except in compliance
  8    with the License.  You may obtain a copy of the License at
  9
 10      http://www.apache.org/licenses/LICENSE-2.0
 11
 12    Unless required by applicable law or agreed to in writing,
 13    software distributed under the License is distributed on an
 14    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 15    KIND, either express or implied.  See the License for the
 16    specific language governing permissions and limitations
 17    under the License.
 18-->
 19
 20Notes for plugin developers
 21===========================
 22
 23These notes are primarily intended for Android and iOS developers who want to write plugins which interface with the file system using the File plugin.
 24
 25Working with Cordova file system URLs
 26-------------------------------------
 27
 28Since 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. 
 29
 30On 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.
 31
 32### Converting cdvfile:// URLs to fileystem paths
 33
 34Plugins 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.
 35
 36It 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.
 37
 38#### Android
 39
 40On 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:
 41
 42    // webView is a member of the Plugin class
 43    CordovaResourceApi resourceApi = webView.getResourceApi();
 44
 45    // Obtain a file:/// URL representing this file on the device,
 46    // or the same URL unchanged if it cannot be mapped to a file
 47    Uri fileURL = resourceApi.remapUri(Uri.parse(cdvfileURL));
 48
 49It is also possible to use the File plugin directly:
 50
 51    import org.apache.cordova.file.FileUtils;
 52    import org.apache.cordova.file.FileSystem;
 53    import java.net.MalformedURLException;
 54
 55    // Get the File plugin from the plugin manager
 56    FileUtils filePlugin = (FileUtils)webView.pluginManager.getPlugin("File");
 57
 58    // Given a URL, get a path for it
 59    try {
 60        String path = filePlugin.filesystemPathForURL(cdvfileURL);
 61    } catch (MalformedURLException e) {
 62        // The filesystem url wasn't recognized
 63    }
 64
 65To convert from a path to a `cdvfile://` URL:
 66
 67    import org.apache.cordova.file.LocalFilesystemURL;
 68
 69    // Get a LocalFilesystemURL object for a device path,
 70    // or null if it cannot be represented as a cdvfile URL.
 71    LocalFilesystemURL url = filePlugin.filesystemURLforLocalPath(path);
 72    // Get the string representation of the URL object
 73    String cdvfileURL = url.toString();
 74
 75If your plugin creates a file, and you want to return a FileEntry object for it, use the File plugin:
 76
 77    // Return a JSON structure suitable for returning to JavaScript,
 78    // or null if this file is not representable as a cdvfile URL.
 79    JSONObject entry = filePlugin.getEntryForFile(file);
 80
 81#### iOS
 82
 83Cordova 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.
 84
 85    // Get a CDVFilesystem URL object from a URL string
 86    CDVFilesystemURL* url = [CDVFilesystemURL fileSystemURLWithString:cdvfileURL];
 87    // Get a path for the URL object, or nil if it cannot be mapped to a file
 88    NSString* path = [filePlugin filesystemPathForURL:url];
 89    
 90
 91    // Get a CDVFilesystem URL object for a device path, or
 92    // nil if it cannot be represented as a cdvfile URL.
 93    CDVFilesystemURL* url = [filePlugin fileSystemURLforLocalPath:path];
 94    // Get the string representation of the URL object
 95    NSString* cdvfileURL = [url absoluteString];
 96
 97If your plugin creates a file, and you want to return a FileEntry object for it, use the File plugin:
 98
 99    // Get a CDVFilesystem URL object for a device path, or
100    // nil if it cannot be represented as a cdvfile URL.
101    CDVFilesystemURL* url = [filePlugin fileSystemURLforLocalPath:path];
102    // Get a structure to return to JavaScript
103    NSDictionary* entry = [filePlugin makeEntryForLocalURL:url]
104
105#### JavaScript
106
107In JavaScript, to get a `cdvfile://` URL from a FileEntry or DirectoryEntry object, simply call `.toURL()` on it:
108
109    var cdvfileURL = entry.toURL();
110
111In 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:
112
113    // create appropriate Entry object
114    var entry;
115    if (entryStruct.isDirectory) {
116        entry = new DirectoryEntry(entryStruct.name, entryStruct.fullPath, new FileSystem(entryStruct.filesystemName));
117    } else {
118        entry = new FileEntry(entryStruct.name, entryStruct.fullPath, new FileSystem(entryStruct.filesystemName));
119    }
120