DeviceStorage.addNamed()

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

Summary

The addNamed method is used to add a file inside a given storage area.

This method allows to choose the name of the file. However, if a file with the same name already exists, this method will fail. It's not possible to override a file. To update or modify a file, you have to pick it first with the getEditable or enumerateEditable method.

Note: Repository in a storage area is implicit; it's not possible to explicitly create an empty repository. If you want to use a repository structure you have to make it part of the name of the file to store. So if you want to store the file bar inside the foo repository, you have to provide the complete path name of the file: addNamed(blob, "foo/bar").

As files are added in a given restricted storage area, for security reasons, a file path name cannot start with "/" nor "../" (and "./" is pointless).

Syntax

var instanceOfDOMRequest = instanceOfDeviceStorage.addNamed(file, name);

Parameters

file: A Blob object representing the file to add (note that a File object is also a Blob object).
name: A string representing the full name (path + file name) of the file.

Returns

It returns a DOMRequest object to handle the success or error of the operation.

Example

var sdcard = navigator.getDeviceStorage("sdcard");
var file   = new Blob(["This is a text file."], {type: "text/plain"});
var request = sdcard.addNamed(file, "myFile.txt");
request.onsuccess = function () {
  var name = this.result.name;
  console.log('File "' + name + '" successfully wrote on the sdcard storage area');
}
request.onerror = function () {
  console.warn('Unable to write the file: ' + this.error);
}

Specification

Not part of any specification.