File
Esta API te permite leer, escribir y navegar sobre el sistema de ficheros.
Objetos
- DirectoryEntry
- DirectoryReader
- File
- FileEntry
- FileError
- FileReader
- FileSystem
- FileTransfer
- FileTransferError
- FileUploadOptions
- FileUploadResult
- FileWriter
- Flags
- LocalFileSystem
- Metadata
File
Este objeto contiene atributos de un archivo o fichero en particular.
Atributos
- name: El nombre del fichero. (DOMString)
- fullPath: La ruta completa hacia el fichero, incluyendo el nombre. (DOMString)
- type: El tipo 'mime' del fichero. (DOMString)
- lastModifiedDate: La ultima fecha de modificación. (Date)
- size: El tamaño del fichero en bytes. (long)
Detalles
El objeto File
contiene atributos sobre un fichero en particular. Puedes obtener una instancia de un fichero File
, llamando al método file de un objeto FileEntry
.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
FileReader
FileReader
es un objeto que permite leer un fichero.
Atributos
- readyState: Puede tener tres estados EMPTY, LOADING o DONE.
- result: El contenido del archivo que se ha leído. (DOMString)
- error: Un objeto que contiene los errores. (FileError)
- onloadstart: Una función 'callback' que sera llamada cuando la lectura empieza. (Function)
- onprogress: Una función 'callback' que sera llamada mientras se lee el archivo, reportar progresos (progess.loaded/progress.total). (Function) -NO SOPORTADA
- onload: Una función 'callback' que sera llamada cuando la lectura finalice satisfactoriamente. (Function)
-
onabort: Una función 'callback' que sera llamada cuando se aborte el proceso de lectura. (llamando al método
abort()
). (Function) - onerror: Una función 'callback' que sera llamada cuando la lectura falla. (Function)
- onloadend: Una función 'callback' que sera llamada cuando la lectura termine (Tanto si falla o no). (Function)
Métodos
- abort: Aborta la lectura del fichero.
- readAsDataURL: Lee el fichero y devuelve los datos como una URL codificada en base64.
- readAsText: Lee el fichero como texto plano.
Detalles
El objeto FileReader
permite leer ficheros del sistema de archivos del dispositivo. Los ficheros pueden ser leídos como texto plano o codificados en base64. Los desarrolladores pueden registrar sus propias funciones a los eventos 'loadstart', 'progress', 'load', 'loadend', 'error' y 'abort'.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Leer como URL
Argumentos:
- file - El objeto File
a leer.
Ejemplo Rápido
function win(file) {
var reader = new FileReader();
reader.onloadend = function(evt) {
console.log("read success");
console.log(evt.target.result);
};
reader.readAsDataURL(file);
};
var fail = function(evt) {
console.log(error.code);
};
entry.file(win, fail);
Leer como texto
Argumentos:
- file - El objeto
File
a leer - encoding - La codificación a usar para codificar el contenido del fichero. Por defecto se usara UTF8.
Ejemplo Rápido
function win(file) {
var reader = new FileReader();
reader.onloadend = function(evt) {
console.log("read success");
console.log(evt.target.result);
};
reader.readAsText(file);
};
var fail = function(evt) {
console.log(error.code);
};
entry.file(win, fail);
Ejemplo Rápido del método 'abort'
function win(file) {
var reader = new FileReader();
reader.onloadend = function(evt) {
console.log("read success");
console.log(evt.target.result);
};
reader.readAsText(file);
reader.abort();
};
function fail(error) {
console.log(error.code);
}
entry.file(win, fail);
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de FileReader</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Espera a que phonegap se inicie
//
function onLoad() {
document.addEventListener("deviceready", onDeviceReady, false);
}
// PhoneGap esta listo
//
function onDeviceReady() {
window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, gotFS, fail);
}
function gotFS(fileSystem) {
fileSystem.root.getFile("readme.txt", {create: true}, gotFileEntry, fail);
}
function gotFileEntry(fileEntry) {
fileEntry.file(gotFile, fail);
}
function gotFile(file){
readDataUrl(file);
readAsText(file);
}
function readDataUrl(file) {
var reader = new FileReader();
reader.onloadend = function(evt) {
console.log("Read as data URL");
console.log(evt.target.result);
};
reader.readAsDataURL(file);
}
function readAsText(file) {
var reader = new FileReader();
reader.onloadend = function(evt) {
console.log("Read as text");
console.log(evt.target.result);
};
reader.readAsText(file);
}
function fail(evt) {
console.log(evt.target.error.code);
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Lectura de ficheros</p>
</body>
</html>
Peculiaridades iOS
- encoding este parámetro no esta soportado, se usara siempre UTF8.
FileWriter
FileWriter es un objeto que permite escribir en un archivo.
Atributos
- readyState: Uno de los tres estados, INIT, WRITING o DONE.
- fileName: El nombre del fichero que sera escrito. (DOMString)
- length: La longitud del archivo a ser escrito. (long)
- position: La posición actual del puntero del archivo. (long)
- error: Un objeto conteniendo errores. (FileError)
- onwritestart: Llamada cuando la escritura comienza. (Function)
- onprogress: Llamada mientras se escribe el archivo, reporta el progreso (progess.loaded/progress.total). (Function) -NO SOPORTADO
- onwrite: Llamada cuando la escritura se completo satisfactoriamente. (Function)
-
onabort: Llamada cuando la escritura sea abortada. Por ejemplo cuando se llama al método
FileWriter.abort
. (Function) - onerror: Llamada cuando la escritura falle. (Function)
- onwriteend: Llamada cuando la escritura finalice (Satisfactoriamente o no). (Function)
Métodos
- abort: Aborta el proceso de escritura.
- seek: Mueve el puntero hacia el byte especificado.
- truncate: Trunca el archivo a la longitud indicada.
- write: Escribe los datos al archivo.
Detalles
El objeto FileWriter
es una forma de escribir ficheros al sistema de archivos del dispositivo. Los desarrolladores pueden registrar sus propias funciones 'callbacks' a los eventos 'writestart', 'progress', 'write', 'writeend', 'error' y 'abort'.
Se creara un FileWriter para un solo fichero. Puedes usarlo para escribir un fichero múltiples veces. El objeto FileWriter
mantiene los atributos de posición y longitud, por lo que podrás usar FileWriter.seek
y FileWriter.write
en cualquier posición del archivo. Por defecto el objeto FileWriter
escribe al inicio del fichero (sobreescribiendo información). Indica el atributo opcional append
a true
en el constructor de FileWriter
para iniciar la escritura desde el final del archivo.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Ejemplo Rápido de Seek
function win(writer) {
// Adelanta rápidamente el puntero hacia el final del archivo
writer.seek(writer.length);
};
var fail = function(evt) {
console.log(error.code);
};
entry.createWriter(win, fail);
Ejemplo Rápido de Truncate
function win(writer) {
writer.truncate(10);
};
var fail = function(evt) {
console.log(error.code);
};
entry.createWriter(win, fail);
Ejemplo Rápido de Write
function win(writer) {
writer.onwrite = function(evt) {
console.log("Se escribió satisfactoriamente");
};
writer.write("Un texto de ejemplo");
};
var fail = function(evt) {
console.log(error.code);
};
entry.createWriter(win, fail);
Ejemplo Rápido de Append
function win(writer) {
writer.onwrite = function(evt) {
console.log("Se escribió satisfactoriamente");
};
writer.seek(writer.length);
writer.write("texto añadido");
};
var fail = function(evt) {
console.log(error.code);
};
entry.createWriter(win, fail);
Ejemplo Rápido de Abort
function win(writer) {
writer.onwrite = function(evt) {
console.log("Se escribió satisfactoriamente");
};
writer.write("Un texto de ejemplo");
writer.abort();
};
var fail = function(evt) {
console.log(error.code);
};
entry.createWriter(win, fail);
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de FileWriter</title>
<script type="text/javascript" charset="utf-8" src="phonegap.0.9.4.js"></script>
<script type="text/javascript" charset="utf-8">
// Espera a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta lista
//
function onDeviceReady() {
window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, gotFS, fail);
}
function gotFS(fileSystem) {
fileSystem.root.getFile("leeme.txt", {create: true}, gotFileEntry, fail);
}
function gotFileEntry(fileEntry) {
fileEntry.createWriter(gotFileWriter, fail);
}
function gotFileWriter(writer) {
writer.onwrite = function(evt) {
console.log("Se escribió satisfactoriamente");
};
writer.write("some sample text");
// El contenido del fichero ahora es 'some sample text'
writer.truncate(11);
// El contenido del fichero ahora es 'some sample'
writer.seek(4);
// El contenido del fichero aun es 'some sample' pero el puntero apunta después del carácter 'e' de 'some'
writer.write(" different text");
// El contenido del fichero ahora es 'some different text'
}
function fail(error) {
console.log(error.code);
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Escritura de ficheros</p>
</body>
</html>
FileSystem
Este objeto modela al sistema de archivos.
Atributos
- name: El nombre del sistema de archivos. (DOMString)
- root: El directorio raíz del sistema de archivos. (DirectoryEntry)
Detalles
El objeto FileSystem
representa toda la información del sistema de archivos. El nombre del sistema de archivos sera único entre todos los sistemas de archivos. El atributo root
contiene un objeto DirectoryEntry
que representa el directorio raíz de este sistema de archivos.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Ejemplo Rápido del Sistema de Archivos
function onSuccess(fileSystem) {
console.log(fileSystem.name);
console.log(fileSystem.root.name);
}
// Solicita el sistema de archivos persistente
window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onSuccess, null);
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de FileSystem</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Espera a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo
//
function onDeviceReady() {
window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onFileSystemSuccess, fail);
}
function onFileSystemSuccess(fileSystem) {
console.log(fileSystem.name);
console.log(fileSystem.root.name);
}
function fail(evt) {
console.log(evt.target.error.code);
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Sistema de Archivos</p>
</body>
</html>
FileEntry
Este objeto representa un fichero de su sistema de archivos. Esto esta regulado por las especificaciones W3C Directories and Systems.
Atributos
-
isFile: Siempre
true
. (boolean) -
isDirectory: Siempre
false
. (boolean) -
name: El nombre del
FileEntry
, excluyendo la ruta. (DOMString) -
fullPath: La ruta absoluta desde la raíz hacia el
FileEntry
. (DOMString)
NOTA: Los siguientes atributos están especificados por la W3C pero no están soportados por PhoneGap:
-
filesystem: El sistema de archivos al que pertenece este
FileEntry
. (FileSystem)
Métodos
- getMetadata: Busca metadatos sobre el fichero.
- moveTo: Mueve el fichero hacia otra ruta diferente en el sistema de archivos.
- copyTo: Copia el fichero hacia otra ruta diferente en el sistema de archivos.
- toURI: Retorna una URI que puede ser usada para encontrar el fichero.
- remove: Elimina el fichero.
- getParent: Busca el directorio padre.
-
createWriter: Crea un objeto
FileWriter
que puede ser usado para escribir en el fichero. -
file: Crea un objeto
File
que almacena los atributos del fichero.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
getMetadata
Busca metadatos en el fichero.
Argumentos:
-
successCallback - Una función 'callback' a la que se le pasara el objeto
Metadata
. (Function) -
errorCallback - Una función 'callback' que sera llamada si ocurre algún error obteniendo los metadatos. Se le pasara un objeto
FileError
. (Function)
Ejemplo Rápido
function success(metadata) {
console.log("Ultima modificación: " + metadata.modificationTime);
}
function fail(error) {
alert(error.code);
}
// Solicita los metadatos de este fichero
entry.getMetadata(success, fail);
moveTo
Mueve el fichero hacia una ruta diferente en el sistema de archivos. Las siguientes acciones se consideran erróneas:
- mover el fichero dentro de su mismo padre sin especificar un nombre diferente.
- mover el fichero hacia una ruta que ya esta ocupada por un directorio;
También, si intentar mover el fichero sobre otro fichero existente, se intentara eliminarlo y reemplazarlo.
Argumentos:
- parent - El directorio padre a donde mover el fichero. (DirectoryEntry)
- newName - El nuevo nombre del fichero. Si no se especifica ninguno se usara el nombre actual. (DOMString)
-
successCallback - Una función 'callback' que sera llamada con el objeto
FileEntry
del nuevo fichero. (Function) -
errorCallback - Una función 'callback' que sera llamada si ocurre algún error mientras se mueve el fichero. Se le pasa un objeto
FileError
. (Function)
Ejemplo Rápido
function success(entry) {
console.log("Nueva ruta: " + entry.fullPath);
}
function fail(error) {
alert(error.code);
}
function moveFile(entry) {
var parent = document.getElementById('parent').value,
parentEntry = new DirectoryEntry({fullPath: parent});
// mueve el fichero a un nuevo directorio y lo renombra
entry.moveTo(parentEntry, "newFile.txt", success, fail);
}
copyTo
Copia un fichero hacia una nueva ruta el sistema de archivos. Las siguientes acciones se consideran erróneas:
- copiar el fichero dentro de su mismo padre sin especificar un nombre diferente.
Argumentos:
- parent - El directorio padre a donde copiar el fichero. (DirectoryEntry)
- newName - El nuevo nombre del fichero. Se usara el mismo nombre si no se especifica ninguno. (DOMString)
- successCallback - Una función 'callback' que se llamara pasándole el FileEntry del nuevo fichero. (Function)
-
errorCallback - Una función 'callback' que se llamara si ocurre un error mientras se copiaba el fichero. Se le pasara un objeto
FileError
. (Function)
Ejemplo Rápido
function win(entry) {
console.log("Nueva ruta: " + entry.fullPath);
}
function fail(error) {
alert(error.code);
}
function copyFile(entry) {
var parent = document.getElementById('parent').value,
parentEntry = new DirectoryEntry({fullPath: parent});
// copia el fichero a un nuevo directorio y lo renombra
entry.copyTo(parentEntry, "file.copy", success, fail);
}
toURI
Retorna una URI que puede ser usada para localizar el fichero
Ejemplo Rápido
// Obtiene la URI de esta entrada
var uri = entry.toURI();
console.log(uri);
remove
Elimina el fichero.
Argumentos:
- successCallback - Una función 'callback' que se llama después de que el fichero sea eliminado. Se invoca sin argumentos. (Function)
-
errorCallback - Una función 'callback' que se llamara si ocurriera un error mientras se elimina el fichero. Se le pasara un objeto
FileError
. (Function)
Ejemplo Rápido
function success(entry) {
console.log("Eliminado satisfactoriamente");
}
function fail(error) {
alert('Error eliminando el archivo: ' + error.code);
}
// elimina el archivo
entry.remove(success, fail);
getParent
Busca el DirectoryEntry
padre que contiene al archivo.
Argumentos:
-
successCallback - Una función 'callback' que se llama pasándole el
DirectoryEntry
padre de este fichero. (Function) -
errorCallback - Una función 'callback' a la que se llamara si ocurre un error mientras se recuperaba el
DirectoryEntry
padre. Se le pasara un objetoFileError
. (Function)
Ejemplo Rápido
function success(parent) {
console.log("Nombre del padre: " + parent.name);
}
function fail(error) {
alert(error.code);
}
// Obtiene el `DirectoryEntry` padre
entry.getParent(success, fail);
createWriter
Crea un objeto FileWriter
asociado con este FileEntry
.
Argumentos:
-
successCallback - Una función 'callback' que recibirá el objeto
FileWriter
. (Function) -
errorCallback - Una función 'callback' que es llamada si ocurriera un error mientras se crea el objeto
FileWriter
. Se le pasara un objetoFileError
. (Function)
Ejemplo Rápido
function success(writer) {
writer.write("Vamos a escribir algo...");
}
function fail(error) {
alert(error.code);
}
// crea un objeto `FileWriter` para escribir en el archivo
entry.createWriter(success, fail);
file
Retorna un objeto File
que modela el estado actual del fichero asociado a este FileEntry
.
Argumentos:
-
successCallback - Una función 'callback' a la que se le pasa el objeto
File
. (Function) -
errorCallback - Una función 'callback' que sera llamada si ocurre algún error cuando creemos el objeto
File
(Ejemplo: El archivo ya no existe). Se le pasara como argumento un objetoFileError
. (Function)
Ejemplo Rápido
function success(file) {
console.log("Tamaño del archivo: " + file.size);
}
function fail(error) {
alert("No se pudo obtener las propiedades del fichero: " + error.code);
}
// obtiene las propiedades del fichero
entry.file(success, fail);
DirectoryEntry
Este objeto modela un directorio en el sistema de archivos. Esta API esta regulada por la especificación W3C Directories and Systems.
Atributos
-
isFile: Siempre
false
. (boolean) -
isDirectory: Siempre
true
. (boolean) -
name: El nombre del
DirectoryEntry
, Excluyendo la ruta. (DOMString) -
fullPath: La ruta absoluta desde la raíz hacia el objeto
DirectoryEntry
. (DOMString)
NOTA: Los siguientes atributos están definidos en las especificaciones W3C pero no están soportados por PhoneGap:
-
filesystem: El sistema de archivos donde reside este
DirectoryEntry
. (FileSystem)
Métodos
Los siguientes métodos pueden ser llamados en un objeto DirectoryEntry
:
- getMetadata: Busca metadatos sobre el directorio.
- moveTo: Mueve un directorio hacia otro destino dentro del sistema de archivos.
- copyTo: Copia el directorio hacia otro destino dentro del sistema de archivos.
- toURI: Retorna una URI que puede usarse para localizar el directorio.
- remove: Elimina el directorio, previamente debe estar vacio.
- getParent: Busca el padre del directorio.
-
createReader: Crea un nuevo objeto
DirectoryReader
que puede leer entradas de un directorio. - getDirectory: Crea o busca un directorio.
- getFile: Crea o busca un fichero.
- removeRecursively: Elimina el directorio y todo su contenido.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
getMetadata
Busca metadatos sobre el directorio.
Argumentos:
-
successCallback - Una función 'callback' a la que se le pasara el objeto
Metadata
. (Function) -
errorCallback - Una función 'callback' que sera llamada si algo falla mientras se obtienen los metadatos. Se le pasara un objeto
FileError
. (Function)
Ejemplo Rápido
function success(metadata) {
console.log("Ultima modificación: " + metadata.modificationTime);
}
function fail(error) {
alert(error.code);
}
// Solicita el objeto Metadata de esta entrada
entry.getMetadata(success, fail);
moveTo
Mueve un directorio a un sitio diferente en el sistema de archivos. Las siguientes acciones se consideran erróneas:
- mover un directorio dentro de si mismo o a cualquier hijo descendiente;
- mover un directorio dentro de su mismo padre sin especificar un nombre diferente.
- mover un directorio hacia una ruta actualmente ocupada por un fichero;
- mover un directorio hacia una ruta ocupada por un directorio que no este vacio.
Además, al mover un directorio sobre otro directorio vacio, se intentara eliminarlo y reemplazarlo.
Argumentos:
- parent - El directorio padre al que mover el directorio. (DirectoryEntry)
- newName - El nuevo nombre del directorio. Si no se especifica ninguno, se usara el mismo por defecto. (DOMString)
-
successCallback - Una función 'callback' que sera llamada pasándole el objeto
DirectoryEntry
del nuevo directorio. (Function) -
errorCallback - Una función 'callback' que sera llamada si ocurre algún error mientras se intentaba mover el directorio. Se le pasara un objeto
FileError
. (Function)
Ejemplo Rápido
function success(entry) {
console.log("Nueva ruta: " + entry.fullPath);
}
function fail(error) {
alert(error.code);
}
function moveDir(entry) {
var parent = document.getElementById('parent').value,
newName = document.getElementById('newName').value,
parentEntry = new DirectoryEntry({fullPath: parent});
// moverá este directorio hacia un nuevo directorio y luego lo renombrara
entry.moveTo(parentEntry, newName, success, fail);
}
copyTo
Copia un directorio hacia otro diferente en el sistema de archivos. Las siguientes acciones se consideran erróneas:
- copiar un directorio dentro de si mismo a cualquier nivel descendiente;
- copiar un directorio dentro de su mismo padre sin especificar un nombre diferente.
Las copias de directorios son siempre recursivas, esto quiere decir que se copia todo el contenido del directorio.
Argumentos:
- parent - El directorio padre a donde copiar el directorio. (DirectoryEntry)
- newName - El nuevo nombre del directorio. Si no se especifica ninguno, se usara el mismo nombre por defecto. (DOMString)
- successCallback - Una función 'callback' que se disparara pasándole el objeto 'DirectoryEntry' del nuevo directorio. (Function)
-
errorCallback - Una función 'callback' que sera llamada si ocurre algún error mientras se copia el directorio. Se le pasara un objeto
FileError
como argumento. (Function)
Ejemplo Rápido
function win(entry) {
console.log("Nueva ruta: " + entry.fullPath);
}
function fail(error) {
alert(error.code);
}
function copyDir(entry) {
var parent = document.getElementById('parent').value,
newName = document.getElementById('newName').value,
parentEntry = new DirectoryEntry({fullPath: parent});
// moverá este directorio hacia un nuevo directorio y lo renombrara
entry.copyTo(parentEntry, newName, success, fail);
}
toURI
Retorna una URI que podrá ser usada para localizar el directorio.
Ejemplo Rápido
// Obtiene la URI de este directorio
var uri = entry.toURI();
console.log(uri);
remove
Elimina el directorio. Las siguientes acciones se consideran erróneas:
- eliminar un directorio que no esta vacio;
- eliminar el directorio raíz del sistema de archivos.
Argumentos:
- successCallback - Una función 'callback' que sera llamada después de que el directorio sea eliminado. Sera invocada sin parámetros. (Function)
-
errorCallback - Una función 'callback' que sera llamada si ocurre algún error mientras se elimina el directorio. Se le pasara un objeto
FileError
. (Function)
Ejemplo Rápido
function success(entry) {
console.log("Eliminado satisfactoriamente");
}
function fail(error) {
alert('Hubo un error eliminando el directorio: ' + error.code);
}
// elimina el directorio
entry.remove(success, fail);
getParent
Busca el DirectoryEntry
padre que contiene al directorio.
Argumentos:
-
successCallback - Una función 'callback' que sera llamada pasándole el objeto
DirectoryEntry
padre. (Function) -
errorCallback - Una función 'callback' que sera llamada si ocurre algún error mientras se obtiene el padre. Se pasara un objeto
FileError
. (Function)
Ejemplo Rápido
function success(parent) {
console.log("Nombre del padre: " + parent.name);
}
function fail(error) {
alert('Ocurrió un error obteniendo el padre: ' + error.code);
}
// Obtiene el DirectoryEntry padre
entry.getParent(success, fail);
createReader
Crea un nuevo objeto DirectoryReader
para leer las entradas en un directorio.
Ejemplo Rápido
// crea un lector de directorios
var directoryReader = entry.createReader();
getDirectory
Crea o busca un directorio existente. Es un error el intentar:
- crear un directorio que todavía no tenga un padre.
Argumentos:
-
path - la ruta del directorio donde mirar o crearlo. Una ruta absoluta o una relativa de este
DirectoryEntry
. (DOMString) - options - Opciones para indicar si se debería crear cuando no exista ninguno. (Flags)
-
successCallback - Una función 'callback' que sera llamada con el objeto
DirectoryEntry
object. (Function) -
errorCallback - Una función 'callback' que se llamara si ocurre algún error creando o buscando el directorio. Se le pasara un objeto
FileError
. (Function)
Ejemplo Rápido
function success(parent) {
console.log("Nombre del padre: " + parent.name);
}
function fail(error) {
alert("No se pudo crear el nuevo directorio: " + error.code);
}
// Retorna un directorio existe, o lo crea si no existiera
entry.getDirectory("newDir", {create: true, exclusive: false}, success, fail);
getFile
Crea o busca un fichero. Es un error el intentar:
- crear un fichero que todavía no tiene un padre.
Argumentos:
-
path - La ruta hacia el fichero donde buscarlo o crearlo. Una ruta absoluta o una relativa hacia este objeto
DirectoryEntry
. (DOMString) - options - Opciones para indicar si se debería crear cuando no exista ninguno. (Flags)
-
successCallback - Una función 'callback' que sera llamada con el objeto
FileEntry
object. (Function) -
errorCallback - Una función 'callback' que se llamara si ocurre algún error creando o buscando el fichero. Se le pasara un objeto
FileError
. (Function)
Ejemplo Rápido
function success(parent) {
console.log("Nombre del padre: " + parent.name);
}
function fail(error) {
alert("Ocurrió un error recuperando el fichero: " + error.code);
}
// Retorna un fichero existe, o lo crea si no existiera
entry.getFile("newFile.txt", {create: true, exclusive: false}, success, fail);
removeRecursively
Elimina un directorio y todo su contenido, si durante el proceso algún fichero no puede ser eliminado y se dispara el evento errorCallback
, lo mas seguro es que parte del contenido ya halla sido eliminado.
Las siguientes acciones se consideran erróneas:
- eliminar el directorio raíz del sistema de fichero.
Argumentos:
-
successCallback - Una función 'callback' que es llamada después de que
DirectoryEntry
sea eliminado. Se invocara sin parámetros. (Function) -
errorCallback - Una función 'callback' que se llamara si ocurriera un error al eliminar el
DirectoryEntry
. Se le pasara un objetoFileError
. (Function)
Ejemplo Rápido
function success(parent) {
console.log("Eliminación recursiva terminada");
}
function fail(error) {
alert("Ocurrió un error al eliminar el directorio y su contenido: " + error.code);
}
// elimina el directorio y todo su contenido
entry.removeRecursively(success, fail);
DirectoryReader
Un objeto que enumera los ficheros y directorios existentes dentro de un directorio. Esta API esta definida por las especificaciones W3C Directories and Systems.
Métodos
- readEntries: Lee entradas en un directorio.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
readEntries
Lee las entradas de este directorio
Argumentos:
-
successCallback - Una función 'callback' a la que se le pasara un array de objetos
FileEntry
yDirectoryEntry
. (Function) -
errorCallback - Una función 'callback' que se llamara si ocurre algún error obteniendo el listado. Se le pasara un objeto
FileError
. (Function)
Ejemplo Rápido
function success(entries) {
var i;
for (i=0; i<entries.length; i++) {
console.log(entries[i].name);
}
}
function fail(error) {
alert("Ocurrió un error mientras se obtenía la lista: " + error.code);
}
// Obtiene un lector de directorio
var directoryReader = dirEntry.createReader();
// Obtiene la lista de todas las entradas de este directorio
directoryReader.readEntries(success,fail);
FileTransfer
FileTransfer es un objeto que permite subir archivos a un servidor.
Atributos
N/A
Métodos
- upload: envía ficheros a un servidor.
Detalles
El objeto FileTransfer
proporciona una forma de subir archivos a un servidor remoto usando una petición HTTP POST de varias partes. Están soportados los protocolos HTTP y HTTPS. Se pueden especificar parámetros opcionales pasándole al método FileTranfer.upload
un objeto FileUploadOptions
. Tras una subida satisfactoria, se llamara a la función 'success' y se le pasara como argumento el objeto FileUploadResult
. Si ocurre un error, se llamara a la función 'error', y se le pasara un objeto FileTransferError
.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Ejemplo Rápido
// !! Se asume que la variable fileURI contiene un URI válido a un archivo de texto en el dispositivo
var win = function(r) {
console.log("Código = " + r.responseCode);
console.log("Respuesta = " + r.response);
console.log("Enviado = " + r.bytesSent);
}
var fail = function(error) {
alert("Ocurrió un error: Código = " = error.code);
}
var options = new FileUploadOptions();
options.fileKey="file";
options.fileName=fileURI.substr(fileURI.lastIndexOf('/')+1);
options.mimeType="text/plain";
var params = new Object();
params.value1 = "test";
params.value2 = "param";
options.params = params;
var ft = new FileTransfer();
ft.upload(fileURI, "http://ejemplo.servidor.com/upload.php", win, fail, options);
Ejemplo Completo
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>Ejemplo de FileTransfer</title>
<script type="text/javascript" charset="utf-8" src="phonegap.0.9.4.min.js"></script>
<script type="text/javascript" charset="utf-8">
// Espera a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta lista
//
function onDeviceReady() {
// Retorna la ruta hacia el archivo de imagen
navigator.camera.getPicture(uploadPhoto,
function(message) { alert('Fallo obteniendo imagen'); },
{ quality: 50,
destinationType: navigator.camera.DestinationType.FILE_URI,
sourceType: navigator.camera.PictureSourceType.PHOTOLIBRARY }
);
}
function uploadPhoto(imageURI) {
var options = new FileUploadOptions();
options.fileKey="file";
options.fileName=imageURI.substr(imageURI.lastIndexOf('/')+1);
options.mimeType="image/jpeg";
var params = new Object();
params.value1 = "test";
params.value2 = "param";
options.params = params;
var ft = new FileTransfer();
ft.upload(imageURI, "http://ejemplo.servidor.com/upload.php", win, fail, options);
}
function win(r) {
console.log("Código = " + r.responseCode);
console.log("Respuesta = " + r.response);
console.log("Enviados = " + r.bytesSent);
}
function fail(error) {
alert("Ocurrió un error: Código = " = error.code);
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Subida de Fichero</p>
</body>
</html>
FileUploadOptions
Puede pasarse un objeto FileUploadOptions
al método FileTransfer.upload
para indicar parámetros adicionales a la hora de subir el archivo.
Atributos
- fileKey: El nombre del formulario (Elemento form). Se usara "file" por defecto. (DOMString)
- fileName: El nombre del fichero que desea guardar en el servidor. Se usara "image.jpg" por defecto. (DOMString)
- mimeType: El tipo 'mime' del fichero que estas subiendo. Se usara "image/jpeg" por defecto. (DOMString)
- params: Un juego de llaves/valores que se pasara junto a la petición HTTP. (Object)
Descripción
Puede pasarle un objeto FileUploadOptions
al método FileTranfer.upload
para indicar parámetros adicionales a la hora de subir el archivo.
FileUploadResult
El objeto FileUploadResult
se obtiene por medio de la función 'callback' 'success' del método FileTransfer.upload
.
Atributos
- bytesSent: El numero de bytes que se transfirió al servidor como parte de la subida. (long)
- responseCode: El código HTTP de respuesta retornado por el servidor. (long)
- response: La respuesta retornada por el servidor. (DOMString)
Descripción
El objeto FileUploadResult
se obtiene por medio de la función 'callback' 'success' del método FileTransfer.upload
.
Peculiaridades iOS
- iOS no incluye valores para
responseCode
nibytesSent
en el objetoFileUploadResult
.
Flags
Este objeto se usa para pasarle argumentos a los métodos getFile y getDirectory de DirectoryEntry
, que busca o crea ficheros y directorios.
Atributos
-
create: Usado para indicar que el fichero o el directorio deberá ser creado, si no existiera. Por defecto se usara
false
. (boolean) -
exclusive: Por si mismo,
exclusive
no tiene ningún efecto. Usado junto acreate
, causa que la creación del fichero o del directorio falle si la ruta ya esta usada. Se usarafalse
por defecto. (boolean)
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Ejemplo Rápido
// Obtiene el directorio, creándolo si no existiera.
dataDir = fileSystem.root.getDirectory("data", {create: true});
// Crea el fichero (Si no existiera).
lockFile = dataDir.getFile("lockfile.txt", {create: true, exclusive: true});
LocalFileSystem
Este objeto proporciona la forma de obtener la raíz del sistema de archivos.
Métodos
- requestFileSystem: Solicita un sistema de archivos. (Function)
-
resolveLocalFileSystemURI: Recupera un
DirectoryEntry
o unFileEntry
usando una URI local. (Function)
Constantes
-
LocalFileSystem.PERSISTENT
: Usada para el almacenamiento que no debería ser eliminado sin solicitud o permiso del usuario. -
LocalFileSystem.TEMPORARY
: Usado para el almacenamiento sin garantía de persistencia.
Detalles
El objeto LocalFileSystem
esta definido en el objeto window.
Plataformas Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Ejemplo Rápido de Petición del Sistema de Archivos
function onSuccess(fileSystem) {
console.log(fileSystem.name);
}
// Solicita el sistema de archivos persistente
window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onSuccess, onError);
Ejemplo Rápido de Resolución URI
function onSuccess(fileEntry) {
console.log(fileEntry.name);
}
window.resolveLocalFileSystemURI("file:///ejemplo.txt", onSuccess, onError);
Ejemplo Completo
<!DOCTYPE html>
<html>
<head>
<title>Ejemplo de LocalFileSystem</title>
<script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
<script type="text/javascript" charset="utf-8">
// Espere a que PhoneGap se inicie
//
document.addEventListener("deviceready", onDeviceReady, false);
// PhoneGap esta listo
//
function onDeviceReady() {
window.requestFileSystem(LocalFileSystem.PERSISTENT, 0, onFileSystemSuccess, fail);
window.resolveLocalFileSystemURI("file:///ejemplo.txt", onResolveSuccess, fail);
}
function onFileSystemSuccess(fileSystem) {
console.log(fileSystem.name);
}
function onResolveSuccess(fileEntry) {
console.log(fileEntry.name);
}
function fail(evt) {
console.log(evt.target.error.code);
}
</script>
</head>
<body>
<h1>Ejemplo</h1>
<p>Sistema de Archivos Local</p>
</body>
</html>
Metadata
Esta interfaz proporciona información acerca de los estados de un fichero o directorio.
Atributos
- modificationTime: La ultima vez que fue modificado este directorio o fichero. (Date)
Detalles
El objeto Metadata
proporciona toda la información sobre el estado de un fichero o directorio. Puedes obtener una instancia del objeto Metadata llamando a los métodos DirectoryEntry.getMetadata
y FileEntry.getMetadata
.
Plataforma Soportadas
- Android
- BlackBerry WebWorks (OS 5.0 y superior)
- iOS
Ejemplo Rápido
function win(metadata) {
console.log("Ultima modificación: " + metadata.modificationTime);
}
// Solicita el objeto metadata de esta entrada
entry.getMetadata(win, null);
FileError
Un objeto FileError
sera creado cada vez que ocurra un error en cualquier método de la API File.
Atributos
- code: Uno de los errores predefinidos en la lista inferior.
Constantes
FileError.NOT_FOUND_ERR
FileError.SECURITY_ERR
FileError.ABORT_ERR
FileError.NOT_READABLE_ERR
FileError.ENCODING_ERR
FileError.NO_MODIFICATION_ALLOWED_ERR
FileError.INVALID_STATE_ERR
FileError.SYNTAX_ERR
FileError.INVALID_MODIFICATION_ERR
FileError.QUOTA_EXCEEDED_ERR
FileError.TYPE_MISMATCH_ERR
FileError.PATH_EXISTS_ERR
Descripción
El objeto FileError
es el único parámetro que tienen las funciones 'callbacks' de error en la API File. Los desarrolladores deberían consultar el atributo code
para determinar que tipo de error es.
FileTransferError
El objeto FileTransferError
se obtiene por medio de las funciones 'callback' de errores.
Atributos
- code: Uno de los errores definidos en la lista inferior. (int)
Constantes
FileTransferError.FILE_NOT_FOUND_ERR
FileTransferError.INVALID_URL_ERR
FileTransferError.CONNECTION_ERR
Descripción
El objeto FileTransferError
se obtiene por medio de las funciones 'callbacks' de errores cuando falla la subida.