- From: WonSuk Lee via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 17 Mar 2010 02:27:30 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/gallery
In directory hutz:/tmp/cvs-serv23443/2009/dap/gallery
Modified Files:
Overview.html
Log Message:
Initial draft
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/gallery/Overview.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -d -r1.3 -r1.4
--- Overview.html 17 Mar 2010 00:02:46 -0000 1.3
+++ Overview.html 17 Mar 2010 02:27:28 -0000 1.4
@@ -1,517 +1,403 @@
<!DOCTYPE html>
<html>
- <head>
- <title>The Gallery API</title>
- <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
- <script src='../ReSpec.js/js/simple-node.js' class='remove'></script>
- <script src='../ReSpec.js/js/shortcut.js' class='remove'></script>
- <script src='../ReSpec.js/js/respec.js' class='remove'></script>
- <script src='../ReSpec.js/bibref/biblio.js' class='remove'></script>
- <script class='remove'>
+<head>
+ <title>The Gallery API</title>
+ <meta http-equiv="content-type" content="text/html; charset=UTF-8">
+ <script type="text/javascript" src="../ReSpec.js/js/respec.js" class="remove">
+ </script>
+ <script type="text/javascript" src="../ReSpec.js/js/sh_main.min.js"
+ class="remove">
+ </script>
+ <script type="text/javascript" class="remove">
var respecConfig = {
specStatus: "ED",
shortName: "gallery-api",
+ editors: [{name: "이원석(Wonsuk Lee)", company: "Electronics and Telecommunications Research Institute (ETRI)"},
+ {name: "이강찬(Kangchan Lee)", company: "Electronics and Telecommunications Research Institute (ETRI)"}],
// publishDate: "2009-08-06",
// previousPublishDate: "1977-03-15",
edDraftURI: "http://dev.w3.org/2009/dap/gallery/",
// lcEnd: "2009-08-05",
};
- </script>
- <script src='../common/config.js' class='remove'></script>
- </head>
+ </script>
+ <script type="text/javascript" src="../common/config.js" class="remove">
+ </script>
+ <link rel="stylesheet" href="../ReSpec.js/css/respec.css" type="text/css"
+ media="screen">
+</head>
<body>
-< section id=abstract>This specification defines an Application
-Programming Interface (<acronym title="Application Programming Interface">API</acronym>) that provides access
-to media gallery in the device. A media gallery is a collection of media items,
-such as video, audio and image. </
-section>< section>
-
-<h2>Introduction</h2>
-
-<p>The Gallery API defines a high-level interface for accessing media gallery
-in the device.</p>
-< section id=examples>
-
-<h2>Usage Examples</h2>
-
-<p>The following code extracts illustrate how to work with a gallery API in the
-device: </p>
-
-<div>
-<p>Opening the gallery and changing the view of gallery.</p>
-
-<p></p>
-<pre class="example sh_javascript_dom">// Define the changeView success callback function.
-function changeViewSuccess() {
- alert("Gallery contains "+ myGallery.getNumofMediaObjects() + " images");
-}
-
-// Define the changeView failure callback function.
-function changeViewFailure(e) {
- alert("Cannot change gallery view");
-}
-
-// Define the open Success callback function.
-function openSuccess() {
- alert("Gallery contains "+ myGallery.getNumofMediaObjects() + " media objects");
- myGallery.changeView(changeViewSuccess, changeViewFailure, {filterItemType:gallery})
-}
-
-
-// Define the open Failure callback function.
-function openFailure(e) {
- alert("Cannot open the gallery");
-
-// Open the gallery.
-myGallery.open(openSuccess, openFailure);</pre>
-<pre class="example sh_javascript_dom"></pre>
-</div>
-</ section></
- section>< section id=security>
-
-<h2>Security and Privacy Considerations</h2>
-The API defined in this specification can be used to add, update, find and
-delete media content 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.
-
-<h3>Privacy considerations for implementers of Capture API</h3>
-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. </
- section>< section id=api>
-
-<h2>API Description</h2>
-< section id=gallery>
-
-<h3><a>Gallery</a> interface</h3>
-
-<p>The <code>Gallery</code> interface exposes an interface to access media
-gallery in the device.</p>
-
-<p class="issue">Where does it hang off of? Example given above assumes
-navigator.device — in which case we need to define a
-<code>NavigatorDevice</code> interface somewhere.</p>
-<dl title="[Supplemental, NoInterfaceObject] interface MediaGallery"
-class="idl">
- <dt>const unsigned short MEDIA_SORT_NONE = 0</dt>
- <dd>Constant used to identify no sort ordering. </dd>
- <dt>const unsigned short MEDIA_SORT_BY_FILENAME = 1</dt>
- <dd>Constant used to identify sort by filename. </dd>
- <dt>const unsigned short MEDIA_SORT_BY_FILEDATE = 2</dt>
- <dd>Constant used to identify sort by file date. </dd>
- <dt>const unsigned short MEDIA_SORT_BY_MEDIATYPE = 3</dt>
- <dd>Constant used to identify sort by media type. </dd>
- <dt>const unsigned short MEDIA_SORT_BY_TITLE = 0</dt>
- <dd>Constant used to identify sort by title.</dd>
- <dt>const unsigned short MEDIA_SORT_BY_AUTHOR = 1</dt>
- <dd>Constant used to identify sort by author.</dd>
- <dt>const unsigned short MEDIA_SORT_BY_ALBUM = 2</dt>
- <dd>Constant used to identify sort by album. </dd>
- <dt>const unsigned short MEDIA_SORT_BY_DATE = 3</dt>
- <dd>Constant used to identify sort by date</dd>
- <dt>const unsigned short MEDIA_SORT_BY_ASCENDING = 0</dt>
- <dd>Constant used to identify ascending sort order.</dd>
- <dt>const unsigned short MEDIA_SORT_BY_DESCENDING = 1</dt>
- <dd>Constant used to identify ascending sort order. </dd>
- <dt>readonly attribute GalleryProperties metadata</dt>
- <dd>Generic metadata information regarding to the gallery.</dd>
-</dl>
-<dl title="[Supplemental, NoInterfaceObject] interface MediaGallery"
-class="idl">
- <dt>Unsigned long getNumofMediaObjects () </dt>
- <dd>Get the number of media objects in the gallery.</dd>
- <dt>PendingOperation open () </dt>
- <dd>Open the gallery in the device.
- <p>This method takes two arguments. When called, it immediately returns a
- <a href="#pendingoperation-interface"><code>PendingOperation</code></a>
- object and then asynchronously start a <em>open gallery</em> process
- defined as follows:</p>
- <p></p>
- <ol>
- <li>Open the gallery. Allow application to access media contents of the
- gallery.</li>
- <li>If successful, invoke the associated <code>successCB</code>. If the
- attempt fails, and the method was invoked with a non-null
- <code>errorCallback</code> argument, this method must invoke the
- <code>errorCallback</code> with a <a
- href="#captureerror-interface"><code>GalleryError</code></a> object
- as an argument. </li>
- </ol>
- <dl class="parameters">
- <dt>GallerySuccessCB successCB </dt>
- <dd>Function to call when the asynchronous operation completes </dd>
- <dt>optional GalleryErrorCB errorCB </dt>
- <dd>Function to call when the asynchronous operation fails. This
- parameter is OPTIONAL.</dd>
- </dl>
- </dd>
- <dt>PendingOperation refresh () </dt>
- <dd>Refresh the content item(s) of gallery.
- <p>This method takes two arguments. When called, it immediately returns a
- <a href="#pendingoperation-interface"><code>PendingOperation</code></a>
- object and then asynchronously start a <em>refresh gallery</em> process
- defined as follows:</p>
- <p></p>
- <ol>
- <li>Refresh the gallery. Apply the changes to the gallery (e.g. the
- added or deleted content items)</li>
- <li>If successful, invoke the associated <code>successCB</code>. If the
- attempt fails, and the method was invoked with a non-null
- <code>errorCallback</code> argument, this method must invoke the
- <code>errorCallback</code> with a <a
- href="#captureerror-interface"><code>GalleryError</code></a> object
- as an argument. </li>
- </ol>
- <dl class="parameters">
- <dt>GallerySuccessCB successCB </dt>
- <dd>Function to call when the asynchronous operation completes </dd>
- <dt>optional GalleryErrorCB errorCB</dt>
- <dd>Function to call when the asynchronous operation fails. This
- parameter is OPTIONAL.</dd>
- </dl>
- </dd>
- <dt>PendingOperation close () </dt>
- <dd>Close the gallery in the device. Disallow application to access media
- contents of the gallery.
- <p></p>
- </dd>
- <dt>PendingOperation changeView () </dt>
- <dd>Change the current view of the gallery
- <p>This method takes three arguments. When called, it immediately returns
- a <a href="#pendingoperation-interface"><code>PendingOperation</code></a>
- object and then asynchronously start a <em>change view</em> process
- defined as follows:</p>
- <p></p>
- <ol>
- <li>Change the view style of the gallery.</li>
- <li>If successful, invoke the associated <code>successCB</code>. If the
- attempt fails, and the method was invoked with a non-null
- <code>errorCallback</code> argument, this method must invoke the
- <code>errorCallback</code> with a <a
- href="#captureerror-interface"><code>GalleryError</code></a> object
- as an argument. </li>
- </ol>
- <dl class="parameters">
- <dt>GallerySuccessCB successCB </dt>
- <dd>Function to call when the asynchronous operation completes </dd>
- <dt>optional GalleryErrorCB errorCB </dt>
- <dd>Function to call when the asynchronous operation fails. This
- parameter is OPTIONAL</dd>
- <dt>optional ViewStyle ViewOption </dt>
- <dd>Describe details on the way to sort and filter media objects in
- the new view. This parameter is OPTIONAL </dd>
- <dd></dd>
- </dl>
- </dd>
- <dt>MediaObjects getMediaObjects () </dt>
- <dd>Retrieves the list of media object. Retrieves an array of Media Objects
- from the gallery according to current view options. If no view has been
- created, all items of the gallery are returned.
- <p></p>
- </dd>
- <dt>MediaObject getMediaObject () </dt>
- <dd>Retrieves the media object by id. The id of an media object never
- changes while gallery is open.
- <dl class="parameters">
- <dt>Unsigned long objId </dt>
- <dd>Unique numberic id of the media object to be retrieved. </dd>
- </dl>
- </dd>
-</dl>
-</ section>
-<p>< section id=galleryproperties> </p>
-
-<h3><a>GalleryProperties</a> interface</h3>
-
-<p><code>GalleryProperties</code> interface capture generic metadata
-information of a gallery.</p>
-
-<p>More properties to be defined here.</p>
-<dl title="[NoInterfaceObject] interface GalleryProperty" class="idl">
- <dt>readonly attribute DOMString? title</dt>
- <dd>The title of the gallery.</dd>
- <dt>readonly attribute Date CreatedDate</dt>
- <dd>The date and time the gallery was originally created.</dd>
-</dl>
-
-<p>< section id=mediaobject> </p>
-
-<h3><a>MediaObject</a> interface</h3>
-
-<p><code>MediaObject</code> 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.</p>
-<dl title="[NoInterfaceObject] interface MediaData" class="idl">
- <dt>const unsigned short MEDIA_OBJ_TYPE_UNDEFINED = 0</dt>
- <dd>Constant use to identify an undefined MediaObject. </dd>
- <dt>const unsigned short MEDIA_OBJ_TYPE_VIDEO = 1 </dt>
- <dd>Constant use to identify a video MediaObject.</dd>
- <dt>const unsigned short MEDIA_OBJ_TYPE_AUDIO = 2</dt>
- <dd>Constant use to identify an audio MediaObject.</dd>
- <dt>const unsigned short MEDIA_OBJ_TYPE_IMAGE = 3</dt>
- <dd>Constant use to identify an image MediaObject.</dd>
- <dt>readonly attribute unsigned long id</dt>
- <dd>Unique id of media object. This id is a unique numeric identifiers of
- the object. This id is persistent while the gallery is opened.</dd>
- <dt>readonly attribute unsigned long type</dt>
- <dd>Type of media object.</dd>
- <dt>readonly attribute unsigned DOMString mimeType</dt>
- <dd>Mimetype of the media file.</dd>
- <dt>readonly attribute unsigned DOMString filename</dt>
- <dd>The name of the file corresponding to this object.</dd>
- <dt>readonly attribute MediaObjectProperties metadata</dt>
- <dd>metadata associated to the media object.</dd>
-</dl>
-
-<p>< section id=MediaObjectProperties> </p>
-
-<h3><a>MediaObjectProperties</a> interface</h3>
-
-<p><code>MediaObjectProperties</code> interface capture generic metadata
-information of a media object.</p>
-
-<p>More properties to be defined here.</p>
-<dl title="[NoInterfaceObject] interface MediaObjectProperties" class="idl">
- <dt>readonly attribute DOMString? title</dt>
- <dd>The title of the media object.</dd>
- <dt>readonly attribute DOMString? author</dt>
- <dd>The author of the media object.</dd>
- <dt>readonly attribute DOMString? description</dt>
- <dd>A textual description of the media object.</dd>
- <dt>readonly attribute DOMString? keyword</dt>
- <dd>A descriptive phrase or keyword that specify the topic of the media
- object.</dd>
- <dt>readonly attribute DOMString? copyright</dt>
- <dd>The copyright statement. Identification of the copyrights holder.</dd>
- <dt>readonly attribute Date CreatedDate</dt>
- <dd>The date and time the media object was originally created.</dd>
-</dl>
-</ section>< section
-id=viewtype>
-
-<h3><a>ViewType</a> interface</h3>
-
-<p><code>ViewType</code> interface offer the way to describe how gallery is
-displayed.</p>
-<dl title="[NoInterfaceObject] interface FormatData" class="idl">
- <dt>attribute short order </dt>
- <dd>Specify wheither media objects are ordered in ascending or descending
- order. </dd>
- <dt>attribute short firstViewOption</dt>
- <dd>Primary criteria to order the media object of the gallery.</dd>
- <dt>attribute short secondViewOption</dt>
- <dd>Second criteria to order the media object of the gallery.</dd>
- <dt>attribute Data startDate </dt>
- <dd>Start date for performing the search. Media object with date previous
- to that date will not be returned.</dd>
- <dt>attribute Data endDate</dt>
- <dd>End date for performing the search. Media object with date later to
- that date will not be returned.</dd>
- <dt>attribute DOMString metaTag </dt>
- <dd>String to be searched in the metadata of media object on the
- gallery.</dd>
-</dl>
-</ section>< section
-id=GallerySuccesscallbak>
-
-<h3><a>GallerySuccessCB</a> interface</h3>
-<dl title="[Callback=FunctionOnly, NoInterfaceObject] interface CaptureCB"
-class="idl">
- <dt>void onSuccess () </dt>
- <dd>Callback function issued when the upper function is correctly
- finished.</dd>
-</dl>
-</ section>< section
-id=mediaobjects>
-
-<h3><a>MediaObj</a>ects typedef</h3>
-
-<p>The <a>MediaObj</a>ects typedef represents a <code>sequence</code> of <a
-href="#mediaobject"><code>MediaObject</code></a> objects.</p>
-<dl title="typedef sequence<MediaData> MediaArray" class="idl">
-</dl>
-</ section>< section
-id=errorcallback>
-
-<h3><a>GalleryErrorCB</a> interface</h3>
-<dl title="[Callback=FunctionOnly, NoInterfaceObject] interface CaptureErrorCB"
-class="idl">
- <dt>void onError () </dt>
- <dd><dl class="parameters">
- <dt>CaptureError error </dt>
- <dd>The error object of an unsuccessful capture asynchronous
- operation. </dd>
- </dl>
- </dd>
-</dl>
-</ section>< section
-id=captureerror>
-
-<h3><a>GalleryError</a> interface</h3>
-
-<p>The <a>GalleryError</a> interface encapsulates all errors in the Gallery
-API. </p>
-
-<p class="note">More error codes to be defined here. </p>
-<dl title="[NoInterfaceObject] interface CaptureError" class="idl">
- <dt>const unsigned short GALLERY_OPEN_ERRER = 0 </dt>
- <dd>Gallery is already open. </dd>
- <dt>const unsigned short GALLERY_NOT_OPEN_ERRER = 1 </dt>
- <dd>Gallery is not open.</dd>
- <dt>readonly attribute unsigned short code </dt>
- <dd>An error code assigned by an implementation when an error has occurred
- in Gallery API processing.</dd>
-</dl>
-</ section></
- section></
-section>< section id=pendingoperation>
-
-<h3><a>PendingOperation</a> interface</h3>
-
-<p class="note">This may be a general interface for use throughout all APIs.
-Included here for now for completion.</p>
-<dl title="[NoInterfaceObject] interface PendingOperation" class="idl">
- <dt>void cancel () </dt>
- <dd>Cancel/clear the pending asynchronous operation. </dd>
-</dl>
-</ section></
- section></
-section></ section>< section
-class=appendix>
-
-<h3>Requirements</h3>
-
-<p>The Gallery API: </p>
-<ul>
- <li>MUST enable listing all available gallery sources(e.g. specific
- directory, memory card, etc), their names and types</li>
- <li>MUST enable creating a new gallery</li>
- <li>MUST enable finding and deleting a gallery</li>
- <li>MUST enable finding a content item inside a gallery</li>
- <li>MUST enable adding, updating, and deleting a content item from a gallery
- </li>
- <li>MUST expose metadata about the gallery's content items (e.g. author,
- created date, copyright, media-dependent information, etc.)</li>
- <li>MUST enable filtering and ordering the list of content items according to
- various options (e.g. sorted by date)</li>
-</ul>
-</ section>< section>
-
-<h3>Use cases</h3>
-
-<p>This section contains a set of use cases collected for the Gallery API. Note
-that this section might be removed in future versions of the document. </p>
-
-<h4>Picture Capture and Picture upload</h4>
-
-<p>A (web-based) camera application that allow the user to capture image with
-and without preview mode using the device camera capability. Also allow the
-user to capture multiple images in burst mode and upload the image(s) to a
-server using XHR. </p>
-
-<div class="issue">
-<p>The image is returned as URI from captureImage() callback? How do we XHR
-upload? Do we need the FileAPI or is there a need to return the image (captured
-object) as binary data?</p>
-</div>
-
-<h4>Panorama Image Capture</h4>
-
-<p>A (web-based) camera application that allow the user to capture panorama
-images with and without preview mode using the device camera capability. When
-the user select panorama mode, the view finder displays an indication that it
-is ready to take the 1st image of 3. the user points the device starting from
-the left and presses the Take button. The device takes the image indicated by
-an alert, then goes back to take mode for the next image in the sequence. The
-view finder displays a 1/8 overlay of previous image on the left side so the
-user can line up for the next image. After taking all 3 images that makes up
-the panorama picture, the device displays the picture on the screen for a
-second before going back to the view finder mode. </p>
+<section id="abstract">This specification defines an Application Programming Interface (<acronym
+title="Application Programming Interface">API</acronym>) that provides access
+to media gallery in the device. A media gallery is a collection of media
+items,such as video, audio and image.
+</section>
-<h4>Video chat</h4>
+<section id="conformance">
+</section>
-<p>The use case is to be able to write a web app that implements a voice/video
-chat client. This could be as part of an instant messaging client, or might be
-a standalone videophone or 'telephone'. Another example might be an online
-'chat with customer service' link on the web site that downloaded the web app
-that allowed the customer to do this directly. </p>
+<section class="informative">
-<h5>Discussion</h5>
+ <h2>Introduction</h2>
+ <p>The Gallery API defines a high-level interface for accessing media gallery in the device.</p>
+ <section>
+ <h2>Usage Examples</h2>
+ <p>The following code extracts illustrate how to work with a gallery API in the device: </p>
-<p>Video output can be handled with the <code><video></code> tag.
-However, video input is not so easy as there is no obvious way to pass captured
-video in real time to the server. You might think that you could use the
-preview URL as proposed in one API as a way, but there is no obvious way to
-pass the data coming out of this URL down (for example) a websocket. </p>
+ <div>
+ <p>Opening the gallery and changing the view of gallery.</p>
+ <pre class="example sh_javascript_dom">
+
+ // Define the changeView success callback function.
+ function changeViewSuccess() {
+ alert("Gallery contains "+ myGallery.getNumofMediaObjects() + " images");
+ }
-<p>The approach of rendering the preview into a <code><canvas></code> and
-then scraping the canvas, re-encoding the data and transmitting it seems too
-ugly (and too inefficient) to be useful. The rendering approach also doesn't
-work for the associated audio stream. Worse, the preview data stream might not
-include the audio anyway. </p>
+ // Define the changeView failure callback function.
+ function changeViewFailure(e) {
+ alert("Cannot change gallery view");
+ }
-<p>An ideal approach would be to define a websocket like interface onto the
-camera/microphone (it might even be as simple as defining a method to get a web
-sockets URL for the camera/microphone). Another alternative (which would cause
-more upheaval) would be to add the websocket read/write interface onto
-XmlHttpRequest and then have the camera expose an HTTP URL for the full
-audio/video data stream. </p>
+ // Define the open Success callback function.
+ function openSuccess() {
+ alert("Gallery contains "+ myGallery.getNumofMediaObjects() + " media objects");
+ myGallery.changeView(changeViewSuccess, changeViewFailure, {filterItemType:gallery})
+ }
-<h4>Web cam</h4>
-<p>A (web-based) surveillance application that would allow the user to survey
-their property remotely. The camera would allow for some type of control such
-as moving the camera left, right, up and down. Another usage would allow for
-the surveillance web application to monitor for movement and trigger a
-notification such as email or alert to the user</p>
+ // Define the open Failure callback function.
+ function openFailure(e) {
+ alert("Cannot open the gallery");
+ }
-<h4>Voice search</h4>
+ // Open the gallery.
+ myGallery.open(openSuccess, openFailure);
+ </pre>
+ </div>
+ </section>
+</section>
+<section>
+ <h2>Security and Privacy Considerations</h2>
+ <p class="note"><strong>This section is under development.</strong> </p>
+ <p>The API defined in this specification can be used to add, update, find and delete media content 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.
+ </p>
+ <section>
+ <h2>Privacy considerations for implementers of Gallery API</h2>
-<p>A (web-based) search application might offer the user to speak the search
-query into the device, e.g. while holding a push-to-talk button or triggered by
-a proximity sensor (use case for sensor API). The users utterance has to be
-recorded (captured) and may be sent over the network to a network based speech
-recognizer. </p>
+ <p>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.
+ </p>
+ </section>
+</section>
+<section>
+ <h2>API Description</h2>
+ <section>
+ <h2><code>Gallery</code> interface</h2>
+ <p class="issue">The actual object of which the API will be hanging off is still under discussion (e.g. <code>navigator.service</code> vs from
+ <code>navigator.device</code>); see <a href="http://www.w3.org/2009/dap/track/issues/67">ISSUE-67</a></p>
-<h5>Discussion</h5>
+ <p>The <code>Gallery</code> interface exposes an interface to access media gallery in the device.</p>
+ <dl title="[Supplemental, NoInterfaceObject] interface Gallery" class="idl">
+ <dt>const unsigned short MEDIA_SORT_NONE = 0</dt>
+ <dd>Constant used to identify no sort ordering. </dd>
+ <dt>const unsigned short MEDIA_SORT_BY_FILENAME = 1</dt>
+ <dd>Constant used to identify sort by filename. </dd>
+ <dt>const unsigned short MEDIA_SORT_BY_FILEDATE = 2</dt>
+ <dd>Constant used to identify sort by file date. </dd>
+ <dt>const unsigned short MEDIA_SORT_BY_MEDIATYPE = 3</dt>
+ <dd>Constant used to identify sort by media type. </dd>
+ <dt>const unsigned short MEDIA_SORT_BY_TITLE = 0</dt>
+ <dd>Constant used to identify sort by title.</dd>
+ <dt>const unsigned short MEDIA_SORT_BY_AUTHOR = 1</dt>
+ <dd>Constant used to identify sort by author.</dd>
+ <dt>const unsigned short MEDIA_SORT_BY_ALBUM = 2</dt>
+ <dd>Constant used to identify sort by album. </dd>
+ <dt>const unsigned short MEDIA_SORT_BY_DATE = 3</dt>
+ <dd>Constant used to identify sort by date</dd>
+ <dt>const unsigned short MEDIA_SORT_BY_ASCENDING = 0</dt>
+ <dd>Constant used to identify ascending sort order.</dd>
+ <dt>const unsigned short MEDIA_SORT_BY_DESCENDING = 1</dt>
+ <dd>Constant used to identify ascending sort order. </dd>
+ <dt>readonly attribute GalleryProperties metadata</dt>
+ <dd>Generic metadata information regarding to the gallery.</dd>
+ <dt>Unsigned long getNumofMediaObjects () </dt>
+ <dd>Get the number of media objects in the gallery.</dd>
+ <dt>PendingOperation open () </dt>
+ <dd>Open the gallery in the device.
+ <p>This method takes two arguments. When called, it immediately returns a <a href="#pendingoperation-interface"><code>PendingOperation</code></a>
+ object and then asynchronously start a <em>open gallery</em> process defined as follows:</p>
+ <ol>
+ <li>Open the gallery. Allow application to access media contents of the gallery.</li>
+ <li>If successful, invoke the associated <code>successCB</code>. If the attempt fails, and the method was invoked with a non-null
+ <code>errorCallback</code> argument, this method must invoke the <code>errorCallback</code> with a <a
+ href="#captureerror-interface"><code>GalleryError</code></a> object as an argument. </li>
+ </ol>
+ <dl class="parameters">
+ <dt>GallerySuccessCB successCB </dt>
+ <dd>Function to call when the asynchronous operation completes </dd>
+ <dt>optional GalleryErrorCB errorCB </dt>
+ <dd>Function to call when the asynchronous operation fails. This
+ parameter is OPTIONAL.</dd>
+ </dl>
+ </dd>
+
+ <dt>PendingOperation refresh () </dt>
+ <dd>Refresh the content item(s) of gallery.
+ <p>This method takes two arguments. When called, it immediately returns a
+ <a href="#pendingoperation-interface"><code>PendingOperation</code></a>
+ object and then asynchronously start a <em>refresh gallery</em> process
+ defined as follows:</p>
-<p>To avoid latency while sending the captured voice sample to the network
-based speech recognizer, the voice should be recorded in a compressed format.
-The API should allow to select a compression format. </p>
+ <ol>
+ <li>Refresh the gallery. Apply the changes to the gallery (e.g. the
+ added or deleted content items)</li>
+ <li>If successful, invoke the associated <code>successCB</code>. If the
+ attempt fails, and the method was invoked with a non-null
+ <code>errorCallback</code> argument, this method must invoke the
+ <code>errorCallback</code> with a <a
+ href="#captureerror-interface"><code>GalleryError</code></a> object
+ as an argument. </li>
+ </ol>
+ <dl class="parameters">
+ <dt>GallerySuccessCB successCB </dt>
+ <dd>Function to call when the asynchronous operation completes </dd>
+ <dt>optional GalleryErrorCB errorCB</dt>
+ <dd>Function to call when the asynchronous operation fails. This
+ parameter is OPTIONAL.</dd>
+ </dl>
+ </dd>
-<h4>Voice memo</h4>
+ <dt>PendingOperation close () </dt>
+ <dd>Close the gallery in the device. Disallow application to access media contents of the gallery.
+ </dd>
-<p>A (web-based) voice recorder application which allow the user to record a
-memo for later playback.</p>
-</ section>< section
-id=related>
+ <dt>PendingOperation changeView () </dt>
+ <dd>Change the current view of the gallery
+ <p>This method takes three arguments. When called, it immediately returns
+ a <a href="#pendingoperation-interface"><code>PendingOperation</code></a>
+ object and then asynchronously start a <em>change view</em> process
+ defined as follows:</p>
+ <p></p>
+ <ol>
+ <li>Change the view style of the gallery.</li>
+ <li>If successful, invoke the associated <code>successCB</code>. If the
+ attempt fails, and the method was invoked with a non-null
+ <code>errorCallback</code> argument, this method must invoke the
+ <code>errorCallback</code> with a <a
+ href="#captureerror-interface"><code>GalleryError</code></a> object
+ as an argument. </li>
+ </ol>
+ <dl class="parameters">
+ <dt>GallerySuccessCB successCB </dt>
+ <dd>Function to call when the asynchronous operation completes </dd>
+ <dt>optional GalleryErrorCB errorCB </dt>
+ <dd>Function to call when the asynchronous operation fails. This
+ parameter is OPTIONAL</dd>
+ <dt>optional ViewStyle ViewOption </dt>
+ <dd>Describe details on the way to sort and filter media objects in
+ the new view. This parameter is OPTIONAL </dd>
+ <dd></dd>
+ </dl>
+ </dd>
-<h2>Related documents</h2>
+ <dt>MediaObjects getMediaObjects () </dt>
+ <dd>Retrieves the list of media object. Retrieves an array of Media Objects
+ from the gallery according to current view options. If no view has been
+ created, all items of the gallery are returned.
+ <p></p>
+ </dd>
+ <dt>MediaObject getMediaObject () </dt>
+ <dd>Retrieves the media object by id. The id of an media object never
+ changes while gallery is open.
+ <dl class="parameters">
+ <dt>Unsigned long objId </dt>
+ <dd>Unique numberic id of the media object to be retrieved. </dd>
+ </dl>
+ </dd>
+ </dl>
+ </section>
+ <section>
+ <h2><code>GalleryProperties</code> interface</h2>
+ <p><code>GalleryProperties</code> interface capture generic metadata information of a gallery.</p>
+ <p>More properties to be defined here.</p>
+ <dl title="[NoInterfaceObject] interface GalleryProperties" class="idl">
+ <dt>readonly attribute DOMString? title</dt>
+ <dd>The title of the gallery.</dd>
+ <dt>readonly attribute Date CreatedDate</dt>
+ <dd>The date and time the gallery was originally created.</dd>
+ </dl>
+ </section>
+ <section>
+ <h2><code>MediaObject</code> interface</h2>
+ <p><code>MediaObject</code> 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.</p>
-<p>The API described in this document took inspiration from the following
-documents:</p>
-<ul>
- <li><a href="http://bondi.omtp.org/1.0/apis/gallery.html" name="BONDI"
- id="BONDI">BONDI 1.1 Gallery API</a> </li>
-</ul>
-</ section>< section id=future>
+ <dl title="[NoInterfaceObject] interface MediaObject" class="idl">
+ <dt>const unsigned short MEDIA_OBJ_TYPE_UNDEFINED = 0</dt>
+ <dd>Constant use to identify an undefined MediaObject. </dd>
+ <dt>const unsigned short MEDIA_OBJ_TYPE_VIDEO = 1 </dt>
+ <dd>Constant use to identify a video MediaObject.</dd>
+ <dt>const unsigned short MEDIA_OBJ_TYPE_AUDIO = 2</dt>
+ <dd>Constant use to identify an audio MediaObject.</dd>
+ <dt>const unsigned short MEDIA_OBJ_TYPE_IMAGE = 3</dt>
+ <dd>Constant use to identify an image MediaObject.</dd>
+ <dt>readonly attribute unsigned long id</dt>
+ <dd>Unique id of media object. This id is a unique numeric identifiers of
+ the object. This id is persistent while the gallery is opened.</dd>
+ <dt>readonly attribute unsigned long type</dt>
+ <dd>Type of media object.</dd>
+ <dt>readonly attribute unsigned DOMString mimeType</dt>
+ <dd>Mimetype of the media file.</dd>
+ <dt>readonly attribute unsigned DOMString filename</dt>
+ <dd>The name of the file corresponding to this object.</dd>
+ <dt>readonly attribute MediaObjectProperties metadata</dt>
+ <dd>metadata associated to the media object.</dd>
+ </dl>
+ </section>
+ <section>
+ <h2><code>MediaObjectProperties</code> interface</h2>
+ <p><code>MediaObjectProperties</code> interface capture generic metadata information of a media object.</p>
+ <p>More properties to be defined here.</p>
+ <dl title="[NoInterfaceObject] interface MediaObjectProperties" class="idl">
+ <dt>readonly attribute DOMString? title</dt>
+ <dd>The title of the media object.</dd>
+ <dt>readonly attribute DOMString? author</dt>
+ <dd>The author of the media object.</dd>
+ <dt>readonly attribute DOMString? description</dt>
+ <dd>A textual description of the media object.</dd>
+ <dt>readonly attribute DOMString? keyword</dt>
+ <dd>A descriptive phrase or keyword that specify the topic of the media
+ object.</dd>
+ <dt>readonly attribute DOMString? copyright</dt>
+ <dd>The copyright statement. Identification of the copyrights holder.</dd>
+ <dt>readonly attribute Date CreatedDate</dt>
+ <dd>The date and time the media object was originally created.</dd>
+ </dl>
+ </section>
+ <section>
+ <h2><code>ViewType</code> interface</h2>
+ <p><code>ViewType</code> interface offer the way to describe how gallery is displayed.</p>
+ <dl title="[NoInterfaceObject] interface ViewType" class="idl">
+ <dt>attribute short order </dt>
+ <dd>Specify wheither media objects are ordered in ascending or descending
+ order. </dd>
+ <dt>attribute short firstViewOption</dt>
+ <dd>Primary criteria to order the media object of the gallery.</dd>
+ <dt>attribute short secondViewOption</dt>
+ <dd>Second criteria to order the media object of the gallery.</dd>
+ <dt>attribute Data startDate </dt>
+ <dd>Start date for performing the search. Media object with date previous
+ to that date will not be returned.</dd>
+ <dt>attribute Data endDate</dt>
+ <dd>End date for performing the search. Media object with date later to
+ that date will not be returned.</dd>
+ <dt>attribute DOMString metaTag </dt>
+ <dd>String to be searched in the metadata of media object on the
+ gallery.</dd>
+ </dl>
+ </section>
-<h2>Features for Future Consideration</h2>
+ <section>
+ <h2><code>GallerySuccessCB</code> interface</h2>
+ <dl title="[Callback=FunctionOnly, NoInterfaceObject] interface GallerySuccessCB" class="idl">
+ <dt>void onSuccess ()</dt>
+ <dd>Callback function issued when the upper function is correctly finished.</dd>
+ </dl>
+ </section>
+ <section>
+ <h2><code>MediaObjects</code> typedef</h2>
+
+ <p>The <code>MediaObjects</code> typedef represents a <code>sequence</code> of <a href="#mediaobject"><code>MediaObject</code></a> objects.</p>
+ <dl title="typedef sequence<MediaObject> MediaObjects" class="idl">
+ </dl>
+ </section>
+ <section>
+ <h2><code>GalleryErrorCB</code> interface</h2>
+ <dl title="[Callback=FunctionOnly, NoInterfaceObject] interface GalleryErrorCB" class="idl">
+ <dt>void onError () </dt>
+ <dd><dl class="parameters">
+ <dt>GalleryErrorCB error </dt>
+ <dd>The error object of an unsuccessful capture asynchronous operation. </dd>
+ </dl>
+ </dd>
+ </dl>
+ </section>
+ <section>
+ <h2><code>GalleryError</code> interface</h2>
+ <p>The <code>GalleryError</code> interface encapsulates all errors in the Gallery API.</p>
+
+ <p class="note">More error codes to be defined here. </p>
+ <dl title="[NoInterfaceObject] interface GalleryError" class="idl">
+ <dt>const unsigned short GALLERY_OPEN_ERRER = 0 </dt>
+ <dd>Gallery is already open. </dd>
+ <dt>const unsigned short GALLERY_NOT_OPEN_ERRER = 1 </dt>
+ <dd>Gallery is not open.</dd>
+ <dt>readonly attribute unsigned short code </dt>
+ <dd>An error code assigned by an implementation when an error has occurred
+ in Gallery API processing.</dd>
+ </dl>
+ </section>
-<p>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. </p>
-<ul>
- <li>... </li>
-</ul>
-</ section>< section id=ack>
+ <section>
+ <h2><code>PendingOperation</code> interface</h2>
+ <p class="note">This may be a general interface for use throughout all APIs. Included here for now for completion.</p>
+ <dl title="[NoInterfaceObject] interface PendingOperation" class="idl">
+ <dt>void cancel ()</dt>
+ <dd>Cancel/clear the pending asynchronous operation. </dd>
+ </dl>
+ </section>
+</section>
-<h2>Acknowledgements</h2>
+<section>
+ <h2>Use Cases and Requirements</h2>
+ <section>
+ <h2>Use Cases</h2>
+ <p>
+ <h4 id='uc1'>Use Case 1: TBD.
+ </p>
+ <p>
+ <h4 id='uc2'>Use Case 2: TBD.
+ </p>
+ </section>
+ <section>
+ <h2>Requirements</h2>
+ <p>The Gallery API: </p>
+ <ul>
+ <li>MUST enable listing all available gallery sources(e.g. specific
+ directory, memory card, etc), their names and types</li>
+ <li>MUST enable creating a new gallery</li>
+ <li>MUST enable finding and deleting a gallery</li>
+ <li>MUST enable finding a content item inside a gallery</li>
+ <li>MUST enable adding, updating, and deleting a content item from a gallery
+ </li>
+ <li>MUST expose metadata about the gallery's content items (e.g. author,
+ created date, copyright, media-dependent information, etc.)</li>
+ <li>MUST enable filtering and ordering the list of content items according to
+ various options (e.g. sorted by date)</li>
+ </ul>
+ </section>
+</section>
-<p>Many thanks to OMTP BONDI who provided the initial input into this
-specification. </p>
-</ section></body>
+<section class=appendix>
+ <h2>Related documents</h2>
+ <p>The API described in this document took inspiration from the following documents:</p>
+ <ul>
+ <li><a href="http://bondi.omtp.org/1.0/apis/gallery.html" name="BONDI" id="BONDI">BONDI 1.1 Gallery API</a> </li>
+ </ul>
+</section>
+<section>
+ <h2>Features for Future Consideration</h2>
+ <p>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. </p>
+ <ul>
+ <li>...</li>
+ </ul>
+</section>
+<section class=appendix>
+ <h2>Acknowledgements</h2>
+ <p>Many thanks to OMTP BONDI who provided the initial input into this specification.</p>
+</section>
+</body>
</html>
Received on Wednesday, 17 March 2010 02:27:32 UTC