The Device APIs Working Group is currently not pursuing the approach outlined in this draft, so it should be considered historical. Please treat this document with caution and do not reference it or use it as the basis for implementation. The domain covered by this document is still within the scope of the Working Group as defined in its Charter. The Working Group may pursue an alternative API design that is based on the current Web browser security model.
The Gallery API defines a high-level interface for accessing media gallery located on the device. A media gallery is a collection of media objects such as video, audio and image.
Further examples are required to give better understanding concerning the overall functions of the gallery API.
The following code extracts illustrate how to work with a gallery API in the device:
// append images with a title matching 'foobar' from galleries
// not older than 3 months to the document.body
var gallery = navigator.service.gallery;
function getGalleriesSuccess(galleryInfoObjs) {
var galleries = [];
for (var i in galleryInfoObjs) {
if ((new Date().getTime())-galleryInfoObjs[i].createDate < 100*60*60*24*3) {
galleries.push(galleryInfoObjs[i]);
}
}
appendMedia(galleries);
}
function appendMedia(galleries) {
function findSuccess(mediaObjs) {
var container = document.createElement("div");
for (var i in mediaObjs) {
var img = document.createElement("img");
var title = document.createElement("div");
title.innerHTML = "Title: " + mediaObjs[i].title;
// create blob URI using window.createObjectURL():
// http://dev.w3.org/2006/webapi/FileAPI/#creating-revoking
img.src = createObjectURL(mediaObjs[i]);
container.appendChild(img);
container.appendChild(title);
}
document.body.appendChild(container);
}
function findError() {
console.log('whoops, something went wrong!');
}
gallery.find(['title', 'uri'], findSuccess, findError,
{filter: 'foobar', galleries: galleries, mediaType: gallery.IMAGE_TYPE });
}
gallery.getGalleries(getGalleriesSuccess);
This section is under development.
The API defined in this specification can be used to add, update, find and delete media objects from user's media gallery. This information can potentially compromise user privacy and a conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism should ensure that such operations MUST be authenticated.
A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism SHOULD ensure that privacy information is not revealed without user's informed consent.
Gallery interfaceThe actual object of which the API will be hanging off is still under discussion (e.g. navigator.service vs from
navigator.device); see ISSUE-67
The Gallery interface exposes an interface to access media gallery located on the device.
Find media objects in the gallerys according to the find process detailed below.
This method takes two, three or four arguments. When called, it immediately returns a PendingOp object, as
defined in [[!CORE-DEVICE]], and then asynchronously starts a find process defined as follows:
PendingOp task source in one of the task queues
(i.e. an existing find() operation is still pending a response), and the current method was invoked with a
non-null errorCB argument, dispatch an error event with a PENDING_OPERATION_ERROR code value.
success event. If the attempt fails, and the method was
invoked with a non-null errorCB argument, this method must dispatch an error
event with the code attribute set according to the type of failure that has occurred.
Retrieve all galleries from available sources(e.g. device local memory, external memory and even Fliker, Facebook, etc.) according to the retrieve process detailed below.
This method takes one or two arguments. When called, it immediately returns a PendingOp object, as
defined in [[!CORE-DEVICE]], and then asynchronously starts a retrieve process defined as follows:
PendingOp task source in one of the task queues
(i.e. an existing find() operation is still pending a response), and the current method was invoked with a
non-null errorCB argument, dispatch an error event with a PENDING_OPERATION_ERROR code value.
success event. If the attempt fails, and the method was
invoked with a non-null errorCB argument, this method must dispatch an error
event with the code attribute set according to the type of failure that has occurred.
MediaObject interfaceMediaObject interface offer access to information regarding an each media object. A media object is a media file belonged to the gallery, that
is an video, audio or image file.
GalleryInfo interfaceGalleryInfo interface capture generic metadata information of a gallery.
supportedMediaObjectType attribute is required? Other attribute could be taken into account.
GalleryFindOptions interfaceGalleryFindOptions interface describe the options that can be applied to media object searching and displaying.
GalleryFindCB interfaceGalleryInfoCB interfaceGalleryErrorCB interfaceGalleryError interfaceThe GalleryError interface encapsulates all errors in the Gallery API.
More error codes to be defined here.
The Gallery API:
The API described in this document took inspiration from the following documents:
This is a list of features that have been discussed with respect to this version of the API but for which it has been decided that if they are included it will be in a future revision.
Many thanks to OMTP BONDI who provided the initial input into this specification.