2009/dap/gallery Overview.html,1.4,1.5

Update of /sources/public/2009/dap/gallery
In directory hutz:/tmp/cvs-serv9800/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.4
retrieving revision 1.5
diff -u -d -r1.4 -r1.5
--- Overview.html	17 Mar 2010 02:27:28 -0000	1.4
+++ Overview.html	18 Mar 2010 06:51:05 -0000	1.5
@@ -28,9 +28,7 @@
 
 <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. 
+title="Application Programming Interface">API</acronym>) that provides access to media gallery located on the device.
 </section>
 
 <section id="conformance">
@@ -39,11 +37,11 @@
 <section class="informative">
 
 	<h2>Introduction</h2>
-	<p>The Gallery API defines a high-level interface for accessing media gallery in the device.</p>
+	<p>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. </p>
 	<section>
 		<h2>Usage Examples</h2>
+		<p class="note">Further examples are required to give better understanding concerning the overall functions of the gallery API. </p>
 		<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>
 			<pre class="example sh_javascript_dom">
@@ -61,10 +59,9 @@
           // Define the open Success callback function.
           function openSuccess() {
                 alert("Gallery contains "+ myGallery.getNumofMediaObjects() + " media objects");
-                myGallery.changeView(changeViewSuccess, changeViewFailure, {filterItemType:gallery})
+                myGallery.changeView(changeViewSuccess, changeViewFailure, {order:gallery.MEDIA_SORT_BY_DESCENDING, firstViewOption:gallery.MEDIA_SORT_BY_FILEDATE})
           }
 
-
           // Define the open Failure callback function.
           function openFailure(e) {
                 alert("Cannot open the gallery");
@@ -79,7 +76,7 @@
 <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
+	<p>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.
 	</p>
@@ -94,12 +91,24 @@
 <section>
 	<h2>API Description</h2>
 	<section>
+		<h2><code>Galleries</code> interface</h2>
+		<p class="note"> More functions could be taked into account. e.g. How about finding function to the all galleries on the device? </p>
+		<p><code>Galleries</code> interface offer access to the list of Media Galleries on the device. The number of galleries is dependent on the implementation. 
+			As an example, in a window mobile implementation it might retrieve the gallery located in the directory "\My Documents" and another on located on the memory card.</p>
+		
+
+		<dl title="[NoInterfaceObject] interface Galleries" class="idl">
+		  <dt>MediaGalleries getGalleries() </dt>
+		    <dd>Retrieve all galleries located on the device. </dd>
+		</dl>		
+	</section>	
+	<section id="gallery">
 		<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>
 
-		<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">
+		<p>The <code>Gallery</code> interface exposes an interface to access media gallery located on the device.</p>
+		<dl title="[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>
@@ -124,60 +133,58 @@
 		    <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>
+		  <dt>PendingOp 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>This method takes two arguments. When called, it immediately returns a <code>PendingOp</code> object, as defined in
+      [[!CORE-DEVICE]] 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>Open the gallery. Allow application to access media objects 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>
+			          href="#galleryerror-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>
+			        <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
+		  <dt>PendingOp refresh () </dt>
+		    <dd>Refresh the media object(s) of gallery. 
+		      <p>This method takes two arguments. When called, it immediately returns a <code>PendingOp</code> object , as defined in
+      [[!CORE-DEVICE]] and then asynchronously start a <em>refresh gallery</em> process
 		      defined as follows:</p>
 
 		      <ol>
 		        <li>Refresh the gallery. Apply the changes to the gallery (e.g. the
-		          added or deleted content items)</li>
+		          added or deleted media object(s))</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
+		          href="#galleryerror-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>
+		        <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. 
+		  <dt>PendingOp close () </dt>
+		    <dd>Close the gallery in the device. Disallow application to access media objects of the gallery. 
 		    </dd>
 
-		  <dt>PendingOperation changeView () </dt>
+		  <dt>PendingOp 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
+		      <p>This method takes three arguments. When called, it immediately returns a <code>PendingOp</code> object, as defined in
+      [[!CORE-DEVICE]] and then asynchronously start a <em>change view</em> process
 		      defined as follows:</p>
 		      <p></p>
 		      <ol>
@@ -186,19 +193,18 @@
 		          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
+		          href="#galleryerror-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>
+		        <dt>optional GalleryErrorCB? errorCB </dt>
 		          <dd>Function to call when the asynchronous operation fails. This
 		            parameter is OPTIONAL</dd>
-		        <dt>optional ViewStyle ViewOption </dt>
+		        <dt> optional ViewType 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>
+		            the new view.</dd>
 		      </dl>
 		    </dd>
 
@@ -212,7 +218,7 @@
 		    <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>
+		        <dt>unsigned long objectId </dt>
 		          <dd>Unique numberic id of the media object to be retrieved. </dd>
 		      </dl>
 		    </dd>		    
@@ -221,18 +227,24 @@
 	<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>
+		<p class="note">More properties could be taken into account.</p>
 		<dl title="[NoInterfaceObject] interface GalleryProperties" class="idl">
-		  <dt>readonly attribute DOMString? title</dt>
+		  <dt>readonly attribute DOMString title</dt>
 		    <dd>The title of the gallery.</dd>
-		  <dt>readonly attribute Date CreatedDate</dt>
+		  <dt>readonly attribute Date createdDate</dt>
 		    <dd>The date and time the gallery was originally created.</dd>
+		  <dt>readonly attribute DOMString location</dt>
+		    <dd>The location the gallery is located on.</dd>
+		  <dt>readonly attribute DOMString[] supportedMediaObjectType</dt>
+		    <dd>A list of media object type supported by this gallery.</dd>		    		    
 		</dl>
 	</section>
-	<section>
+	<section id="mediaobject">
 		<h2><code>MediaObject</code> interface</h2>
+		<p class="note"> The adding, updating, finding and deleting functions of media object should be defined</p>
 		<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 MediaObject" class="idl">
 		  <dt>const unsigned short MEDIA_OBJ_TYPE_UNDEFINED = 0</dt>
@@ -259,7 +271,7 @@
 	<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>
+		<p class="note">More properties could be taken into account.</p>
 		<dl title="[NoInterfaceObject] interface MediaObjectProperties" class="idl">
 		  <dt>readonly attribute DOMString? title</dt>
 		    <dd>The title of the media object.</dd>
@@ -298,33 +310,39 @@
 		    gallery.</dd>
 		</dl>
 	</section>
-
-	<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>
+	<section id="mediagalleries-typedef">
+		<h2><code>MediaGalleries</code> typedef</h2>
+	
+		<p>The <code>MediaGalleries</code> typedef represents a <code>sequence</code> of <a href="#gallery"><code>Gallery</code></a>.</p>
+		<dl title="typedef sequence&lt;Gallery&gt; Gallery" class="idl">
+		</dl>
+	</section>	
+	<section id="mediaobjects-typedef">
 		<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>
+		<p>The <code>MediaObjects</code> typedef represents a <code>sequence</code> of <a href="#mediaobject"><code>MediaObject</code></a>.</p>
 		<dl title="typedef sequence&lt;MediaObject&gt; MediaObjects" class="idl">
 		</dl>
 	</section>
-	<section>
+	<section id="galleryerror-interface">
 		<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>
+		          <dd>The error object of an unsuccessful asynchronous operation. </dd>
 		      </dl>
 		    </dd>
 		</dl>		
 	</section>
 	<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>GalleryError</code> interface</h2>
 		<p>The <code>GalleryError</code> interface encapsulates all errors in the Gallery API.</p>
 		
@@ -340,14 +358,6 @@
 		</dl>		
 	</section>
 
-	<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>
 
 <section>
@@ -367,14 +377,14 @@
 			<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>MUST enable creating a new gallery?</li>
+			  <li>MUST enable finding and deleting a gallery?</li>
+			  <li>MUST enable finding a media object inside a gallery</li>
+			  <li>MUST enable adding, updating, and deleting a media object from a gallery
 			  </li>
-			  <li>MUST expose metadata about the gallery's content items (e.g. author,
+			  <li>MUST expose metadata about the gallery's media object (e.g. author,
 			    created date, copyright, media-dependent information, etc.)</li>
-			  <li>MUST enable filtering and ordering the list of content items according to
+			  <li>MUST enable filtering and ordering the list of media object according to
 			    various options (e.g. sorted by date)</li>
 			</ul>
 		</section>		

Received on Thursday, 18 March 2010 06:51:09 UTC