File API, accesso al file system

L'accesso al file system locale di un dispositivo è realizzato in Apache Cordova tramite un'implementazione delle specifiche W3C File API. Per avere accesso all'intero file system possiamo utilizzare il metodo requestFileSystem() come mostrato nel seguente esempio:

window.requestFileSystem(
		LocalFileSystem.PERSISTENT,
		0,
		function(fileSystem) {
			alert("File system: " + fileSystem.name + "\n" +
			      "Root: " + fileSystem.root.name + "\n");
		},
		function(event) {
			alert(event.target.error.code);
		}
);

Tramite requestFileSystem() possiamo specificare il tipo di file system a cui vogliamo accedere. Nell'esempio abbiamo specificato che vogliamo accedere al file system di tipo persistente; in alternativa possiamo chiedere l'accesso ad un file system temporaneo specificando la costante LocalFileSystem.TEMPORARY.

L'oggetto passato alla funzione di callback eseguita in caso di successo prevede due proprietà: name, che rappresenta il nome del file system, e root, che è costituita da un oggetto di tipo DirectoryEntry.

Avendo accesso alla root del file system possiamo navigare nella sua struttura per accedere a file e sottocartelle.

In alternativa possiamo accedere direttamente ad un elemento del file system tramite un URI utilizzando il metodo resolveLocalFileSystemURI():

window.resolveLocalFileSystemURI(
		"file:///myfolder/myfile.txt",
		function(fileEntry) {
			// ...
		},
		function(event) {
			alert(event.target.error.code);
		}
);

In questo caso alla funzione di callback viene passato un oggetto di tipo FileEntry (o DirectoryEntry nel caso l'URI si riferisca ad una cartella) tramite il quale abbiamo accesso all'elemento del file system sottostante.

Gli oggetti FileEntry e DirectoryEntry mettono a disposizione proprietà e metodi per gestire ed effettuare le più comuni operazioni su file e cartelle. Ad esempio, per copiare un file in una diversa posizione possiamo utilizzare il metodo copyTo(), come mostrato dal seguente codice:

fileEntry.copyTo(
		directoryEntry,
		"Copy of myFile.txt",
		function() {
			// successo ...
		},
		function() {
			// fallimento ...
		}
);

Il metodo prende un oggetto directoryEntry che rappresenta la cartella di destinazione, il nome da assegnare al file copiato e le solite due funzioni di callback per gestire il successo o il fallimento dell'operazione.

Altri metodi consentono l'eliminazione (remove()), lo spostamento (moveTo()), l'accesso alle metainformazioni (getMetadata()) ed altro ancora.

Abbiamo inoltre a disposizione altri tipi di oggetto che ci consentono di gestire i contenuti di cartelle e file. Per le cartelle abbiamo DirectoryReader che con il suo metodo readEntries() ci consente di accedere a file e sottocartelle di una directoryEntry:

var dirReader = directoryEntry.createReader();
dirReader.readEntries(
	function(entries) {
		var i;
		var typeDescription = "File: ";
		for (i=0; i<entries.length; i++) {
			if (entries[i].isDirectory) typeDescription = "Directory: ";
			console.log(typeDescription + entries[i].name);
		}
	},
	function(error) {
		alert("Errore: " + error.code);
	}
);

Nell'esempio, dopo avere creato l'oggetto DirectoryReader a partire da una DirectoryEntry abbiamo invocato readEntries() specificando le callback di successo e fallimento. Nel primo caso scorriamo l'elenco delle entries visualizzando il tipo di entry seguito dal relativo nome.

Per creare un file possiamo far ricorso al metodo getFile() di una directoryEntry:

directoryEntry.getFile("nuovoFile.txt", { create: true }, success, failure );

Se il nome specificato come primo argomento esiste, alla callback di successo verrà passato il fileEntry corrispondente, altrimenti viene prima creato un nuovo file con il nome specificato.

Per scrivere del testo all'interno del file utilizzeremo quindi l'oggetto FileWriter:

function success(fileEntry) {
	fileEntry.createWriter(
		function(writer) {
			writer.write("Testo di prova");
		},
		function(error) {
			alert("Errore: " + error.code);
		}
	);
}

Nell'esempio abbiamo creato un FileWriter a partire dal fileEntry specificando le callback che gestiranno l'esito dell'operazione. In caso di corretta creazione del FileWriter utilizziamo il suo metodo write() per scrivere del testo all'interno.

Analogamente, per leggere il contenuto di un file possiamo utilizzare l'oggetto FileReader:

function success(fileEntry) {
	fileEntry.file(
		function(file) {
			var reader = new FileReader();
			reader.onloadend = getFileContent;
			reader.readAsText(file);
		},
		function(error) {
			alert("Errore: " + error.code);
		}
	);
}

Come possiamo vedere l'approccio è leggermente diverso dalla scrittura. In questo caso, sempre a partire dal fileEntry, utilizziamo il metodo file() che ci consente di ottenere un oggetto di tipo File tramite una opportuna funzione di callback. Creiamo quindi un FileReader e associamo una funzione di callback (getFileContent()) all'evento di avvenuto caricamento del contenuto del file (onloadend). Avviamo quindi la lettura del file tramite il metodo readAsText() specificando come parametro il file stesso.

Se tutto va come previsto, la funzione di callback getFileContent() sarà in grado di accedere al contenuto del file:

function getFileContent(event) {
	alert("Contenuto del file: " + event.target.result);
}

Il supporto per la gestione del file system è molto ricco e prevede diverse opzioni. Ad esempio include il supporto per l'upload dei file che abbiamo già avuto modo di esplorare. Per avere maggiori dettagli e quindi di una visione più completa delle possibilità offerte da Cordova è opportuno consultare la documentazione ufficiale.