mozilla
Os seus resultados da pesquisa

    Device Storage API

    Non-standard
    This feature is non-standard and is not on a standards track. Do not use it on production sites facing the Web: it will not work for every user. There may also be large incompatibilities between implementations and the behavior may change in the future.

    This API is available on Firefox OS for privileged or certified applications only.

    Sumário

    O Device Storage API é utilizado para acessar o sistema via Web app. Como acessar arquivos do sistema é algo sensível, e por está razão que API só libera o acesso a leitura.

    Nota: Acessar o storage do device é um pouco lento devido a limitação do nível físico. Em muitos casos pode ser mais rápido usar uma base de dados IndexedDB em vez de armazenar os arquivos no storage do device.

    Acessando um storage

    Ponto de entrada

    É possível ter acesso a uma área de storage utilizando o método, navigator.getDeviceStorage(). Este método aceita uma string como parâmetro que representa o nome do storage que você quer acessar. O método retorna um objeto DeviceStorage que é utilizaod para ter acesso a leitura da área do storage.

    Firefox OS fornece as seguintes áreas de storage:

    • apps: Esta área de storage é reponsável por armazenar os apps. Como este dado é crítico, requer um previlégio extra, que só está disponível somente para apps certificadas.
    • music: Esta área de storage é responsável por armazenar as música e sons.
    • pictures: Esta área de storage é resposável por armazenas as imagens.
    • sdcard: Esta área de storage é responsável por dar acesso ao SDCard do device.
    • videos: Esta área de storage é responsável por armazenar os vídeos.
    var pics = navigator.getDeviceStorage('pictures');

    Para ser capaz de utilizar cada uma dessas áreas de storage, a app precisa solicitar no seu manifesto a permissão. Como examplo, se app precisa ter acesso a área de storage  sdcard, é necessário declarar a seguinte linha "device-storage:sdcard" para slolicitar a permissão, detro do arquivo de manifesto, conforme exemplo abaixo.

    "permissions": {
      "device-storage:videos":{ "access": "readonly" },
      "device-storage:pictures":{ "access": "readwrite" }
    }

    Utilizando um storage

    Depois que uma app tem acesso a uma área de storage, ela pode adicionar, pegar e remover arquivos desta área.

    Adicionar um arquivo

    Para adicionar um arquivo utilizamos os seguintes métodos addNamed ou add. O primeiro método permite definir o nome do arquivo que está sendo adicionado e o segundo método gera o nome de forma automatica. Ambos os métodos são assíncronos e retorna um objeto DOMRequest para controlar o success ou error da operação. Isto é muito importânte para acompanhar o processo de leitura e escrita de arquivos.

    Aqueles dois métodos espera um Blob como o seu primeiro parametro. Este objeto será transformado em um arquivo e armazenado em background. Quando criar o objeto Blob, é obrigado dar um type. Este type, que é o type mime, é importânte porque algumas áreas storage tem base restrição o type:

    • music só aceita Blob como um tipo mime de audio válido
    • pictures só aceita Blob como um tipo mime de image válido
    • videos só aceita Blob como um tipo mime de vídeo válido
    var sdcard = navigator.getDeviceStorage("sdcard");
    var file   = new Blob(["This is a text file."], {type: "text/plain"});
    
    var request = sdcard.addNamed(file, "my-file.txt");
    
    request.onsuccess = function () {
      var name = this.result;
      console.log('File "' + name + '" successfully wrote on the sdcard storage area');
    }
    
    // An error typically occur if a file with the same name already exist
    request.onerror = function () {
      console.warn('Unable to write the file: ' + this.error);
    }
    

    Nota: Repositória em uma área de storage são implícitos. Repository in a storage area are implicit. Não é possível criar explicidamente um repositório vazio.  Se você  Se você precisar de uma estrutura de repositório é necessário ter um arquivo armazenado. Então se você precisa armazenar um arquivo bar dentro do repositório foo, você tem que usar o método addNamed  com o caminho compreto para o arquivo addNamed(blob, "foo/bar"). Isto também é utilzado quando você precisa recuperar um arquivo utilizando seu nome (veja abaixo).

    Como os arquivos são adicionados dentro de uma área de storage retrita, por razões de securança, o caminho do arquivo não pode começar com "/" ou "../" (e "./" é inútil).

    Download de um arquivo

    Download de um arquivo pode ser feito de duas maneira: usando seu nome ou por interação em uma lista inteira.

    A maneira mais fácil de recuperar um arquivo é utiliznado o nome do arquivo nos métodos get e getEditable. O primeiro método retorna um objeto File (que age só como uma leitura de arquivo) e o segundo retorna o objeto FileHandle object (que permite alterar o arquivo base). Os dois métodos são assíncronos e returna um objeto DOMRequest para manipular caso tenha success ou error.

    var sdcard = navigator.getDeviceStorage('sdcard');
    
    var request = sdcard.get("my-file.txt");
    
    request.onsuccess = function () {
      var file = this.result;
      console.log("Get the file: " + file.name);
    }
    
    request.onerror = function () {
      console.warn("Unable to get the file: " + this.error);
    }
    

    A outra maneira de recuperar arquivos é navegando pelo conteúdo da área de storage. Temos dois métodos enumerate eenumerateEditable. O retorno do primeiro método é os objetos File o segunto método retorna os objetos FileHandle . Ambos métodos são assíncrono e retorna um objeto DOMCursor para iterar ao longo da lista de arquivos. Um DOMCursor é nada menos que um DOMRequest com uma função a mais para interar de forma assíncrona ao longo de uma lista de coisas (arquivos nesse caso).

    var pics = navigator.getDeviceStorage('pictures');
    
    // Let's browse all the images available
    var cursor = pics.enumerate();
    
    cursor.onsuccess = function () {
      var file = this.result;
      console.log("File found: " + file.name);
    
      // Once we found a file we check if there is other results
      if (!this.done) {
        // Then we move to the next result, which call the cursor
        // success with the next file as result.
        this.continue();
      }
    }
    
    cursor.onerror = function () {
      console.warn("No file found: " + this.error);
    }
    

    É possível para limitar o número de resultados, passando dois parâmetros opcionais para os métodos enumerate e enumerateEditable.

    O primeiro parâmetro pode ser uma string, que representa uma sub pasta para uma busca interna.

    O segundo parâmetro pode ser um objeto com uma propriedade since, que permite liberar a pesquisa por um determinado período de tempo.

    var pics = navigator.getDeviceStorage('pictures');
    
    // Lets retrieve picture from the last week.
    var param = {
      since: new Date((+new Date()) - 7*24*60*60*1000)
    }
    
    var cursor = pics.enumerate(param);
    
    cursor.onsuccess = function () {
      var file = this.result;
      console.log("Picture taken on: " + file.lastModifiedDate);
    
      if (!this.done) {
        this.continue();
      }
    }
    

    Deletar um arquivo

    Um arquivo pode ser removido a partir da sua área de storage, simplismente utilizando o método delete. Este método só precisa do nome para deletar o arquivo. Como todos os outros métodos da interface DeviceStorage, este também é assíncrono e retorna um objeto DOMRequest para manipular os status de success ou error.

    var sdcard = navigator.getDeviceStorage('sdcard');
    
    var request = sdcard.delete("my-file.txt");
    
    request.onsuccess = function () {
      console.log("File deleted");
    }
    
    request.onerror = function () {
      console.log("Unable to delete the file: " + this.error);
    }
    

    Informação do Storage

    Além de acessar os arquivos, a área de storage fornece alguns métodos para ler facilmente algumas informações importantes.

    Estaço Livre

    Uma das mais umportantes informações para saber sobre o storage, é a quantidade de espaço livre para armazenamento. A interface DeviceStorage fornece duas funções úteis dedicada ao espaço de armazenamento:

    • freeSpace() para pegar a quantidade de espaço livre disponível para armazenar novos arquivos;
    • usedSpace() para pegar a quantidade de espaço usado pelos arquivos armazenados;

    Como os dois métodos são assíncronos, eles retornam um objeto DOMRequest para tratar os status de success ou error.

    var videos = navigator.getDeviceStorage('videos');
    
    var request = videos.usedSpace();
    
    request.onsuccess = function () {
      // The result is express in bytes, lets turn it into megabytes
      var size = this.result / 1048576;
      console.log("The videos on your device use a total of " + size.toFixed(2) + "Mo of space.");
    }
    
    request.onerror = function () {
      console.warn("Unable to get the space used by videos: " + this.error);
    }
    

    Ouvindo alterações

    Como muitas aplicações pode usar uma mesma área de storage ao mesmo tempo, por este motivo é muito útil para aplicação estar ciente de uma alteração em uma área de storage. É também útil para uma aplição que deseja executar uma ação assíncrona sem a dependência do objeto de retorno DOMRequest por cada método da interface  DeviceStorage.

    Para esse fim, um evento change é acionado cada vez que um arquivo é criado, modificado ou deletado. Este evento pode ser capturado utilizando a propriedade  onchange ou o método addEventListener(). O evento pega um objeto DeviceStorageChangeEvent que um objeto regular Event que tem duas própriedades não obrigatórias:

    var sdcard = navigator.getDeviceStorage('sdcard');
    
    sdcard.onchange = function (change) {
      var reason = change.reason;
      var path   = change.path;
    
      console.log('The file "' + path + '" has been ' + reason);
    }
    

    Especificação

    Não faz parte de qualquer especificação.

    Compatibilidade com Browser

    Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari
    Basic support ? ? Não suportado Não suportado Não suportado
    Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
    Basic support ? ? Não suportado Não suportado Não suportado

    Veja também

    Etiquetas do documento e colaboradores

    Contribuíram para esta página: MarcoBruno
    Última atualização por: MarcoBruno,