- From: Mercurial notifier <cvsmail@w3.org>
- Date: Tue, 10 Apr 2012 05:30:13 +0000
- To: public-dap-commits@w3.org
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