Cordova - FileSystem - why so many path alternatives?

Question

I am just looking through the Cordova source code to try and figure something out, and there are currently six alternate methods/properties to access the path of a file.

Currently (running using iOS), there is:

// Properties
file.fullPath; // file:///full/path/syntax/file
file.nativeURL; // file:///full/path/syntax/file

// Method(s)
file.toInternalURL(); // formats the file.fullPath into a cdvfile://localhost/persisten/file.
file.toURL(); // if file.nativeURL is set, uses file.nativeURL, otherwise use file.toInternalURL() or file.fullPath.

// Deprecated method(s)
file.toURI(); // deprecated - calls file.toURL();
file.toNativeURL() // deprecated - calls file.toURL();

I understand two are deprecated - which both point to file.toURL() - so I can ignore them and focus on just four methods.

But what is the difference between file.fullPath and file.nativeURL - they are exactly the same? They are both properties on the file object - both publicly accessible.

As far as I can tell, file.toURL() uses both of these - first file.nativeURL if not that, then file.toInternalURL() or failing that, then file.fullPath.

Then finally, file.toNativeURL() returns a cdvfile:// formatted location.

So, most methods point to the file.nativeURL property. Is file.toURL() the method to use since it handles all instances? If so, then what on earth is cdvfile://?

Thanks

Answer 1

file.fullPath is a part of the spec, and should actually look like: /path/relative/to/my/root. If you're seeing that it has file:///, then that's a bug.

file.nativeURL is meant to be an implementation detail. But sadly, it's not obviously marked as such. It's not a part of the spec, and doesn't exist on other platforms.

file.toURL() is likely what you want. It's a part of the spec, gives you a URL that can be passed to resolveLocalFileSystemURL, and has fewer gotchas compared to cdvfile: URLs.

file.toInternalURL() is not a part of the spec, but it a Cordova-specific extension. I don't think it would ever be a useful thing to use.