Plugin File - CGastrell/phonegap GitHub Wiki

Referencias:

File Plugin

Este plugin implementa una File API basada, entre otras, en las especificaciones de HTML5 File API. Tambien implementa una interfaz de FileWriter.

En breve: permite leer y escribir archivos al dispositivo

No tan breve: por las medidas de seguridad y las especificaciones mencionadas, es uno de los plugins mas complejos de implementar.

File API: uso basico

La File API tiene un esquema asincronico de funcionamiento. Esto es, ninguno (o casi ninguno) de sus metodos nos devolvera un archivo o puntero, todo sera a traves de callbacks.

La File API cuenta con objetos para referenciar cada uno de los items que concierne al sistema de archivos. Cada objeto tendra metodos para acceder a sus descendientes a traves de llamadas asincronicas. Es esta metodologia la que hace complejo implementar un lector/escritor de archivos.

Los objetos mas relevantes son:

FileSystem
DirectoryEntry
FileEntry
File
FileReader
FileWriter

Jerarquicamente, esto se ve asi:

window.requestFileSystemURL(LocalFileSystem.PERSISTENT, 0, onFileSystemSuccess, onFail);

function onFileSystemSuccess(fileSystem) {
  //obtenemos el fileSystem
  fileSystem.getDirectory('./files', function(directoryEntry) {
    //obtenemos el directorio
    directoryEntry.getFile('test.txt', function(fileEntry) {
      //obtenemos el archivo
      fileEntry.file(function(fileObject) {
        //una vez que tenemos el archivo en un objeto
        var reader = new FileReader();
        reader.onloadend = function() {
          //mostramos el contenido (si es texto)
          console.log(this.result);
        }
        reader.readAsText(fileObject);
      });
    });
  });
}

function onFail(error) {
  console.log(error)
}

Constantes

El File Plugin provee una serie de metodos y constantes. Las constantes son referencias a distintos esquemas de sistemas de archivos.

cordova.file.applicationDirectory
cordova.file.applicationStorageDirectory
cordova.file.dataDirectory
cordova.file.cacheDirectory
cordova.file.externalApplicationStorageDirectory
cordova.file.externalDataDirectory
cordova.file.externalCacheDirectory
cordova.file.externalRootDirectory
cordova.file.tempDirectory
cordova.file.syncedDataDirectory
cordova.file.documentsDirectory

Estas constantes existen para cubrir las posibilidades segun el sistema de archivos de la plataforma. Estas constantes corresponden, segun la plataforma, a estas rutas del sistema de archivos:

iOS

Device Path	`cordova.file.*`	`iosExtraFileSystems`	r/w?	persistent?	OS clears	sync	private
`/var/mobile/Applications/<UUID>/`	applicationStorageDirectory	-	r	N/A	N/A	N/A	Yes
`appname.app/`	applicationDirectory	bundle	r	N/A	N/A	N/A	Yes
`www/`	-	-	r	N/A	N/A	N/A	Yes
`Documents/`	documentsDirectory	documents	r/w	Yes	No	Yes	Yes
`NoCloud/`	-	documents-nosync	r/w	Yes	No	No	Yes
`Library`	-	library	r/w	Yes	No	Yes?	Yes
`NoCloud/`	dataDirectory	library-nosync	r/w	Yes	No	No	Yes
`Cloud/`	syncedDataDirectory	-	r/w	Yes	No	Yes	Yes
`Caches/`	cacheDirectory	cache	r/w	Yes*	Yes***	No	Yes
`tmp/`	tempDirectory	-	r/w	No**	Yes***	No	Yes

Android:

Device Path	`cordova.file.*`	`AndroidExtraFileSystems`	r/w?	persistent?	OS clears	private
`file:///android_asset/`	applicationDirectory		r	N/A	N/A	Yes
`/data/data/<app-id>/`	applicationStorageDirectory	-	r/w	N/A	N/A	Yes
`cache`	cacheDirectory	cache	r/w	Yes	Yes*	Yes
`files`	dataDirectory	files	r/w	Yes	No	Yes
`Documents`		documents	r/w	Yes	No	Yes
`<sdcard>/`	externalRootDirectory	sdcard	r/w	Yes	No	No
`Android/data/<app-id>/`	externalApplicationStorageDirectory	-	r/w	Yes	No	No
`cache`	externalCacheDirectry	cache-external	r/w	Yes	No**	No
`files`	externalDataDirectory	files-external	r/w	Yes	No	No

Codigos de error

Cuando exista un error, se ejecutara la funcion que hayamos provisto como Error Handler y esta recibira alguno de estos codigos:

Cod.	Constante
1	`NOT_FOUND_ERR`
2	`SECURITY_ERR`
3	`ABORT_ERR`
4	`NOT_READABLE_ERR`
5	`ENCODING_ERR`
6	`NO_MODIFICATION_ALLOWED_ERR`
7	`INVALID_STATE_ERR`
8	`SYNTAX_ERR`
9	`INVALID_MODIFICATION_ERR`
10	`QUOTA_EXCEEDED_ERR`
11	`TYPE_MISMATCH_ERR`
12	`PATH_EXISTS_ERR`