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.

This specification defines an Application Programming Interface (API) that provides access to media gallery located on the device.

Introduction

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.

Usage Examples

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:

Security and Privacy Considerations

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.

Privacy considerations for implementers of Gallery API

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.

API Description

Gallery interface

The 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.

const unsigned short AUDIO_TYPE = 0

Constant used to identify audio type of media.

const unsigned short VIDEO_TYPE = 1

Constant used to identify video type of media.

const unsigned short IMAGE_TYPE = 2

Constant used to identify image type of media.

const unsigned short SORT_BY_FILENAME = 3

Constant used to identify sort by filename.

const unsigned short SORT_BY_FILEDATE = 4

Constant used to identify sort by file date.

const unsigned short SORT_BY_MEDIATYPE = 5

Constant used to identify sort by media type.

const unsigned short SORT_BY_TITLE = 6

Constant used to identify sort by title.

const unsigned short SORT_BY_AUTHOR = 7

Constant used to identify sort by author.

const unsigned short SORT_BY_ALBUM = 8

Constant used to identify sort by album.

const unsigned short SORT_BY_DATE = 9

Constant used to identify sort by date

const unsigned short SORT_BY_ASCENDING = 10

Constant used to identify ascending sort order.

const unsigned short SORT_BY_DESCENDING = 11

Constant used to identify ascending sort order.

readonly attribute unsigned long length

the number of media objects in the gallery.

caller PendingOp find ()

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:

If the attempt was successful, dispatch a success event. If the attempt fails, and the method was
invoked with a non-nullerrorCB argument, this method must dispatch an error
event with the code attribute set according to the type of failure that has occurred.

If the attempt was successful, dispatch a success event. If the attempt fails, and the method was
invoked with a non-nullerrorCB argument, this method must dispatch an error
event with the code attribute set according to the type of failure that has occurred.

GalleryInfoCB successCB

Function to call when the asynchronous operation completes

optional GalleryErrorCB? errorCB

Function to call when the asynchronous operation fails.

MediaObject interface

MediaObject 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.

readonly attribute unsigned long id

Unique id of media object. This id is a unique numeric identifiers of
the object. This id is persistent while the gallery is opened.

GalleryInfo interface

supportedMediaObjectType attribute is required? Other attribute could be taken into account.

readonly attribute DOMString title

The title of the gallery.

readonly attribute Date createdDate

The date and time the gallery was originally created.

readonly attribute DOMString location

The location the gallery is located on.

readonly attribute DOMString[] description

>The description of the gallery.

readonly attribute DOMString[] supportedMediaObjectType

A list of media object type supported by this gallery.

GalleryFindOptions interface

GalleryFindOptions interface describe the options that can be applied to media object searching and displaying.

attribute DOMString? filter

A DOMString-based search filter with which to search. It's working based on the metadata of media object.

attribute short? mediaType

Specify the scope of media type for finding the media object

attribute GalleryInfo[]? gallery

Specify the scope of gallery for finding the media object

attribute short? order

Specify wheither media objects are ordered in ascending or descending order. Default is an ascending order.

attribute short? firstSortOption

Primary criteria to order the media object of the gallery.

attribute short? secondSortOption

Second criteria to order the media object of the gallery.

attribute Date? startDate

Start date for performing the search. Media object with date previous
to that date will not be returned.

attribute Date? endDate

End date for performing the search. Media object with date later to
that date will not be returned.

GalleryFindCB interface

void onSuccess (in MediaObject[] mediaObjectObjs)

MediaObject[] mediaObjectObjs

The Media Object resulting from the given Gallery find() method.

GalleryInfoCB interface

void onSuccess (in GalleryInfo[] galleryInfoObjs)

GalleryInfo[] galleryInfoObjs

The GalleryInfo Objects resulting from the given Gallery getGalleries() method.

GalleryErrorCB interface

void onError ()

GalleryError error

The Gallery API related error object.

GalleryError interface

The GalleryError interface encapsulates all errors in the Gallery API.

More error codes to be defined here.

const unsigned short UNKNOWN_ERROR = 0

An unknown error occurred.

const unsigned short INVALID_ARGUMENT_ERROR = 1

An invalid parameter was provided when the requested method was invoked.

const unsigned short TIMEOUT_ERROR = 2

The requested method timed out before it could be completed.

const unsigned short PENDING_OPERATION_ERROR = 3

If the user agent is currently waiting for a callback on a current find() operation, as defined in this specification.

const unsigned short IO_ERROR = 4

An error occurred in communication with the underlying implementation that meant the requested method could not complete.

const unsigned short NOT_SUPPORTED_ERROR = 5

The requested method is not supported by the current implementation.

const unsigned short PERMISSION_DENIED_ERROR = 20

Access to the requested method was denied at the implementation or by the user.

readonly attribute unsigned short code

An error code assigned by an implementation when an error has occurred in Gallery API processing.

Use Cases and Requirements

Use Cases

Use Case 1:

While uploading a photo to a web site, I'd like the photos that are relevant in that context to be represented to me
to select from. E.g. if I'm uploading a photo to a travel blog about Paris I'm probably only interested in photos from that area, thus I'd like
those to be shown to me very prominently (I should still be able to select photos from other areas, if I want to).

Use Case 2: Picture album application

When user executes picture album app, this should list up the albums those were available from handset memory, external memory and even flickr,
facebook. There are a lot of different albums. Thus user would like to sort these by the specific metadata property like title, created date, location, etc.
Typically when one album has a lot of pictures, user would like to search a picture by the specific metadata information. In addtion,
user wants to reorder pictures by the some metadata information. And user would like to take a look at some pictures those were taken in special place.

Requirements

The Gallery API:

MUST enable listing all of galleries from available sources( e.g. local storage, memory card and even cloud services )

MUST enable filtering and ordering the list of galleries or media object repectively according to various options (e.g. sorted by date, title, geolocation, etc.)

MUST enable to search a media object within limited scope of galleries