back to top

Le FileSystem API di HTML5 – Fondamenti ed interfacce coinvolte

Naturale estensione delle File APIs sono le FileSystem APIs, il cui scopo risiede nel permettere ad una Web Application di richiedere uno spazio dedicato per salvare dati, in maniera temporanea o persistente. L’accesso avviene in modalità sandboxed: l’applicazione potrà cioè accedere alla sola porzione del filesystem ad essa dedicata.

Lo user-agent dovrà chiedere all’utente il permesso per allocare spazio sul disco qualora il tipo di storage richiesto sia persistent; in entrambi i casi comunque, i dati, persistenti o temporanei, potranno sempre essere eliminati dall’utente, manualmente o tramite interfaccia fornita dallo user-agents.

L’applicazione richiede l’allocazione di spazio attraverso una chiamata al metodo requestFileSystem dell’oggetto LocalFileSystem:

Signature

interface LocalFileSystem {
    const unsigned short TEMPORARY = 0;
    const unsigned short PERSISTENT = 1;
    void requestFileSystem (unsigned short type, unsigned long long size, FileSystemCallback successCallback, optional ErrorCallback errorCallback);
    void resolveLocalFileSystemURL (DOMString url, EntryCallback successCallback, optional ErrorCallback errorCallback);
};

Il metodo requestFileSystem

type indica se la richiesta sia per il salvataggio persistente o temporaneo (PERSISTENT o TEMPORARY).

size indica lo spazio richiesto sul disco.

successCallback ed errorCallback sono le funzioni previste rispettivamente per la gestione del feedback positivo e degli errori.

Il metodo resolveLocalFileSystemURL

Il metodo permette di cercare tra le entries del filesystem un file od una directory localizzati all’url indicata.

L’interfaccia Flags permette di fornire parametri aggiuntivi ai metodi che leggono o creano files e directories:

Signature

[NoInterfaceObject]
interface Flags {
    attribute boolean create;
    attribute boolean exclusive;
};

create indica che si desidera creare un file/directory ex-novo, exclusive (in obbligatoria accoppiata con create) causa un fallimento dell’operazione nel caso in cui la risorsa già esista.

L’astrazione ruota intorna ad un oggetto FileSystem:

Signature

[NoInterfaceObject]
interface FileSystem {
    readonly attribute DOMString      name;
    readonly attribute DirectoryEntry root;
};

che prevede un name ed una cartella di root; per ogni filesystem sono previste delle entries (files o directories); in alto nella gerarchia troviamo l’interfaccia Entry:

Signature

[NoInterfaceObject]
interface Entry {
    readonly attribute boolean    isFile;
    readonly attribute boolean    isDirectory;
    void      getMetadata (MetadataCallback successCallback, optional ErrorCallback errorCallback);
    readonly attribute DOMString  name;
    readonly attribute DOMString  fullPath;
    readonly attribute FileSystem filesystem;
    void      moveTo (DirectoryEntry parent, optional DOMString newName, optional EntryCallback successCallback, optional ErrorCallback errorCallback);
    void      copyTo (DirectoryEntry parent, optional DOMString newName, optional EntryCallback successCallback, optional ErrorCallback errorCallback);
    DOMString toURL (optional DOMString mimeType);
    void      remove (VoidCallback successCallback, optional ErrorCallback errorCallback);
    void      getParent (EntryCallback successCallback, optional ErrorCallback errorCallback);
};

L’interfaccia espone una completa lista di strumenti per ottenere informazioni ed agire sul filesystem, vediamo gli attributi:

  • isFile: booleano, indica se la entry è un file.
  • isDirectory: booleano, indica se la entry è una directory
  • name
  • fullPath
  • filesystem: il filesystem cui la Entry appartiene

Vediamo ora i metodi

getMetadata (MetadataCallback successCallback, optional ErrorCallback errorCallback)

Accede ai metadata della risorsa.

moveTo (DirectoryEntry parent, optional DOMString newName, optional EntryCallback successCallback, optional ErrorCallback errorCallback)

Sposta la entry in una locazione differente (parent) del filesystem rinominandola newName, qualora un file/directory con lo stesso nome esistesse nella destinazione verrà sovrascritta.

copyTo (DirectoryEntry parent, optional DOMString newName, optional EntryCallback successCallback, optional ErrorCallback errorCallback)

Copia il file/directory dentro parent, con nuovo nome newName.

remove (VoidCallback successCallback, optional ErrorCallback errorCallback)

Elimina il file/directory. tentare di eliminare una directory vuota o la root genera un errore.

getParent (EntryCallback successCallback, optional ErrorCallback errorCallback);

Ritorna la Entry contenitore, se la Entry è la root del filesystem, torna la entry stessa.

toURL (optional DOMString mimeType)

Ritorno un URL identificativo per la entry.

Tutti i metodi ad eccezione di quest’ultimo prevedono un successCallback ed un errorCallback.

DirectoryEntry e FileEntry estendono Entry.

DirectoryEntry

Signature

[NoInterfaceObject]
interface DirectoryEntry : Entry {
    DirectoryReader createReader ();
    void            getFile (DOMString path, optional Flags options, optional EntryCallback successCallback, optional ErrorCallback errorCallback);
    void            getDirectory (DOMString path, optional Flags options, optional EntryCallback successCallback, optional ErrorCallback errorCallback);
    void            removeRecursively (VoidCallback successCallback, optional ErrorCallback errorCallback);
};

L’interfaccia espone quattro metodi:

createReader()

Crea un DirectoryReader per leggere le entries in questa directory. Le entries vengono ritornate dal metodo readEntries del reader.

getFile(DOMString path, optional Flags options, optional EntryCallback successCallback, optional ErrorCallback errorCallback)

Crea o cerca un file in path, passando opzionalmente un oggetto Flags.

getDirectory (DOMString path, optional Flags options, optional EntryCallback successCallback, optional ErrorCallback errorCallback)

Crea o cerca una directory in path, passando opzionalmente un oggetto Flags.

removeRecursively (VoidCallback successCallback, optional ErrorCallback errorCallback);

Elimina la directory e ricorsivamente il suo contenuto.

Tutti i metodi ad eccezione di createReader prevedono un successCallback ed un errorCallback.

FileEntry

Signature

[NoInterfaceObject]
interface FileEntry : Entry {
    void createWriter (FileWriterCallback successCallback, optional ErrorCallback errorCallback);
    void file (FileCallback successCallback, optional ErrorCallback errorCallback);
};

FileEntry rappresenta una entry di tipo File nel filesystem; espone due metodi:

createWriter (FileWriterCallback successCallback, optional ErrorCallback errorCallback)

Crea un nuovo FileWriter per la risorsa.

void file (FileCallback successCallback, optional ErrorCallback errorCallback)

Ritorna un oggetto File che rappresenta lo stato corrente di questa entry.

Le APIs prevedono anche una versione sincrona del meccanismo; la base è l’oggetto FileSystemSync.

Pubblicitร 

In questa guida...