cordova-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ian Clelland <>
Subject Re: File API as implemented by cordova-plugins-file
Date Mon, 23 Jun 2014 22:04:56 GMT
On Mon, Jun 23, 2014 at 5:06 PM, Jesse <> wrote:

> I am working through numerous failing tests in the file plugin, but the
> documentation is non-existent.
> Is there some reference to this somewhere? Pointing to ever-changing
> defunct specs

I'm pretty sure that those are almost mutually exclusive ;)

> that aren't even followed makes this impossible to resolve
> without going and reading the code from other platforms. ( likely all of
> them, since it seems to be quirk-ville )

I'd like to think that the tests are more-or-less definitive, but I'm sure
there are lots of things that aren't covered, or are over-specified by the
tests. I'd be glad to sit down some day and sort out what still needs
testing, and what is just testing odd compatibility requirements or
 implementation details that needs to be split out.

> Currently the docs say:
> This plugin provides the HTML5 FileSystem API
> ( )
> which provides little if any info.

That's not a great URL to use -- The File plugin provides both the File API
(, and the (now-defunct) Directories and
System extension to it ( is the latest,
although the plugin was mostly written when was current).

It also implements the FileWriter spec (, although I often
forget that one :)

> Mozilla has done a better job of documenting some of this stuff, but not
> the cordova specific additions.
> My first implementation question:
> What is a nativeURL? It is a non-standard property that was added to Entry
> and therefore FileEntry and DirectoryEntry, but documentation makes no
> mention of it.

It is a non-standard extension, necessitated by the fact that on at least
Android and iOS, some URLs are more equal than others. Specifically, things
like <audio> and <video> tags on Android, and (I think) <link> tags on iOS,
*have* to use URLs that are understood by the WebView. Our
url-request-intercept code is never even called when the webview tries to
get those resources, and so we can't use custom URL schemes; they *need* to
be actual file:/// or equivalent URLs.

There is a .toNativeURL() method exposed on Entry for application code to
get those. It will use the .nativeURL property, if it exists, and will fall
back to the regular .toURL() code if it doesn't.

You're right that it could be better documented; one of my long-standing
to-dos is to revamp the whole of the File plugin documentation.

> It would be great if we could document FIRST when we add breaking changes
> that affect other 'less important' platforms.

I specifically tried to implement the JS side of the code for .toNativeURL
in a way that wouldn't break the platforms that I don't use (and can't
currently test on). There are multiple fallbacks in the code that should
make the JS behave correctly, even if the property hasn't been implemented.

I'm more than happy to set up a call with you, if you have more questions
about File specifically, or to work things out on the list. Just let me


> @purplecabbage

  • Unnamed multipart/alternative (inline, None, 0 bytes)
View raw message