Skip to content

Commit fe3d6f4

Browse files
dasergerobpaveza
authored andcommitted
Added cdvfile protocol purpose description and examples
1 parent 8cbd514 commit fe3d6f4

File tree

1 file changed

+35
-0
lines changed

1 file changed

+35
-0
lines changed

README.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -401,6 +401,41 @@ This method will now return filesystem URLs of the form
401401

402402
which can be used to identify the file uniquely.
403403

404+
## cdvfile protocol
405+
**Purpose**
406+
407+
`cdvfile://localhost/persistent|temporary|another-fs-root*/path/to/file` can be used for platform-independent file paths.
408+
cdvfile paths are supported by core plugins - for example you can download an mp3 file to cdvfile-path via `cordova-plugin-file-transfer` and play it via `cordova-plugin-media`.
409+
To use `cdvfile` as a tag' `src` you should convert it to native path via `toURL()` method of the resolved fileEntry, which you can get via `resolveLocalFileSystemURL` - see examples below.
410+
411+
__*Note__: See [Where to Store Files](#where-to-store-files), [File System Layouts](#file-system-layouts) and [Configuring the Plugin](#configuring-the-plugin-optional) for more details about available fs roots.
412+
413+
**Converting cdvfile:// to native path**
414+
415+
```javascript
416+
resolveLocalFileSystemURL('cdvfile://localhost/temporary/path/to/file.mp4', function(entry) {
417+
var nativePath = entry.toURL();
418+
console.log('Native URI: ' + nativePath);
419+
document.getElementById('video').src = nativePath;
420+
```
421+
422+
**Converting native path to cdvfile://**
423+
424+
```javascript
425+
resolveLocalFileSystemURL(nativePath, function(entry) {
426+
console.log('cdvfile URI: ' + entry.toInternalURL());
427+
```
428+
429+
**Using cdvfile in core plugins**
430+
431+
```javascript
432+
fileTransfer.download(uri, 'cdvfile://localhost/temporary/path/to/file.mp3', function (entry) { ...
433+
```
434+
```javascript
435+
var my_media = new Media('cdvfile://localhost/temporary/path/to/file.mp3', ...);
436+
my_media.play();
437+
```
438+
404439
## List of Error Codes and Meanings
405440
When an error is thrown, one of the following codes will be used.
406441

0 commit comments

Comments
 (0)