The Bondi Gallery Module: bondi.gallery - Version 1.0

28 May 2009

Authors

Stefano Vercelli <stefano.vercelli@telecomitalia.it>

Abstract

BONDI Gallery interface.

1. Introduction
- 1.1. Features
- 1.2. Device Capabilities
2. Type Definitions
- 2.1. GalleryArray
- 2.2. MediaItemArray
3. Interfaces
- 3.1. GalleryError
- 3.2. GalleryManager
- 3.3. Gallery
- 3.4. MediaItem

Summary of Methods

Interface	Method
GalleryError
GalleryManager	GalleryArray getGalleries()
Gallery	unsigned integer getNumberOfMediaItems() PendingOperation open(SuccessCallback onSuccess, ErrorCallback onError) PendingOperation refresh(SuccessCallback onSuccess, DeviceAPIErrorCallback onError) void close() PendingOperation changeView(SuccessCallback onSuccess, ErrorCallback onError, Map viewOptions) MediaItemArray getMediaItems() MediaItem getMediaItemById(unsigned long itemId)
MediaItem

1. Introduction

The BONDI Gallery interface provides access to media galleries located on the phone. A media gallery is a collection of media files (here referred to as media items), that is image, audio and video files. The number and the location of media galleries are implementation dependent. As an example, on a Windows Mobile phone a gallery can be located in the directory "\My Documents". A gallery can also be located in different directories; for example you can have a single gallery including files from "\My Documents" directory and from the memory card. The interface allows the user to create a custom view of the gallery. This means that the interface exposes an API to filter and order the list of files according to various options. As an example a user can request all images sorted by date, or mp3 files sorted by author.

1.1. Features

This is the list of URIs used to declare this API's features, for use in bondi.requestFeature. For each URL, the list of functions provided is provided.

http://bondi.omtp.org/api/gallery.read: Access to the gallery content.

Device capabilities: io.file.read

1.2. Device capabilities

io.file.read

Read gallery files from the filesystem.

Security parameters:

name: Name of directory or file, in virtual filesystem, e.g. rootlocation/filename

2. Type Definitions

2.1. `GalleryArray`

Array of Gallery objects.

        typedef sequence<Gallery>   GalleryArray;

2.2. `MediaItemArray`

Array of MediaItem objects.

        typedef sequence<MediaItem> MediaItemArray;

3. Interfaces

3.1. `GalleryError`

Gallery specific errors.

        interface GalleryError : GenericError {

                const unsigned short GALLERY_OPEN_ERROR = 1;

                const unsigned short GALLERY_NOT_OPEN_ERROR = 2;
        };

This interface inherits from: GenericError

Constants

unsigned short GALLERY_OPEN_ERROR: Gallery is already open
unsigned short GALLERY_NOT_OPEN_ERROR: Gallery is not open

3.2. `GalleryManager`

Interface retrieval of list of media galleries of the phone.

        interface GalleryManager {

                GalleryArray getGalleries();
        };

This interface allows for the retrieval of the list of Media Galleries present on the phone. The number of galleries is hardcoded in the implementation. As an example, in a windows mobile implementation it may retrieve the gallery located in the directory "\My Documents" and another one located on the memory card. The property info of each gallery can be checked to get further details.

Code example

        var availableGalleries = bondi.gallery.getGalleries();
        for (i=0; iavailableGalleries.length; i++) {
                var galleryInfo = availableGalleries[i].info;
                // check gallery info...
        }

Methods

getGalleries

Retrieves all galleries managed by the manager.

Signature

GalleryArray getGalleries();

The number of galleries depends on the implementation. It can return an empty array: if it does this means that the developer or phone manufacturer doesn't give access to galleries, or that there are no galleries currently available (for example, because there is no memory card in the phone).

Return value

a vector containing all available galleries.

API features

http://bondi.omtp.org/api/gallery.read

Code example

        var availableGalleries = bondi.gallery.getGalleries();

3.3. `Gallery`

Interface to access the media gallery of the phone.

        interface Gallery {

                const unsigned short MEDIA_ITEM_TYPE_UNDEFINED = 0;

                const unsigned short MEDIA_ITEM_TYPE_AUDIO = 1;

                const unsigned short MEDIA_ITEM_TYPE_VIDEO = 2;

                const unsigned short MEDIA_ITEM_TYPE_IMAGE = 3;

                const unsigned short MEDIA_SORT_NONE = 0;

                const unsigned short MEDIA_SORT_BY_FILENAME = 1;

                const unsigned short MEDIA_SORT_BY_FILEDATE = 2;

                const unsigned short MEDIA_SORT_BY_TYPE = 3;

                const unsigned short MEDIA_SORT_BY_TITLE = 20;

                const unsigned short MEDIA_SORT_BY_AUTHOR = 21;

                const unsigned short MEDIA_SORT_BY_ALBUM = 22;

                const unsigned short MEDIA_SORT_BY_DATE = 23;

                const unsigned short MEDIA_SORT_ASCENDING = 0;

                const unsigned short MEDIA_SORT_DESCENDING = 1;

                readonly attribute Map info;

                unsigned long getNumberOfMediaItems()
                        raises(SecurityError, GalleryError);

                PendingOperation open(in SuccessCallback onSuccess, in ErrorCallback onError)
                        raises(SecurityError, DeviceAPIError, GalleryError);

                PendingOperation refresh(in SuccessCallback onSuccess, in DeviceAPIErrorCallback onError)
                        raises(SecurityError, DeviceAPIError, GalleryError);

                void close()
                        raises(DeviceAPIError, GalleryError);

                PendingOperation changeView(in SuccessCallback onSuccess,
                                            in ErrorCallback onError,
                                            in Map viewOptions)
                        raises(SecurityError, DeviceAPIError, GalleryError);

                MediaItemArray getMediaItems()
                        raises(SecurityError, DeviceAPIError, GalleryError);

                MediaItem getMediaItemById(in unsigned long itemId)
                        raises(SecurityError, DeviceAPIError, GalleryError);
        };

Interface for handling a media gallery of the device. This interface scans a predefined location of the filesystem for media files and extracts multimedia information from them. The user can create a custom view by filtering and sorting the list of media items.

Code example

        myGallery.open(openSuccess, openFailure);
        function openSuccess() {
                alert("Gallery contains " + myGallery.getNumberOfMediaItems() + " media items");
                myGallery.changeView(changeViewSuccess, changeViewFailure, {filterItemType:gallery.MEDIA_ITEM_TYPE_IMAGE});
        }
        function openFailure(e) {
                alert("Cannot open the gallery");
        }
        function changeViewSuccess() {
                alert("Gallery contains " + myGallery.getNumberOfMediaItems() + " images");
        }
        function changeViewFailure(e) {
                alert("Cannot change gallery view");
        }

Constants

unsigned short MEDIA_ITEM_TYPE_UNDEFINED: Constant used to identify an undefined MediaItem.
unsigned short MEDIA_ITEM_TYPE_AUDIO: Constant used to identify an audio MediaItem.
unsigned short MEDIA_ITEM_TYPE_VIDEO: Constant used to identify a video MediaItem.
unsigned short MEDIA_ITEM_TYPE_IMAGE: Constant used to identify an image MediaItem.
unsigned short MEDIA_SORT_NONE: Constants used to identify no sort ordering.
unsigned short MEDIA_SORT_BY_FILENAME: Constants used to identify sort by filename.
unsigned short MEDIA_SORT_BY_FILEDATE: Constants used to identify sort by file date.
unsigned short MEDIA_SORT_BY_TYPE: Constants used to identify sort by media item type.
unsigned short MEDIA_SORT_BY_TITLE: Constants used to identify sort by title.
unsigned short MEDIA_SORT_BY_AUTHOR: Constants used to identify sort by author.
unsigned short MEDIA_SORT_BY_ALBUM: Constants used to identify sort by album.
unsigned short MEDIA_SORT_BY_DATE: Constants used to identify sort by date.
unsigned short MEDIA_SORT_ASCENDING: Constant used to identify ascending sort order.
unsigned short MEDIA_SORT_DESCENDING: Constants used to identify descending sort order.

Attributes

[readonly] Map info

Returns information about the gallery.

Provides generic information regarding the gallery. In particular it indicates if the location of the gallery is removable, is on the device or both, and a list of mime types supported by this gallery. The return map can be: {locationType:removable|device|mixed;mimetype:<list of supported mimetypes>}

Code example

        var galleryDetails = gallery.info;
        alert("This gallery is located on a " + galleryDetails.locationType + " location");
        alert("The content of this gallery is " + galleryDetails.contentType);

Methods

getNumberOfMediaItems

Gets the number of media items currently in the gallery.

Signature

unsigned long getNumberOfMediaItems();

Returns the number of media items (that is pictures, videos or audio files) in the current view of the gallery. The number of items may change every time a changeView or refresh operation is performed.

Return value

the number of media items in the current gallery view

Exceptions

SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
GalleryError: GALLERY_NOT_OPEN if the gallery is not open

API features

http://bondi.omtp.org/api/gallery.read

Code example

                var numberOfItems = gallery.getNumberOfMediaItems();

open

Opens the gallery.

Signature

PendingOperation open(SuccessCallback onSuccess, ErrorCallback onError);

When the gallery is opened, memory is allocated and filled with information about the media items it contains.

Parameters

onSuccess: Callback issued when the opening is correctly finished.
onError: Callback issued if an error occurs during the opening.

Return value

PendingOperation enabling the requester to cancel this request.

Exceptions

SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
DeviceAPIError: PENDING_OPERATION_ERROR if another Open operation is being processed
GalleryError: GALLERY_OPEN_ERROR if the gallery is already open

API features

http://bondi.omtp.org/api/gallery.read

Code example

        gallery.open(openSuccess, openFailure);
        function openSuccess() {
                alert("Gallery successfully opened");
        }
        function openFailure(e) {
                alert("Cannot open gallery");
        }

refresh

Refresh the content of the gallery

Signature

PendingOperation refresh(SuccessCallback onSuccess, DeviceAPIErrorCallback onError);

When a refresh is run, the content of the gallery is updated with files added or deleted. The current view options (if any) will be maintained.

Parameters

onSuccess: Callback issued when the refresh is correctly finished.
onError: Callback issued if an error occurs during the refresh.

Return value

PendingOperation enabling the requester to cancel this request.

Exceptions

SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
DeviceAPIError: PENDING_OPERATION_ERROR if a Refresh or ChangeView operation is being processed
GalleryError: GALLERY_NOT_OPEN_ERROR if the gallery is not open

API features

http://bondi.omtp.org/api/gallery.read

Code example

        var itemNum1;
        var itemNum2;
        gallery.open(openSuccess, openFailure);
        function openFailure(e) {
                alert("Cannot open gallery");
        }
        function openSuccess() {
                alert("Gallery successfully opened");
                itemNum1 = gallery.getNumberOfMediaItems();
                // Take some pictures here...
                // ...
                // Then refresh your gallery content:
                gallery.refresh(refreshSuccess, refreshFailure);
        }
        function refreshFailure(e) {
                alert("Cannot refresh gallery");
        }
        function refreshSuccess() {
                itemNum2 = gallery.getNumberOfMediaItems();
                var itemDiff = itemNum2 - itemNum1;
                alert("You added "+itemDiff+" pictures to your gallery");
        }

close

Closes the media gallery.

Signature

void close();

When the gallery is closed, all information regarding the current view is lost and memory is released.

Exceptions

DeviceAPIError: PENDING_OPERATION_ERROR if an Open, Refresh or ChangeView operation is being processed
GalleryError: GALLERY_NOT_OPEN_ERROR if the gallery is not open

Code example

        gallery.open(openSuccess, openFailure);
        function openSuccess() {
                alert("Gallery successfully opened");
                // Perform all operations you need...
                // ...
                // When no longer needed, close the gallery so
                // memory is released.
                gallery.close();
        }
        function openFailure(e) {
                alert("Cannot open gallery");
        }

changeView

Creates a new view of the gallery

Signature

PendingOperation changeView(SuccessCallback onSuccess, ErrorCallback onError, Map viewOptions);

Changes the current view of the gallery filtering and ordering items according to the option parameters. If present, any option regarding a previous view is overwritten by the new ones. Sort options include ascending or descending order by file name, by file date, by media item type or by various fields from the metadata of the media item. Either a primary sort order or a primary and a secondary sort order (applied when files are equivalent as primary order) can be defined. Filter options include selection of the file date, of the media item type, of the file name, of the mimetype as well as various fields from the media item metadata.

Parameters

onSuccess: Callback issued when the refresh is correctly finished.
onError: Callback issued if an error occurs during the refresh.
viewOptions: Contains details on the way to sort and filter items in the new view. The possible map fields are: {order:<ascending or descending order constant>;primarySortOrder:<sort order constant>; secondarySortOrder:<sort order constant>;filterStartDate:<file date>; filterEndDate:<file date>;filterItemType:<media item type constant>; filterFileName:<file name>;filterMimeType:<mimetype>; filterMetaTag0:<metadata tag values>;filterMetaTag1:<metadata tag values>;...} where MetaTag0, MetaTag1, ... are the possible metadata tag labels

Return value

PendingOperation enabling the requester to cancel this request.

Exceptions

SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
DeviceAPIError: INVALID_ARGUMENT_ERROR if an invalid argument is passed PENDING_OPERATION_ERROR if a Refresh or ChangeView operation is being processed
GalleryError: GALLERY_NOT_OPEN_ERROR if the gallery is not open

API features

http://bondi.omtp.org/api/gallery.read

Code example

        gallery.open(openSuccess, openFailure);
        function openFailure(e) {
                alert("Cannot open gallery");
        }
        function openSuccess() {
                alert("Gallery successfulyy opened");
                gallery.changeView(cvSuccess, cvFailure, {
                        order:gallery.MEDIA_SORT_ASCENDING,
                        primarySortOrder:gallery.MEDIA_SORT_BY_FILENAME,
                        secondarySortOrder:gallery.MEDIA_SORT_NONE,
                        filterItemType:gallery.MEDIA_ITEM_TYPE_IMAGE,
                        filterStartDate:20080101,
                        filterEndDate:20081130
                });
        }
        function cvFailure(e) {
                alert("Cannot change gallery view");
        }
        function cvSuccess() {
                var itemNum = gallery.getNumberOfMediaItems();
                alert("You have "+itemNum+" pictures taken in November 2008");
        }

getMediaItems

Retrieves the list of media items

Signature

MediaItemArray getMediaItems();

Retrieves an array of MediaItems from the gallery according to current view options. If no view has been created, all items of the gallery are returned. In this case, the order of items is random.

Return value

a vector of media items

Exceptions

SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
DeviceAPIError: PENDING_OPERATION_ERROR if an Open, Refresh or ChangeView operation is being processed
GalleryError: GALLERY_NOT_OPEN_ERROR if the gallery is not open

API features

http://bondi.omtp.org/api/gallery.read

Code example

        gallery.open(openSuccess, openFailure);
        function openFailure(e) {
                alert("Cannot open gallery");
        }
        function openSuccess() {
                alert("Gallery successfulyy opened");
                var mediaItemArray = gallery.getMediaItems();
                for (i=0; imediaItemArray.length; i++) {
                        alert("Item number "+i+", file is "+mediaItemArray[i].fileName);
                }
        }

getMediaItemById

Retrieves a media item by id

Signature

MediaItem getMediaItemById(unsigned long itemId);

Retrieves a media item by his id. The id of an item never changes while the gallery is open. Notice that this method can retrieve a media item even if it is out of the current view.

Parameters

itemId: Unique numeric id of the media item to be retrieved.

Return value

the MediaItem corresponding to that id

Exceptions

SecurityError: PERMISSION_DENIED_ERROR when access is denied by the security policy.
DeviceAPIError: PENDING_OPERATION_ERROR if an Open, Refresh or ChangeView operation is being processed
GalleryError: GALLERY_NOT_OPEN_ERROR if the gallery is not open

API features

http://bondi.omtp.org/api/gallery.read

Code example

        myGallery.open(openSuccess, openFailure);
        var myPreferredImageId = -1;
        function openFailure(e) {
                alert("Cannot open the gallery");
        }
        function openSuccess() {
                myGallery.changeView(changeViewSuccess, changeViewFailure, {filterItemType:gallery.MEDIA_ITEM_TYPE_IMAGE});
        }
        function changeViewFailure(e) {
                alert("Cannot change gallery view");
        }
        function changeViewSuccess() {
                var imageArray = gallery.getMediaItems();
                for (i=0; iimageArray.length; i++) {
                        var answer = Confirm("Is this your preferred image?");
                        if(answer) {
                                myPreferredImageId = imageArray[i].id;
                        }
                }
                if(myPreferredImageId != -1) {
                        var myPreferredImage = gallery.getMediaItemById(myPreferredImageId);
                        // Display my preferred image
                }
        }

3.4. `MediaItem`

Interface to a single media item.

        interface MediaItem {

                readonly attribute unsigned long id;

                readonly attribute long type;

                readonly attribute DOMString mimeType;

                readonly attribute DOMString fileName;

                readonly attribute Map metadata;
        };

The MediaItem interface offer access to information regarding a single media item. A media item is a media file located in the gallery, that is an image, audio or video file. All information provided are readonly.

Code example

        var myPreferredPictureId = 7;
        var myPreferredPicture = gallery.getMediaItemById(myPreferredPictureId);
        if(myPreferredPicture.type == gallery.MEDIA_ITEM_TYPE_IMAGE) {
                alert("My preferred picture was taken with camera " + myPreferredPicture.metadata.cameraModel);
        }
        else {
                alert("My preferred picture is not an image...");
        }

Attributes

[readonly] unsigned long id

Unique Id of the media item.

This id is a unique numeric identifiers of the item. This id is persistent while the media gallery is opened, so a refresh or changeView operation will not change his value.

Code example

        var selectedItem = mediaItem.id;

[readonly] long type

Type of media item.

The type of the media item is an internal representation to distinguish among audio items (MEDIA_ITEM_TYPE_AUDIO), video items (MEDIA_ITEM_TYPE_VIDEO) or image items (MEDIA_ITEM_TYPE_IMAGE).

Code example

        if (mediaItem.type == gallery.MEDIA_ITEM_TYPE_IMAGE) {
                //display the image
        }

[readonly] DOMString mimeType

Mimetype of the media file.

This field is the mimetype associated to the media file. It can be used to open the media item with an external application.

Code example

        var mimetype = mediaItem.mimeType;

[readonly] DOMString fileName

Gets the name of the file corresponding to this item.

Return the full file name (including path) of the media item.

Code example

        var fileName = mediaItem.fileName;

[readonly] Map metadata

Metadata associated to the media item.

Informations extracted from the media file header. The return map can be: {metaTag0:<metadata tag values>, metaTag1:<metadata tag values>, ...} where metaTag0, metaTag1, ... are the fields of file's metadata.

It is also possible to iterate over the metadata collection:

Code example

        var pictureInfo = mediaItem.metadata;
        alert("Picture taken with camera " + pictureInfo.cameraModel);

Code example

        var metadata = mediaitem.metadata; 
        for (var metadate in metadata) {
                alert(metadate + " of " + mediaitem.fileName + " is " + metadata[metadate]);
        }

The Bondi Gallery Module: bondi.gallery - Version 1.0

28 May 2009

Authors

Abstract

Table of Contents

Summary of Methods

1. Introduction

1.1. Features

1.2. Device capabilities

2. Type Definitions

2.1. GalleryArray

2.2. MediaItemArray

3. Interfaces

3.1. GalleryError

Constants

3.2. GalleryManager

Code example

Methods

Signature

Return value

API features

Code example

3.3. Gallery

Code example

Constants

Attributes

Code example

Methods

Signature

Return value

Exceptions

API features

Code example

Signature

Parameters

Return value

Exceptions

API features

Code example

Signature

Parameters

Return value

Exceptions

API features

Code example

Signature

Exceptions

Code example

Signature

Parameters

Return value

Exceptions

API features

Code example

Signature

Return value

Exceptions

API features

Code example

Signature

Parameters

Return value

Exceptions

API features

Code example

3.4. MediaItem

Code example

Attributes

Code example

Code example

Code example

Code example

Code example

Code example

2.1. `GalleryArray`

2.2. `MediaItemArray`

3.1. `GalleryError`

3.2. `GalleryManager`

3.3. `Gallery`

3.4. `MediaItem`