dap commit: Rewrite the sensor spec to remove discovery.

changeset:   74:604921bf3aaf
tag:         tip
user:        dtran
date:        Mon Apr 09 22:25:56 2012 -0700
files:       sensor-api/Overview.html
description:
Rewrite the sensor spec to remove discovery.
This should be a simple for the JS programmer


diff -r 69178436f4d4 -r 604921bf3aaf sensor-api/Overview.html
--- a/sensor-api/Overview.html	Fri Mar 09 15:25:58 2012 -0800
+++ b/sensor-api/Overview.html	Mon Apr 09 22:25:56 2012 -0700
@@ -1,498 +1,286 @@
-<!DOCTYPE html>
-<html>
-  <head>
-    <title>Sensor API Specification</title>
-    <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
-    <script src='http://dev.w3.org/2009/dap/ReSpec.js/js/respec.js' class='remove'></script>
-    <script src='http://dev.w3.org/2009/dap/ReSpec.js/js/sh_main.min.js' class='remove'></script>
-    <script src="http://dev.w3.org/2009/dap/ReSpec.js/js/lang/sh_javascript_dom.min.js" class='remove'></script>
-   
-    <script class='remove'>
-      var respecConfig = {
-	  specStatus:           "ED",
-          shortName:            "sensor",
-          publishDate:  "2012-03-09",
-          //previousPublishDate:  "2011-06-02",
-          previousMaturity:  "WD",
-          edDraftURI:           "http://dvcs.w3.org/hg/dap/raw-file/tip/sensor-api/Overview.html",
-          // lcEnd: "2009-08-05",
-           editors: [
-    	            {name: "Dzung D Tran", company: "Intel"},
-    	            {name: "José Manuel Cantera Fonseca", company: "Telefónica"}
-    		    ],
-          inlineCSS:    true,
-          noIDLIn:      true,
-          extraCSS:     ["http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],
-          wg:           "Device APIs Working Group",
-          wgURI:        "http://www.w3.org/2009/dap/",
-          wgPublicList: "public-device-apis"
-      };
-    </script>
-    
-    <style>
-            .event {
-                font-family: monospace;
-                color: #459900;
-      }
-    </style>
-  </head>
-  <body>
-	<section id='abstract'>
-      This specification defines a generic API for getting access to information provided by sensors available from a hosting device.
-    </section>
-
-<!--***************************************Sensors***********************************************-->
-	<section>
-		<h2>Introduction</h2>
-		<p>This section is non-normative</p>
-		<p>This specification defines an API that allows application code to obtain information given by the various 
-		sensors available on a hosting device. The information provided through this API is 
-		raw sensor data. The specification is aimed at covering 
-		well-known sensors that are commonly found in devices.  
-                The API is extensible, allowing integration of vendor or external specific sensors.</p>
-		
-		<section>
-		<p>The following code snippet illustrates how to monitor sensor data, for instance the ambient temperature:</p>
-		<pre class="example sh_javascript_dom">
-			var sensorCnx = new SensorConnection('Temperature');
-			sensorCnx.addEventListener('sensordata', function(e) {
-				if(e.data > 20.0) {
-					window.console.log('Temperature is too high!!!!');
-				}
-			} );
-			
-			var watchOptions = { interval: (15 * 60 * 1000) };
-			sensorCnx.startWatch(watchOptions);
-		</pre>
-		
-		<p>The following code snippet illustrates how to discover all sensors of type 'Temperature' that are available from the device:</p>
-		<pre class="example sh_javascript_dom">
-			var sensorReq = navigator.findSensors('Temperature');
-			
-			sensorReq.onsuccess = function() {
-			  for(var count = 0; count < this.result.length; count++) {
-			    window.console.log("Discovered: " + this.result[count].name);
-			  }
-			}
-			
-			sensorReq.onerror = function() {
-			  window.console.error(this.error.code);
-			}
-		</pre>
-		
-		</section>
-	</section>
-
-<section id='conformance'>
-      <p>
-        This specification defines conformance criteria that apply to a single product: the 
-        <dfn id="ua">user agent</dfn> that implements the interfaces that it contains.
-      </p>
-      <p>
-        Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement
-        them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification
-        [[!WEBIDL]], as this specification uses that specification and terminology.
-      </p>
-      <p>
-        A conforming implementation is required to implement all fields defined in this specification.
-      </p>
-</section>
-
-<section>
-	<h2>Security and Privacy Considerations</h2>
-	<p>A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism should ensure that
-	no sensitive information is made available through this API without the user's express permission. User agents MUST acquire permission through a user interface,
-	unless they have prearranged trust relationships with users. </p>
-</section>
-
-<section id="discovery">
-	<h2>Sensor Discovery</h2>
-	  <section>
-	       <div class='idl' title='Navigator implements SensorManager'></div>
-	  </section>
-	  
-	  <section>
-		<h3><a>SensorManager</a></h3>
-		This is an asynchronous API that returns without blocking the calling thread. 
-		 <p>
-                     This interface allows applications to discover what sensors are available from the device.           
-		 The sensor information is acquired by calling platform native sensor interfaces, creating a list of 
-		Sensor objects, and populating that object with appropriate data accordingly.		  
-		 </p>
-                
-		<dl title='[NoInterfaceObject] interface SensorManager' class='idl'>
-				<dt>SensorRequest findSensors(DOMString type)</dt>
-				<dd>
-					<p>When invoked the user agent MUST immediately return a <a>SensorRequest</a> instance with the <a>readyState</a> set 
-					to <a>processing</a>, which does not initially contain any information about the result of the operation. If 
-					the user permissions are ok then the UA MUST queue a new <em>listSensors process</em> that will call platform native 
-					sensor interfaces to fill a list of <a>Sensor</a> objects that will contain metadata about the sensors hosted 
-					by the device. The argument <a>type</a> MUST be set to the type of sensor to be searched for. 
-					<p>If user permissions are not ok the process MUST finish and an error event on the request MUST be fired. 
-					<p>
-					Once the <em>listSensors process</em> finishes without error, the <a>onSuccess</a> event is fired on the request and 
-					the information becomes available through the properties of the <a>SensorRequest</a> instance. If an error occurs while 
-					performing the operation, the <a>onError</a> event is fired and the <a>error</a> is set to the error code. If no matching
-					sensors are found, this is NOT reported as an error but just an empty list of sensors. In either 
-					case the the <a>readyState</a> is set to <code>done</code> to indicate the discovery process has completed</p>
-				</dd>
-		</dl>
-	  </section>
-	  
-	  <section>
-		<h3><a>SensorRequest</a></h3>
-		  This interface provides means to access results of asynchronous sensor discovery requests.
-		  
-		  <dl title='[NoInterfaceObject] interface SensorRequest' class='idl'>
-		      <dt>readonly attribute <a>DOMError</a> error</dt>
-		       <dd>
-			When the readyState is done and an error exception has been raised, MUST return the error of
-                                 the request. This is null when no error occurred. When the readyState is processing,
-                                 MUST throw a <code>DOMException</code> of type <a>InvalidStateError</a>. 
-                        <dl class="getraises" title="DOMException">
-                            <dt><a>InvalidStateError</a></dt>
-                             <dd>Thrown when this attribute was read when the readyState is processing.</dd>
-	                </dl>
-		      </dd>
-		      <dt>attribute Function onerror</dt>
-		       <dd>
-			 The event handler for the error event
-		       </dd>
-		      <dt>attribute Function onsuccess</dt>
-		       <dd>
-			The event handler for the success event
-		      </dd>
-		      <dt>
-			  readonly attribute DOMString readyState</dt> 
-		      </dt>
-		      <dd>Represents the status of the request. It MUST be set to one of the following:
-			<ul>
-			  <li><code>processing</code>. If the discovery process is still pending.</li>
-			  <li><code>done</code>. If the discovery process is completed. </li>
-			</ul>
-		      <dt>readonly attribute Sensor[] result</dt>
-		      <dd>
-			When the <a>readyState</a> is done, MUST return list of sensors discovered.
-			This is undefined when the request resulted in an error. When the <a>readyState</a> is processing, MUST throw a <a><code>InvalidStateError</code></a>.
-			<dl class="getraises" title="DOMException">
-			  <dt><a>InvalidStateError</a></dt>
-			<dd>Thrown when this attribute was read when the <a title="request done">done</a> flag was set to false.</dd>
-			</dl>
-		  </dl>
-		  
-		</section>
-</section>
-
-<section>
-    <h2>Sensor Metadata</h2>
-    <section>
-	<h3><a>Sensor</a></h3>
-		The <code>Sensor</code> object contains different attributes that provide sensor metadata. 
-		<dl title='[NoInterfaceObject] interface Sensor' class='idl'>
-			<dt>readonly attribute short? minDelay</dt>
-			<dd>
-	 			It MUST return the minimum delay allowed between two sensor data events in microseconds or zero if only sensor 
-                                data events are dispatched when there is a change in the measured magnitude. 
-                                <code>null</code> MUST be returned if this parameter is not known to the implementation.
-			</dd>
-			<dt>readonly attribute DOMString name</dt>
-			<dd>
-				It MUST return an unique identifier for the sensor.
-			</dd>
-			<dt>readonly attribute short? minRange</dt>
-			<dd>
-	 			It MUST return the minimum range of the sensor in the sensor's unit or <code>null</code> if it is not known.
-			</dd>
-			<dt>readonly attribute short? maxRange</dt>
-			<dd>
-	 			It MUST return the maximum range of the sensor in the sensor's unit or <code>null</code> if it is not known.
-			</dd>
-			<dt>readonly attribute float? resolution</dt>
-			<dd>
-				It MUST return the sensor's resolution of the sensor in unit of measurement or <code>null</code> 
-                                    if this parameter is not known to the implementation.
-			</dd>
-			<dt>readonly attribute DOMString type</dt>
-			<dd>
-				It MUST return the sensor type. See table below for a list sensor types defined by this specification
-			</dd>
-		</dl>
-    </section>
-</section>
-	
-	<section>
-	  <h2>Sensor Data</h2>
-<section>
-		<h3>SensorConnection Interface</h3>
-		The SensorConnection object is an event target that MUST be used to request a connection to a sensor of a 
-		specified type on the hosting device. The sensor connection is acquired by calling platform native sensor interfaces.
-		<dl title='[Constructor(DOMString type),Constructor(SensorOptions options)] interface SensorConnection : EventTarget' class='idl'>
-        		<dt>readonly attribute Sensor sensor </dt>
-        		<dd>
-          		Represents the metadata of the sensor that is currently connected to this event target.
-			
-			<dl class="getraises" title="DOMException">
-			  <dt><a>InvalidStateError</a></dt>
-			<dd>Thrown when this attribute was read and the sensor connection was in the "new" state.</dd>
-			</dl>
-		        </dd>
-          		
-          		<dt>readonly attribute DOMString status</dt>
-          		<dd>
-          		Represents the current status of the event target. The status MUST be set to one of the
-          		following:
-			  	<ul>
-				        <li><code>new</code>. The object has been instantiated but a connection to the sensor has not been established yet. </li>
-			  		<li><code>open</code>. All the infrastructure to get sensor data is ready.</li>
-			  		<li><code>watching</code>. The sensor is under monitoring.</li>
-                                       <li><code>disconnected</code>. The connection with the sensor has been lost.</li>
-			  		<li><code>error</code>. An error has occured</li>
-			  	</ul>
-          		</dd>
-			
-			<dt>readonly attribute DOMError error</dt>
-			<dd>Represents the current error of the event target. This is null when no error occurred.</dd>
-
-			<dt>attribute Function? onerror</dt>
-			<dd>Allows to set an event handler that will be invoked when the sensor connection is in error</dd>
-
-			<dt>attribute Function? onsensordata</dt>
-			<dd>Allows to set an event handler that will be invoked when new sensor data is available</dd>
-			
-			<dt>attribute Function? onstatuschange</dt>
-			<dd>Allows to set an event handler that will be invoked when connection status change</dd>
-                        
-                        <dt>attribute Function? oncalibneed</dt>
-                        <dd>Allows to set an event handler that will be invoked when the sensor needs calibration</dd>
-                        
-			<dt>void read()</dt>
-				<dd>
-					When invoked the user agent MUST run the following steps:
-					<ol>
-						<li>If the status is other than <code>open</code> or <code>watching</code> an ILLEGAL_STATE exception MUST be thrown. </li>
-						<li>Otherwise the user agent MUST queue a task <var>TRead</var> to perform a reading from the sensor and then return immediately. </li>
-						<li> Once <var>TRead</var> has finished successfully, the implementation MUST queue a task to fire a 
-                                                 <a>SensorDataEvent</a> with: 
-							<ul>
-								<li><code>data</code> field equal to the values read from the sensor.</li>
-								<li><code>isWatchPoint</code> field equal to 'false'</li>
-							</ul>
-						<li>If <var>TRead</var> fails Queue a task to fire a simple event named error at the <a>SensorConnection</a>.</li>
-					</ol>
-				</dd>
-
-          		<dt>void startWatch(SensorWatchOptions watchOptions)</dt>
-				<dd>
-					<p>When called the user agent MUST run the following steps:
-					<ol>
-						<li>If  <a>status</a> is other than <code>open</code> an ILLEGAL_STATE exception MUST be thrown</li>
-						<li>If <a>status</a> is <code>open</code> then run the following sub-steps: </li>
-						<ol>
-							<li>Queue a task <var>TWatch</var> in charge of invoking the  platform native interfaces to start monitoring sensor values
-							in accordance with the parameters specified as part of <a>SensorWatchOptions</a> argument. Then, return immediately to the caller. </li>
-							<li>If <var>TWatch</var> succeeds, the <a>status</a> attribute MUST be set to the <code>watching</code> value. Queue a task to fire a simple event named
-							<code>statuschange</code> at the <a>SensorConnection</a></li>
-							<li>If <var>TWatch</var> fails then Queue a task to fire a simple event named error at the <a>SensorConnection</a>.</li>
-						</ol>
-					</ol>
-					<p>Everytime the platform monitoring mechanism notifies of a new sensor value the user agent MUST queue a task to fire a
-					<a>SensorDataEvent</a> with:
-						<ul>
-							<li><code>data</code> field equal to the values read from the sensor</li>
-							<li><code>isWatchPoint</code> field equal to 'true'
-						</ul>
-				</dd>
-
-			<dt>void endWatch()</dt>
-				<dd>
-					When this method is called the user agent MUST run the following steps:
-					<ol>
-						<li>If status is other than <code>watching</code> an ILLEGAL_STATE exception MUST be thrown.</li>
-						<li>If status is <code>watching</code> then the following substeps MUST be done:
-							<ol>
-								<li>Invoke platform native interfaces to notify the end of the monitoring.</li>
-								<li>If the invocation succeeds, the <a>status</a> attribute MUST be set to the <code>open</code> value 
-                                                               and the control MUST be returned to the caller. Finally, Queue a task to fire a simple event named
-							<code>statuschange</code> at the <a>SensorConnection</a>. </li>
-							<li>If the invocation fails Queue a task to fire a simple event named error at the <a>SensorConnection</a>.</li>
-							</ol>
-					</ol>
-				</dd>
-		</dl>
-	<dl>
-			
-	<dt>[Constructor(SensorOptions options)]</dt>
-	  <dd>Constructs a new <a>SensorConnection</a>. when invoked the user agent MUST run the following steps:
-	    <ol>
-		<li>Let <var>_sensor</var> be the target sensor to be connected to. If none of the dictionary members are defined then raise an instantiation exception. </li>
-		                       <li>If the dictionary member <code>name</code> is not defined
-                                        then <var>_sensor</var> MUST correspond to the default sensor type specified by the <code>type</code> member. 
-                                        Otherwise <var>_sensor</var> MUST be assigned to a sensor of the specified <code>type</code> and whose identifier 
-                                        is equal to the <code>name</code> member. </li>
-					<li>Check if the sensor identified by <var>_sensor</var> is available and ready to be connected</li>					
-					<li>If the sensor exists, is available and user permissions are ok, then instantiate a <code>SensorConnection</code> object and set its status to 'open'. </li>
-					<li>If user permissions are needed then instantiate the SensorConnection object, set its status to 'new' and prompt the user in a user-agent-specific manner for permission.
-					<p>Once the user gives permission set status to 'open'. If the user does not give permission set status to 'error' and fire an error event. 
-					</li>
-					<li>If the sensor is not available or does not exist raise an instantiation exception (tbd). </li>
-	    </ol>
-	    <p>Implementations MAY support other connection options as part of the <a>SensorOptions</a> interface</p>
-	  </dd>
-	  
-	  <dt>[Constructor(DOMString type)]</dt>
-			<dd>Constructs a new <a>SensorConnection</a> by passing a sensor type. This is a convenient function for the more general function described above. 
-			</dd>
-			
-	      <p>These constructors MUST be visible when the script's global object is either a <code>Window</code> object
-		or an object implementing the <code>WorkerUtils</code> interface.</p>
-	</dl>
-
-</section>
-
-<section>
-		<h3><a>SensorWatchOptions Interface</a></h3>
-		<dl title='dictionary SensorWatchOptions' class='idl'>
-				<dt>attribute double threshold</dt>
-				<dd>
-					This attribute only applies to sensors that provide single value readings. It indicates that a data event MUST only be raised when the 
-					sensor value crosses the specified threshold (in either direction).
-					<p class="issue">
-					  This attribute is likely to be revisited to support these use cases:<br>
-					  
-					    - Low and high thresholds<br>
-					    - Ranges [10,20] (10,20] .... <br>
-					   - Thresholds that apply to the different data components of a sensor, for instance x,y,z in the case of accelerometer. 
-					</p>
-				</dd>
-				<dt>attribute double interval</dt>
-				<dd>
-				The <code>interval</code> attribute represents the monitorization interval at which data SHOULD be obtained
-				from the underlying sensor hardware and MUST be expressed in milliseconds. The caller 
-				should be aware that setting a value too small can adversely affect the battery life. If the interval is
-				set to zero, then the implementation MUST return sensor data only when there is a change since the last acquisition.
-				</dd>
-		</dl>
-</section>	
-
-<section>
-  
-  <h3><a>SensorOptions</a> Interface</h3>
-		<dl title='dictionary SensorOptions' class='idl'>
-				<dt>attribute DOMString type</dt>
-				<dd>
-					Sensor type for which a connection is requested
-				</dd>
-				<dt>attribute DOMString name</dt>
-				<dd>
-				  Sensor name for which a connection is requested
-				</dd>
-		</dl>
-</section>
-
-<section>
-		<h3><a>SensorDataEvent</a> Interface</h3>
-                <p class="note">This section will be changed to comply with the DOM4 Event interfaces</p>
- 		<dl title='interface SensorDataEvent : Event' class='idl'>
-				<dt>readonly attribute any data</dt>
-				<dd>This attribute represents the raw data provided by the sensor. The specific type depends on the <a>type</a> of the sensor.
-					See <a href="datatypes"></a> for implementation requirements for this attribute depending on the type of sensor. 
-				</dd>
-       			<dt>readonly attribute DOMString accuracy</dt>
-       			<dd>This attribute MUST return an enumerated value that gives an indication of the accuracy of the sensor data. The allowed values are:
-              		<ul>
-                        <li><code>high</code> - This sensor is reporting data with maximum accuracy</li>
-             		<li><code>medium</code> - This sensor is reporting data with average accuracy, calibration with the environment may improve readings</li>
-              		<li><code>low</code> This sensor is reporting data with low level of accuracy, calibration with the environment is needed</li>
-              		<li><code>unreliable</code> - This sensor is reporting data that can't be trusted, calibration is needed. </li>
-              		</ul>
-       			</dd>
-       			<dt>readonly attribute double timestamp</dt>
-       			<dd>
-				The time in nanosecond at which the sensor data was read. 
-       			</dd>
-				<dt>readonly attribute boolean isWatchPoint</dt>
-				<dd>It is a boolean that denotes if this is a watch point. The only admissible values for this attribute are:
-					<ul>
-						<li><code>false</code>. The event was raised due to onetime read operation</li>
-						<li><code>true</code>. The event was raised due to a recurring watch operation</li>
-					</ul>
-				</dd>
-     			<dt>void initSensorDataEvent(in DOMString type,
-                                in boolean bubbles,
-                                in boolean cancelable,
-                                in boolean isWatchPoint,
-                                in double timestamp,
-                                in DOMString accuracy,
-                                in any data)
-                </dt>
-                <dd>
-                Initializes a <a>SensorDataEvent</a> created through the <code>DocumentEvent</code> interface. 
-                </dd>
-		</dl>
-                
-                <p class="note">A section describing all the events defined by the API might be added for next draft. </p>
-
-</section>
-
-	</section>
-
-<section id="datatypes">
-	<h2>Sensor Type Definitions</h2>
-	This section specifies some base sensor types and related data formats.
-	<section>
-	<h3>Sensor Types and Related Data Formats</h3>
-	<p>This section specifies a base set of sensor types and related data formats. If the UA supports these sensor types, they MUST use 
-	this data format definition.  Any UA can also extend its support to other sensors that are 
-	defined elsewhere outside of this specification.  It is implementation dependent how to register and support new sensor types.</p>
-	<p>For the sensor types defined here, an implementation MUST set the specific type of the <code>SensorDataEvent.data</code> 
-	and <code>SensorDataEvent.type</code> attributes in accordance with the following table:
-		<table class="simple">
-			<thead>
-				<tr>
-				<th>Sensor Type</th>
-				<th>Description</th>
-				<th>Data Type</th>
-				<th>Units</th></tr>
-			</thead>
-			<tbody>
-				<tr><td>Temperature</td><td>A ambient temperature sensor</td><td>double</td><td>degree Celsius (ºC)</td></tr>
-				<tr><td>AtmPressure</td><td>A pressure sensor</td><td>double</td><td>kiloPascal (kP)</td></tr>
-				<tr><td>RelHumidity</td><td>A releative humidity sensor</td><td>double</td><td>percentage</td></tr>
-				<tr><td>AmbientLight</td><td>A light sensor</td><td>double</td><td>Lux</td></tr>
-				<tr><td>AmbientNoise</td><td>A ambient noise sensor</td><td>double</td><td>dbA</td></tr>
-				<tr><td>MagneticField</td><td>A magnetic field sensor</td><td>MagneticFieldData</td><td>micro-Tesla (uTesla)</td></tr>
-				<tr><td>Proximity</td><td>A proximity sensor</td><td>double</td><td>centimetres (cm)</td></tr>
-			</tbody>
-		</table>
-	</p>
-	</section>
-
-	<section><h4>The MagneticFieldData interface</h4>
-		<dl title='interface MagneticFieldData' class='idl'>
-				<dt>readonly attribute double x</dt>
-				<dd> 
-					ambient magnetic field in X
-				</dd>
-				<dt>readonly attribute double y</dt>
-				<dd>
-					ambient magnetic field in Y
-				</dd>
-				<dt>readonly attribute double z</dt>
-				<dd>
-					ambient magnetic field in Z
-				</dd>
-		</dl>
-	</section>
-
-	</section>
-
-<section>
-		
-    <section class='appendix'>
-      <h2>Acknowledgements</h2>
-      <p>
-		WAC Ipanema Device APIs Lightweight Participation WG, in particular Bryan Sullivan, Balaji N.V., and Kaushik Das. 
-      </p>
-    </section>
-  </body>
-</html>
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Sensor API Specification</title>
+    <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
+    <script src='http://dev.w3.org/2009/dap/ReSpec.js/js/respec.js' class='remove'></script>
+    <script src='http://dev.w3.org/2009/dap/ReSpec.js/js/sh_main.min.js' class='remove'></script>
+    <script src="http://dev.w3.org/2009/dap/ReSpec.js/js/lang/sh_javascript_dom.min.js" class='remove'></script>
+   
+    <script class='remove'>
+      var respecConfig = {
+	  specStatus:           "ED",
+          shortName:            "sensor",
+          publishDate:  "2012-03-09",
+          //previousPublishDate:  "2011-06-02",
+          previousMaturity:  "WD",
+          edDraftURI:           "http://dvcs.w3.org/hg/dap/raw-file/tip/sensor-api/Overview.html",
+          // lcEnd: "2009-08-05",
+           editors: [
+    	            {name: "Dzung D Tran", company: "Intel"},
+    	            {name: "José Manuel Cantera Fonseca", company: "Telefónica"}
+    		    ],
+          inlineCSS:    true,
+          noIDLIn:      true,
+          extraCSS:     ["http://dev.w3.org/2009/dap/ReSpec.js/css/respec.css"],
+          wg:           "Device APIs Working Group",
+          wgURI:        "http://www.w3.org/2009/dap/",
+          wgPublicList: "public-device-apis"
+      };
+    </script>
+    
+    <style>
+            .event {
+                font-family: monospace;
+                color: #459900;
+      }
+    </style>
+  </head>
+  <body>
+	<section id='abstract'>
+      This specification defines an API for getting access to information provided by sensors available from a hosting device.
+    </section>
+
+<!--***************************************Sensors***********************************************-->
+	<section>
+		<h2>Introduction</h2>
+		<p>This section is non-normative</p>
+		<p>This specification defines an API that allows application code to obtain information given by the various 
+		sensors available on a hosting device. The information provided through this API is 
+		raw sensor data. The specification is aimed at covering 
+		well-known sensors that are commonly found in devices. </p>
+		
+		<section>
+		<p>The following code snippet illustrates how to monitor sensor data, for instance the ambient temperature:</p>
+		<pre class="example sh_javascript_dom">
+        TDB
+		</pre>
+		
+		<p>The following code snippet illustrates how to discover all sensors of type 'Temperature' that are available from the device:</p>
+		<pre class="example sh_javascript_dom">
+        TBD
+		</pre>
+		
+		</section>
+	</section>
+
+<section id='conformance'>
+      <p>
+        This specification defines conformance criteria that apply to a single product: the 
+        <dfn id="ua">user agent</dfn> that implements the interfaces that it contains.
+      </p>
+      <p>
+        Implementations that use ECMAScript to implement the APIs defined in this specification MUST implement
+        them in a manner consistent with the ECMAScript Bindings defined in the Web IDL specification
+        [[!WEBIDL]], as this specification uses that specification and terminology.
+      </p>
+</section>
+
+<section>
+	<h2>Security and Privacy Considerations</h2>
+	<p>A conforming implementation of this specification MUST provide a mechanism that protects the user's privacy and this mechanism should ensure that
+	no sensitive information is made available through this API without the user's express permission. User agents MUST acquire permission through a user interface,
+	unless they have prearranged trust relationships with users. </p>
+</section>
+
+<section id="sensormanager">
+	<h2>Sensor Manager</h2>
+	  <section>
+	       <div class='idl' title='Navigator implements SensorManager'></div>
+	  </section>
+	  
+	  <section>
+		<h3><a>SensorManager</a></h3>
+		This is an asynchronous API that returns without blocking the calling thread. This interface provides interfaces to applications for making sensor requests.
+                
+		<dl title='[NoInterfaceObject] interface SensorManager' class='idl'>
+                <dt>void cancelWatchpoint(<a>SensorRequest</a> request)</dt>
+				<dd>
+			    When this method is called the user agent MUST check the argument <code>request</code> versus its current pending requests  
+                and do the following:
+				<ol>
+					<li>If the current request is other than <code>WatchPoint</code> an ILLEGAL_STATE exception MUST be thrown.</li>
+					<li>If the current request is <code>WatchPoint</code> then the following substeps MUST be done:
+				    <ol>
+						<li>Invoke platform native interfaces to notify the end of the monitoring.</li>
+						<li>If the invocation succeeds then return.</li>
+						<li>If the invocation fails then an exception MUST be thrown.</li>
+					</ol>
+				</ol>
+				</dd>
+				<dt>void connectSensor(<a>SensorRequest</a> request, SensorSuccessCallback onSuccess, optional callback onFailure)</dt>
+				<dd>
+					<p>When invoked the user agent asks the user if the sensor data should be granted to the requesting application.
+                   UAs may provide arrangements for users to save their response, but must always allow the user to change any saved
+                   permission.</p>
+                   <p>If user permissions are not ok, the request must finish and an error event must be fired. 
+                   Otherwise the request uses the <a>SensorRequest</a> instance data to invoke the  platform native interfaces to start 
+                   monitoring sensor values in accordance with the parameters specified as part of <a>SensorRequest</a> argument. 
+                   It then returns immediately and subsequently, the <code>onSuccess</code> event is fired on the request
+                   when the information becomes available through the properties of the <a>SensorData</a> instance. If an error occurs 
+                   while performing the operation, the <code>onFailure</code> event is fired and the error is set to the error string.</p>
+ 				</dd>
+		</dl>
+	  </section>
+      <section>
+      <h3>SensorSuccessCallback</h3>
+      The success callback passed to <a>connectSensor</a> must provide the signature:
+       <dl title='[NoInterfaceObject] interface SensorSuccessCallback' class='idl'>
+        <dt>void onSuccess(<a>SensorData</a> data)</dt>
+        <dd>
+        The <code>onSuccess</code> callback is raised with an <a>SensorData</a> object when there is sensor data available.
+        </dd>
+      </dl>
+      </section>
+
+      <section>
+      <h3>SensorFailureCallback</h3>
+      The failure callback passed to <a>connectSensor</a> must provide the signature:
+      <dl title='[NoInterfaceObject] interface SensorFailureCallback' class='idl'>
+        <dt>void onFailure(DOMString error)</dt>
+        <dd>
+        The <code>onFailure</code> callback is raised with a error string when an error occurs during the <a>connectSensor</a> process.
+        UAs should provide the following error strings:
+        <ol>
+        <li>"sensor not available"</li>
+        <li>"sensor not responding"</li>
+        <li>"invalid parameters"</li>
+        </ol>
+        </dd>
+      </dl>
+      </section>
+
+</section>
+
+<section id="sensorrequest">
+	<h2>Sensor Request</h2>
+	  <section>
+	       <div class='idl' title='SensorManager implements SensorRequest'></div>
+	  </section>
+	  
+	  <section>
+		<h3><a>SensorRequest</a></h3>
+		  This interface provides means to specify the current request sensor of interest.
+		  
+		  <dl title='[NoInterfaceObject] interface SensorRequest' class='idl'>
+		      <dt>readonly attribute <a>DOMString</a> action</dt>
+		      <dd>
+              Represents the action for the request. The string must not be empty, or the constructor must throw an exception. 
+              The string must be one of:
+              <ol>
+              <li>"OneTime"</li>
+              <li>"WatchPoint"</li>
+              </ol>
+              <p>If the action is <code>OneTime</code>, there is a single response returned to the callback and the connection to the sensor is 
+              cancelled automatically.  If the action is <code>WatchPoint</code>, then repeated data samples are sent to the callback until 
+              <code>cancelWatchpoint</code> is called or the page unloads.</p>
+		      </dd>
+		      <dt>readonly attribute <a>DOMString</a> type</dt>
+		      <dd>
+              Represents the sensor type of the request. The string must not be empty, or the constructor must throw an exception.
+              The type MUST be one of the types specified in section <a>Sensor Type Definitions</a>
+		      </dd>
+			  <dt>attribute double threshold[]</dt>
+			  <dd>
+					It indicates that a data event MUST only be raised when the sensor value crosses any of the threshold values in the 
+                    array (in either direction).
+				</dd>
+				<dt>attribute double interval</dt>
+				<dd>
+				The <code>interval</code> attribute represents the monitorization interval at which data SHOULD be obtained
+				from the underlying sensor hardware and MUST be expressed in milliseconds. The caller 
+				should be aware that setting a value too small can adversely affect the battery life. If the interval is
+				set to zero, then the implementation MUST return sensor data only when there is a change since the last acquisition.
+				</dd>		  
+           </dl>		  
+	  </section>
+</section>
+
+<section id="sensordata">
+	<h2>Sensor Data</h2>
+    <section>
+		<h3><a>SensorData</a></h3>
+		  This interface provides means to access the sensor data for the current request sensor of interest. This object will be returned 
+          in the <code>onSuccess</code> callback of the connectSensor interface.
+		  
+		  <dl title='[NoInterfaceObject] interface SensorData' class='idl'>
+		      <dt>readonly attribute <a>DOMString</a> action</dt>
+		      <dd>
+              Same as in <a>SensorManager</a> request.
+		      </dd>
+		      <dt>readonly attribute <a>DOMString</a> type</dt>
+		      <dd>
+              Same as in <a>SensorManager</a> request.
+		      </dd>
+			  <dt>readonly attribute double accuracy</dt>
+			  <dd>
+              Accuracy of measurement in term of data type specified below section, if available. 
+              If not available, a value of zero must be returned
+			  </dd>
+			  <dt>readonly attribute double minInRange</dt>
+			  <dd>
+              Minimal value in the range the sensor detects, if available. 
+              If not available, a value of zero must be returned.
+			  </dd>		  
+			  <dt>readonly attribute double maxInRange</dt>
+			  <dd>
+              Maximum value in the range the sensor detects, if available. 
+              If not available, a value of zero must be returned
+			  </dd>		  
+			  <dt>readonly attribute double timestamp</dt>
+			  <dd>
+              Time in nanoseconds when the sensor was read, if available.
+              If not available, a value of zero must be returned
+			  </dd>		  
+			  <dt>readonly attribute DOMString name</dt>
+			  <dd>
+              Friendly name of the sensor, if available.
+              If not available, an empty string must be returned
+			  </dd>		  
+			  <dt>readonly attribute double values[]</dt>
+			  <dd>
+              Sensor data values as specified in the section below.
+			  </dd>		  
+           </dl>		  
+	 </section>
+</section>
+
+<section id="datatypes">
+	<h2><a>Sensor Type Definitions</a></h2>
+	This section specifies base sensor types and related data formats.
+	<section>
+	<h3>Sensor Types and Related Data Formats</h3>
+	<p>This section specifies a base set of sensor types and related data formats. If the UA supports these sensor types, they MUST use 
+	this data format definition. UAs may choose which sensors they wish to support.
+	<p>For the sensor types defined here, an implementation MUST set the specific type of the <code>SensorRequest.type</code> 
+	attribute in accordance with the following table:
+		<table class="simple">
+			<thead>
+				<tr>
+				<th>Sensor Type</th>
+				<th>Description</th>
+				<th>Data Type</th>
+				<th>Units</th></tr>
+			</thead>
+			<tbody>
+				<tr><td>AmbientTemperature</td><td>A ambient temperature sensor</td><td>double</td><td>degree Celsius (ºC)</td></tr>
+				<tr><td>AtmPressure</td><td>A pressure sensor</td><td>double</td><td>kiloPascal (kP)</td></tr>
+				<tr><td>RelHumidity</td><td>A releative humidity sensor</td><td>double</td><td>percentage</td></tr>
+				<tr><td>AmbientLight</td><td>A light sensor</td><td>double</td><td>Lux</td></tr>
+				<tr><td>AmbientNoise</td><td>A ambient noise sensor</td><td>double</td><td>dbA</td></tr>
+				<tr><td>DevMagneticField</td><td>A magnetic field sensor</td><td>array of three doubles</td><td>micro-Tesla (uTesla)</td></tr>
+				<tr><td>DevProximity</td><td>A proximity sensor</td><td>double</td><td>centimetres (cm)</td></tr>
+			</tbody>
+		</table>
+	</p>
+	</section>
+</section>
+		
+<section class='appendix'>
+    <h2>Acknowledgements</h2>
+    <p>
+    WAC Ipanema Device APIs Lightweight Participation WG, in particular Bryan Sullivan, Balaji N.V., and Kaushik Das. 
+    </p>
+</section>
+</body>
+</html>

Received on Tuesday, 10 April 2012 05:30:17 UTC