- From: WonSuk Lee via cvs-syncmail <cvsmail@w3.org>
- Date: Wed, 17 Mar 2010 00:02:48 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/gallery
In directory hutz:/tmp/cvs-serv28899/2009/dap/gallery
Modified Files:
Overview.html
Log Message:
minor modification
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/gallery/Overview.html,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -d -r1.2 -r1.3
--- Overview.html 14 Sep 2009 15:36:05 -0000 1.2
+++ Overview.html 17 Mar 2010 00:02:46 -0000 1.3
@@ -19,37 +19,499 @@
</script>
<script src='../common/config.js' class='remove'></script>
</head>
- <body>
- <section id='abstract'>
- This is the abstract for your specification.
- </section>
-
- <section id='conformance'></section>
-
- <section>
- <h2>Requirements</h2>
- <p>
- ...
- </p>
- </section>
-
- <section class='appendix'>
- <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>
- ...
- </p>
- </section>
- </body>
+<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>
+
+<h4>Video chat</h4>
+
+<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>
+
+<h5>Discussion</h5>
+
+<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>
+
+<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>
+
+<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>
+
+<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>
+
+<h4>Voice search</h4>
+
+<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>
+
+<h5>Discussion</h5>
+
+<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>
+
+<h4>Voice memo</h4>
+
+<p>A (web-based) voice recorder application which allow the user to record a
+memo for later playback.</p>
+</ section>< section
+id=related>
+
+<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 id=future>
+
+<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 id=ack>
+
+<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 00:02:50 UTC