navigator.b2g.getDeviceStorage

Description

The getDeviceStorage method is used to access some storage area available on the device.

This method give access to a storage area from the device's default storage, that is the storage area whose .default attribute is true. This is controlled by the user via Settings App > Media Storage > Default media location (e.g. sdcard, internal memory, etc.) Alternatively, you can use the getDeviceStorages method which returns an Array of DeviceStorage (KaiOS 2.5 version but can be applied to 3.0)objects, one per physical storage area.

Regarding [DeviceStorage] (/docs/api/web-apis/deviceStorage/device-storage/)

1. DeviceStorage will be placed **after "navigator.b2g"
2. Syntax of method DeviceStorage.enumerate() is deifferent.

---

Syntax

var instanceOfDeviceStorage = navigator.b2g.getDeviceStorage(storageName);

Parameters

storageName

The name of the targeted storage area. Firefox OS supports the following areas:

• apps: This storage area is used to store the user data needed by apps. As it is critical data, accessing this storage area requires some extra privileges (see below) and is available to certified applications only.

• music: This is the storage area where music and sounds are stored.

• pictures: This is the storage area where pictures are stored.

• sdcard: This is the storage area that gives access to the device's SDCard. sdcard is also used as the name of the device's default internal storage, which is a bit unfortunate and potentially confusing; be aware.

• videos: This is the storage area where videos are stored.

---

Returns

This method returns a DeviceStorage object that can be used to manage files on the associated storage area.

---

Examples

var sdcard = navigator.b2g.getDeviceStorage("sdcard");

DeviceStorage.enumerate()

DeviceStorage.enumerate() is a new return type replaces DOMCursor since DOMCursor has deprecated already. You can find details of the new return type --- FileIterable and examples of using DeviceStorage.enumerate() in this document. DeviceStorage.enumerate()'s retuen type has been changed to "Filelterable." DEtails below:

Filelterable

FileIterable is declared to be asynchronously iterable, for details about iterable protocol and iterator protocol, please check up Iteration protocols, which introduces the synchronous version of iterable and iterator. MDN page of asynchronous iterable and iterator does not exist yet, however, they are mostly the same, except:

1. itor.next() returns a Promise withe the result object.
2. Supports for-await-of to loop through the iteration.
3. Does not support indexing.

For more details about a asynchronously iterable, please reference the W3C spec at Asynchronously iterable declarations.

Interfaces

Interface of Filelterable and DeviceStorage.enumerate() are as follow:

[Exposed=Window]

interface FileIterable {

async iterable<File>;

};

[Throws]

FileIterable enumerate(optional DeviceStorageEnumerationParameters options = {});

[Throws]

FileIterable enumerate(DOMString path, optional DeviceStorageEnumerationParameters options = {});

[Throws]

FileIterable enumerateEditable(optional DeviceStorageEnumerationParameters options = {});

[Throws]

FileIterable enumerateEditable(DOMString path, optional DeviceStorageEnumerationParameters options = {});

Examples

For example, if there are three files a.txt, b.txt, c.txt in default internal SD card, and we want to list them out.

Use itor.next() to loop through the iteration

var sdcard = navigator.b2g.getDeviceStorage('sdcard');

var iterable = sdcard.enumerate();

var files = iterable.values();

var file1 = await files.next();

// file1 is a Promise and will be resolved with Object { done: false, value: File {name: "/sdcard/a.txt", ...} }

var file2 = await files.next();

// file2 is a Promise and will be resolved with Object { done: false, value: File {name: "/sdcard/b.txt", ...} }

var file3 = await files.next();

// file3 is a Promise and will be resolved with Object { done: false, value: File {name: "/sdcard/c.txt", ...} }

var noMoreFile = await files.next();

// noMoreFile is a Promise and will be resolved with Object { done: true, value: Undefined }

Use for await-of to loop through the iteration

var sdcard = navigator.b2g.getDeviceStorage('sdcard');

var iterable = sdcard.enumerate();

async function printAllFiles() {

for await (let file of iterable) {

console.log(file);

}

}

printAllFiles();

// Will print out the following in console...

// Object { done: false, value: File {name: "/sdcard/a.txt", ...} }

// Object { done: false, value: File {name: "/sdcard/b.txt", ...} }

// Object { done: false, value: File {name: "/sdcard/c.txt", ...} }