- From: Robin Berjon via cvs-syncmail <cvsmail@w3.org>
- Date: Mon, 05 Oct 2009 14:35:07 +0000
- To: public-dap-commits@w3.org
Update of /sources/public/2009/dap/api-reqs
In directory hutz:/tmp/cvs-serv17933/api-reqs
Modified Files:
Overview.html
Log Message:
intro; made all pool+Bryan editors as that reflects reality better; cleaned up and filled out all reqs up to Messaging
Index: Overview.html
===================================================================
RCS file: /sources/public/2009/dap/api-reqs/Overview.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -d -r1.5 -r1.6
--- Overview.html 2 Oct 2009 09:59:25 -0000 1.5
+++ Overview.html 5 Oct 2009 14:35:05 -0000 1.6
@@ -1,28 +1,26 @@
<!DOCTYPE html>
<html>
<head>
- <title>DAP API Requirements</title>
+ <title>Device APIs Requirements</title>
<meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
<script src='../ReSpec.js/js/respec.js' class='remove'></script>
<script class='remove'>
var respecConfig = {
- specStatus: "ED",
+ specStatus: "WG-NOTE",
shortName: "dap-api-reqs",
// publishDate: "2009-08-06",
// previousPublishDate: "1977-03-15",
edDraftURI: "http://dev.w3.org/2009/dap/api-reqs/",
// lcEnd: "2009-08-05",
- extraCSS: ["../ReSpec.js/css/respec.css"],
- editors: [
- { name: "Bryan Sullivan",
- company: "AT&T",
- companyURL: "http://att.com/" }],
- wg: "Device APIs and Policy Working Group",
- wgURI: "http://www.w3.org/2009/dap/",
- wgPublicList: "public-device-apis",
- wgPatentURI: "http://www.w3.org/2004/01/pp-impl/43696/status",
};
</script>
+ <script src='../common/config.js' class='remove'></script>
+ <script class='remove'>
+ respecConfig.editors.splice(-1, 0,
+ { name: "Bryan Sullivan",
+ company: "AT&T",
+ companyURL: "http://att.com/" })
+ </script>
</head>
<body>
<section id='abstract'>
@@ -30,309 +28,349 @@
all APIs and to each one individually.
</section>
+ <section class='informative'>
+ <h2>Introduction</h2>
+ <p>
+ The requirements in this document are produced in a high-level, functionally oriented
+ fashion in order to provide sufficient ground on which to build without going through
+ the full landscape analysis process given that the APIs being produced concern domains
+ in which industry experience is already solid.
+ </p>
+ <p>
+ This document is not currently considered to be complete, but rather represents a
+ snapshot of the DAP WG's thinking at the time of its publication.
+ </p>
+ </section>
+
<section>
- <h2>Requirements</h2>
+ <h2>Global Requirements</h2>
<p>
- ...
+ These requirements apply to all APIs produced by the DAP WG.
</p>
+ <ul>
+ <li>APIs MUST be made available in a consistent fashion, hanging off a single access point</li>
+ <li>methods that may take a long time to complete MUST support asynchronous, cancellable operation</li>
+ </ul>
+ <p class='issue'>
+ Should the APIs be made available on <code>navigator</code>, <code>navigator.device</code>,
+ or straight off a <code>window.device</code>?
+ </p>
+ </section>
- <section>
- <h2>Global Requirements</h2>
- <p>
- @@TBD
- </p>
- <ul>
- <li>methods that may take a long time to complete MUST support asynchronous, cancellable operation</li>
- </ul>
- </section>
+ <section>
+ <h2>Application Configuration</h2>
+ <p>
+ Due to overlapping with Widgets: The widget Interface [[WIDGETS-APIS]] and with
+ Web Storage [[WEBSTORAGE]], this deliverable has been dropped.
+ </p>
+ </section>
+ <section>
+ <h2>Application Launcher</h2>
+ <p>
+ The following requirements have been expressed.
+ </p>
+ <ol>
+ <li>
+ A User Agent MAY provide means for non-web applications to register themselves as handlers for
+ media types and URI schemes. (Note that this may be outside the scope of this API.)
+ </li>
+ <li>It SHOULD be possible to launch an application for which no media type or protocol handler exists</li>
+ <li>It SHOULD be possible to pass arguments to a launched application</li>
+ <li>It SHOULD be possible to launch an application asynchronously</li>
+ <li>It SHOULD be possible to launch an application synchronously</li>
+ <li>For applications that run synchronously, it SHOULD be possible to catch the output streams (STDOUT/ERR etc.)</li>
+ </ol>
+ <p>
+ The following requirements, while they could be considered to be functionally part of this API,
+ are already addressed as part of the HTML5 [[HTML5]]
+ <a href='http://www.w3.org/TR/html5/browsers.html#custom-handlers'>Custom scheme and content handlers</a>:
+ </p>
+ <ol>
+ <li>MUST enable (web) applications to register themselves as handlers for a specific protocol</li>
+ <li>A User Agent MAY provide default handlers for a specific protocol</li>
+ <li>MUST enable (web) applications to register themselves as handlers for a specific media type</li>
+ <li>A User Agent MAY provide default handlers for a specific media type</li>
+ </ol>
<section>
- <h2>Application Configuration</h2>
+ <h2>May be considered in future versions</h2>
<p>
- Due to overlapping with Widgets: The widget Interface [[WIDGETS-APIS]] and with
- Web Storage [[WEBSTORAGE]], this deliverable has been dropped.
+ Nothing listed at this time.
</p>
</section>
+ </section>
- <section>
- <h2>Application Launcher</h2>
- <p>
- @@TBD, still under discussion as part of <a href='http://www.w3.org/2009/dap/track/issues/6'>ISSUE-6</a>.
- </p>
- <section>
- <h2>May be considered in future versions</h2>
- <p>
- @@TBD
- </p>
- </section>
- </section>
- <section>
- <h2>Calendar</h2>
+
+ <section>
+ <h2>Calendar</h2>
+ <p>
+ This interface:
+ </p>
+ <ul>
+ <li>MUST enable listing multiple available calendars;</li>
+ <li>MUST expose some basic properties of calendars such as default time zone, name, etc.;</li>
+ <li>MUST enable creating, deleting, and updating calendars;</li>
+ <li>MUST enable creating, deleting, updating, and finding calendar events;</li>
+ <li>MUST expose calendar event properties with a 1:1 mapping to iCalendar [[!RFC5545]] properties and values</li>
+ </ul>
+ <div class='issue'>
<p>
- This interface:
+ The above suggests support for only VEVENT. However Andrew McMillan makes the following point:
</p>
+ <blockquote>
+ "Given that the differences between VEVENT & VTODO are trivial in comparison to the
+ complexity of their common elements, and that VJOURNAL is entirely a subset of those,
+ it seems to me there is very little to gain by removing VTODO and VJOURNAL from this specification.
+ Removal might restrict clients from implementing some potentially useful functionality.
+ The other supporting components of the specification like VALARM and VTIMEZONE seem to me so essential
+ in any reasonable implementation of VEVENT that they don't even merit discussion."
+ </blockquote>
+ </div>
+ <section>
+ <h2>May be considered in future versions</h2>
<ul>
- <li>MUST enable listing multiple available calendars;</li>
- <li>MUST expose some basic properties of calendars such as default time zone, name, etc.;</li>
- <li>MUST enable creating, deleting, and updating calendars;</li>
- <li>MUST enable creating, deleting, updating, and finding calendar events;</li>
- <li>MUST expose calendar event properties with a 1:1 mapping to iCalendar [[!RFC5545]] properties and values</li>
+ <li>iCalendar parsing and serialision</li>
+ <li>hCalendar parsing and serialision</li>
+ <li>calendar diffs</li>
+ <li>direct CalDAV access</li>
</ul>
- <div class='issue'>
- <p>
- The above suggests support for only VEVENT. However Andrew McMillan makes the following point:
- </p>
- <blockquote>
- "Given that the differences between VEVENT & VTODO are trivial in comparison to the
- complexity of their common elements, and that VJOURNAL is entirely a subset of those,
- it seems to me there is very little to gain by removing VTODO and VJOURNAL from this specification.
- Removal might restrict clients from implementing some potentially useful functionality.
- The other supporting components of the specification like VALARM and VTIMEZONE seem to me so essential
- in any reasonable implementation of VEVENT that they don't even merit discussion."
- </blockquote>
- </div>
- <section>
- <h2>May be considered in future versions</h2>
- <ul>
- <li>iCalendar parsing and serialision</li>
- <li>hCalendar parsing and serialision</li>
- <li>calendar diffs</li>
- <li>direct CalDAV access</li>
- </ul>
- </section>
</section>
+ </section>
- <section>
- <h2>Camera</h2>
+ <section>
+ <h2>Camera</h2>
+ <p>
+ The Camera API:
+ </p>
+ <ul>
+ <li>MUST enable capture of static images</li>
+ <li>MUST enable capture of videos</li>
+ <li>MUST enable listing the available cameras</li>
+ <li>MUST enable listing the available formats and codecs, per camera</li>
+ <li>MUST enable retrieval of the captured content</li>
+ <li>MUST provide some metadata about the captured content (e.g. width, height, format, duration)</li>
+ <li>MUST enable choosing preferred aspects of the captured content (e.g. width, height, format, frame rate)</li>
+ <li>MUST enable displaying a viewfinder</li>
+ <li>MUST support asynchronous, cancellable capture</li>
+ <li>SHOULD enable displaying a viewfinder as part of the document (e.g. as a <code>video</code> element [[HTML5]])</li>
+ <li>SHOULD enable control of the camera's capabilities (e.g. zoom, luminosity, night mode, focus mode)</li>
+ </ul>
+ <p class='issue'>
+ Given support for capturing video, we need to take sound capture into account. Once that's supported,
+ is there any reason not to support capturing sound on its own? If we go there, isn't this a Capture API,
+ with the ability to list mikes?
+ </p>
+ <div class='issue'>
<p>
- The Camera API:
- </p>
- <ul>
- <li>MUST enable capture of static images</li>
- <li>MUST enable capture of videos</li>
- <li>MUST enable listing the available cameras</li>
- <li>MUST enable listing the available formats and codecs, per camera</li>
- <li>MUST enable retrieval of the captured content</li>
- <li>MUST provide some metadata about the captured content (e.g. width, height, format, duration)</li>
- <li>MUST enable choosing preferred aspects of the captured content (e.g. width, height, format, frame rate)</li>
- <li>MUST enable displaying a viewfinder</li>
- <li>MUST support asynchronous, cancellable capture</li>
- <li>SHOULD enable displaying a viewfinder as part of the document (e.g. as a <code>video</code> element [[HTML5]])</li>
- <li>SHOULD enable control of the camera's capabilities (e.g. zoom, luminosity, night mode, focus mode)</li>
- </ul>
- <p class='issue'>
- Given support for capturing video, we need to take sound capture into account. Once that's supported,
- is there any reason not to support capturing sound on its own? If we go there, isn't this a Capture API,
- with the ability to list mikes?
+ If the user requests a given capture size which isn't available, do we refuse or do we fall back? If the
+ latter (which is likely) what is the algorithm that is used to find the fallback? It could be (given a request
+ for 1000x50):
+ <ul>
+ <li>the camera's preferred default</li>
+ <li>500x100 (closest number of pixels)</li>
+ <li>1000x700 (closest longest side)</li>
+ <li>2000x100 (closest ratio)</li>
+ </ul>
</p>
- <div class='issue'>
- <p>
- If the user requests a given capture size which isn't available, do we refuse or do we fall back? If the
- latter (which is likely) what is the algorithm that is used to find the fallback? It could be (given a request
- for 1000x50):
- <ul>
- <li>the camera's preferred default</li>
- <li>500x100 (closest number of pixels)</li>
- <li>1000x700 (closest longest side)</li>
- <li>2000x100 (closest ratio)</li>
- </ul>
- </p>
- </div>
- <p class='issue'>
- We could very easily get bogged down in specifying camera capabilities and format feature variants —
- how do we decide which ones are reasonably in?
+ </div>
+ <p class='issue'>
+ We could very easily get bogged down in specifying camera capabilities and format feature variants —
+ how do we decide which ones are reasonably in?
+ </p>
+ <section>
+ <h2>May be considered in future versions</h2>
+ <p>
+ Nothing listed at this time.
</p>
- <section>
- <h2>May be considered in future versions</h2>
- <p>
- Nothing listed at this time.
- </p>
- </section>
</section>
+ </section>
+ <section>
+ <h2>Communications Log</h2>
+ <p>
+ This interface:
+ </p>
+ <ol>
+ <li>MUST be able to provide a list of incoming and outgoing communication events</li>
+ <li>MUST be able to search for events by type (email, phone, SMS...) as well as by content</li>
+ <li>MUST be able to expose relevant metadata about events (start and end time, to and from, etc.)</li>
+ </ol>
<section>
- <h2>Communications Log</h2>
+ <h2>May be considered in future versions</h2>
<p>
- @@TBD Discussed as <a href='http://www.w3.org/2009/dap/track/issues/9'>ISSUE-9</a>,
+ Nothing listed at this time.
</p>
- <section>
- <h2>May be considered in future versions</h2>
- <p>
- @@TBD
- </p>
- </section>
</section>
+ </section>
+ <section>
+ <h2>Contacts</h2>
+ <p>
+ The Contacts API:
+ </p>
+ <ul>
+ <li>MUST enable listing all available address books on the device</li>
+ <li>MUST enable listing all contacts in the address book(s)</li>
+ <li>MUST enable reading the details for a contact</li>
+ <li>SHOULD enable creating a new contact</li>
+ <li>SHOULD enable updating a contact</li>
+ <li>SHOULD enable deleting a contact</li>
+ <li>SHOULD enable filtering the list of contacts to search for a subset</li>
+ </ul>
+ <p class='issue'>
+ Are there convincing use cases for supporting multiple address books in v1 (as opposed to just
+ a default one, and maybe exposing more later)?
+ </p>
+ <p class='issue'>
+ Do we need support for groups in v1?
+ </p>
<section>
- <h2>Contacts</h2>
+ <h2>May be considered in future versions</h2>
<p>
- The Contacts API:
- </p>
- <ul>
- <li>MUST enable listing all available address books on the device</li>
- <li>MUST enable listing all contacts in the address book(s)</li>
- <li>MUST enable reading the details for a contact</li>
- <li>SHOULD enable creating a new contact</li>
- <li>SHOULD enable updating a contact</li>
- <li>SHOULD enable deleting a contact</li>
- <li>SHOULD enable filtering the list of contacts to search for a subset</li>
- </ul>
- <p class='issue'>
- Are there convincing use cases for supporting multiple address books in v1 (as opposed to just
- a default one, and maybe exposing more later)?
- </p>
- <p class='issue'>
- Do we need support for groups in v1?
+ Nothing listed at this time.
</p>
- <section>
- <h2>May be considered in future versions</h2>
- <p>
- Nothing listed at this time.
- </p>
- </section>
</section>
+ </section>
+ <section>
+ <h2>File System</h2>
+ <p>
+ The File System API:
+ </p>
+ <ul>
+ <li>MUST integrate with the W3C File API [[FILE-UPLOAD]]</li>
+ <li>MUST enable listing items in a directory</li>
+ <li>MUST enable creating a file or directory</li>
+ <li>MUST enable deleting a file or directory</li>
+ <li>MUST enable writing to a file</li>
+ <li>MUST enable appending to a file</li>
+ <li>MUST enable getting some metadata about a file (e.g. size, creation and update time, media type)</li>
+ <li>MAY enable setting some metadata on a file</li>
+ <li>SHOULD enable copying files and directories</li>
+ <li>SHOULD enable moving files and directories</li>
+ <li>MUST handle text encoding conversion when reading and writing to file (at least UTF-8 and UTF-16 LE/BE)</li>
+ <li>SHOULD support binary access to file content</li>
+ <li>MUST enable navigating a directory tree</li>
+ <li>MUST reflect file system paths using a normalised separator (/) and in a consistent encoding</li>
+ <li>MAY provide conversion between paths and <code>file:</code> URLs</li>
+ <li>MAY support reading and writing in Base64 (or using <code>data:</code> URLs)</li>
+ <li>SHOULD support reading lines from a text document</li>
+ <li>SHOULD support events for detecting the mounting/unmounting of a file system (e.g. to detect a memory card being plugged in)</li>
+ <li>MUST support listing the available file systems</li>
+ <li>SHOULD provide access to a temporary storage location (a form of /tmp directory)</li>
+ <li>MUST provide some file system metadata (e.g. size, available space, quota)</li>
+ </ul>
<section>
- <h2>File System</h2>
+ <h2>May be considered in future versions</h2>
<p>
- The File System API:
+ Nothing listed at this time.
</p>
- <ul>
- <li>MUST integrate with the W3C File API [[FILE-UPLOAD]]</li>
- <li>MUST enable listing items in a directory</li>
- <li>MUST enable creating a file or directory</li>
- <li>MUST enable deleting a file or directory</li>
- <li>MUST enable writing to a file</li>
- <li>MUST enable appending to a file</li>
- <li>MUST enable getting some metadata about a file (e.g. size, creation and update time, media type)</li>
- <li>MAY enable setting some metadata on a file</li>
- <li>SHOULD enable copying files and directories</li>
- <li>SHOULD enable moving files and directories</li>
- <li>MUST handle text encoding conversion when reading and writing to file (at least UTF-8 and UTF-16 LE/BE)</li>
- <li>SHOULD support binary access to file content</li>
- <li>MUST enable navigating a directory tree</li>
- <li>MUST reflect file system paths using a normalised separator (/) and in a consistent encoding</li>
- <li>MAY provide conversion between paths and <code>file:</code> URLs</li>
- <li>MAY support reading and writing in Base64 (or using <code>data:</code> URLs)</li>
- <li>SHOULD support reading lines from a text document</li>
- <li>SHOULD support events for detecting the mounting/unmounting of a file system (e.g. to detect a memory card being plugged in)</li>
- <li>MUST support listing the available file systems</li>
- <li>SHOULD provide access to a temporary storage location (a form of /tmp directory)</li>
- <li>MUST provide some file system metadata (e.g. size, available space, quota)</li>
- </ul>
- <section>
- <h2>May be considered in future versions</h2>
- <p>
- Nothing listed at this time.
- </p>
- </section>
</section>
+ </section>
+ <section>
+ <h2>Gallery</h2>
+ <p>
+ The Gallery API:
+ </p>
+ <ul>
+ <li>MUST enable listing all available gallery sources, their names and types</li>
+ <li>MUST enable finding content inside a gallery</li>
+ <li>MUST enable adding, updating, and removing content from a gallery</li>
+ <li>MUST expose metadata about the gallery's content items (copyright, author, media-dependent information, etc.)</li>
+ </ul>
+ <p class='issue'>
+ Exposing metadata is tricky, often giving a choice between creating an endless ontology
+ or building an open-ended system that guarantees no interoperability.
+ </p>
+ <p class='issue'>
+ A lot of this functionality can be provided if the Gallery API is basically a way of
+ accessing well-known parts of the file system, and if the File System API has a way
+ of exposing sufficient metadata. This could make for a very simple API.
+ </p>
<section>
- <h2>Gallery</h2>
+ <h2>May be considered in future versions</h2>
<p>
- The Gallery API:
- </p>
- <ul>
- <li>MUST enable listing all available gallery sources, their names and types</li>
- <li>MUST enable finding content inside a gallery</li>
- <li>MUST enable adding, updating, and removing content from a gallery</li>
- <li>MUST expose metadata about the gallery's content items (copyright, author, media-dependent information, etc.)</li>
- </ul>
- <p class='issue'>
- Exposing metadata is tricky, often giving a choice between creating an endless ontology
- or building an open-ended system that guarantees no interoperability.
- </p>
- <p class='issue'>
- A lot of this functionality can be provided if the Gallery API is basically a way of
- accessing well-known parts of the file system, and if the File System API has a way
- of exposing sufficient metadata. This could make for a very simple API.
+ Nothing listed at this time.
</p>
- <section>
- <h2>May be considered in future versions</h2>
- <p>
- @@TBD
- </p>
- </section>
</section>
+ </section>
+ <section>
+ <h2>Messaging</h2>
+ <p>
+ @@TBD, still under discussion as part of <a href='http://www.w3.org/2009/dap/track/issues/13'>ISSUE-13</a>.
+ </p>
<section>
- <h2>Messaging</h2>
+ <h2>May be considered in future versions</h2>
<p>
- @@TBD, still under discussion as part of <a href='http://www.w3.org/2009/dap/track/issues/13'>ISSUE-13</a>.
+ @@TBD
</p>
- <section>
- <h2>May be considered in future versions</h2>
- <p>
- @@TBD
- </p>
- </section>
</section>
+ </section>
+ <section>
+ <h2>System Information & Events</h2>
+ <p>
+ The System Information & Events API:
+ </p>
+ <ul>
+ <li>MUST enable listing available power sources (batteries, wall...)</li>
+ <li>MUST expose whether the device is running on battery or not</li>
+ <li>MUST expose charge level per battery and globally</li>
+ <li>MUST enable listing available network interfaces, their types (Wifi, 3G, LAN...), and signal strengths</li>
+ <li>MUST provide CPU information</li>
+ <li>MAY provide CPU load information</li>
+ <li>MUST enable listing storage areas, their types, writability, and available space</li>
+ <li>MUST provide RAM information</li>
+ <li>MAY provide RAM load information</li>
+ <li>MUST enable listing displays, as well as their colour depth, resolution, etc.</li>
+ <li>MUST enable listing input devices (mouse, keyboard, touch, keypad, voice, stylus...)</li>
+ <li>MUST enable listing audio output devices and their properties</li>
+ <li>MUST enable listing audio input devices and their properties</li>
+ <li>MUST enable listing video capture devices and their properties</li>
+ <li>MUST enable listing picture capture devices and their properties</li>
+ <li>MUST enable listing thermal sensors, alongside their names and measurements</li>
+ <li>MUST enable listing ambient light sensors, alongside their names and measurements</li>
+ <li>MUST enable listing proximity detectors, alongside their names and measurements</li>
+ <li>MUST expose gyroscope and accelerometer capability and measurements</li>
+ <li>MUST enable listing vibration capability</li>
+ <li>MUST expose the availability of compass and geolocation capability</li>
+ </ul>
<section>
- <h2>System Information & Events</h2>
+ <h2>May be considered in future versions</h2>
<p>
- The System Information & Events API:
+ @@TBD
</p>
- <ul>
- <li>MUST enable listing available power sources (batteries, wall...)</li>
- <li>MUST expose whether the device is running on battery or not</li>
- <li>MUST expose charge level per battery and globally</li>
- <li>MUST enable listing available network interfaces, their types (Wifi, 3G, LAN...), and signal strengths</li>
- <li>MUST provide CPU information</li>
- <li>MAY provide CPU load information</li>
- <li>MUST enable listing storage areas, their types, writability, and available space</li>
- <li>MUST provide RAM information</li>
- <li>MAY provide RAM load information</li>
- <li>MUST enable listing displays, as well as their colour depth, resolution, etc.</li>
- <li>MUST enable listing input devices (mouse, keyboard, touch, keypad, voice, stylus...)</li>
- <li>MUST enable listing audio output devices and their properties</li>
- <li>MUST enable listing audio input devices and their properties</li>
- <li>MUST enable listing video capture devices and their properties</li>
- <li>MUST enable listing picture capture devices and their properties</li>
- <li>MUST enable listing thermal sensors, alongside their names and measurements</li>
- <li>MUST enable listing ambient light sensors, alongside their names and measurements</li>
- <li>MUST enable listing proximity detectors, alongside their names and measurements</li>
- <li>MUST expose gyroscope and accelerometer capability and measurements</li>
- <li>MUST enable listing vibration capability</li>
- <li>MUST expose the availability of compass and geolocation capability</li>
- </ul>
- <section>
- <h2>May be considered in future versions</h2>
- <p>
- @@TBD
- </p>
- </section>
</section>
+ </section>
+ <section>
+ <h2>Tasks</h2>
+ <p>
+ @@TBD
+ </p>
<section>
- <h2>Tasks</h2>
+ <h2>May be considered in future versions</h2>
<p>
@@TBD
</p>
- <section>
- <h2>May be considered in future versions</h2>
- <p>
- @@TBD
- </p>
- </section>
</section>
+ </section>
+ <section>
+ <h2>User Interface</h2>
+ <p>
+ @@TBD
+ </p>
<section>
- <h2>User Interface</h2>
+ <h2>May be considered in future versions</h2>
<p>
@@TBD
</p>
- <section>
- <h2>May be considered in future versions</h2>
- <p>
- @@TBD
- </p>
- </section>
</section>
</section>
-
<section class='appendix'>
<h2>Acknowledgements</h2>
Received on Monday, 5 October 2009 14:35:10 UTC