diff --git a/index.bs b/index.bs index af4a14e..e751227 100644 --- a/index.bs +++ b/index.bs @@ -103,6 +103,16 @@ spec: webidl; type:dfn; text:identifier "date": "2017", "status": "Informational", "publisher": "International Journal of Information Security" + }, + "GENERIC-SENSOR-USECASES": { + "authors": [ + "Rick Waldron, Mikhail Pozdnyakov, Alexander Shalamov" + ], + "id": "GENERIC-SENSOR-USECASES", + "href": "https://w3c.github.io/sensors/usecases", + "title": "Sensor Use Cases", + "date": "2017", + "status": "Note" } } @@ -136,10 +146,9 @@ enable advanced use cases thanks to performant [=low-level=] APIs, and increase the pace at which new sensors can be exposed to the Web by simplifying the specification and implementation processes. -Issue: This lacks an informative section with examples for developers. -Should contain different use of the API, -including using it in conjunction with `requestAnimationFrame`. - +A comprehensive list of concrete sensors that are based on Generic Sensor API, applicable use +cases, and code examples can be found in [[GENERIC-SENSOR-USECASES]] and [[MOTION-SENSORS]] +explainer documents.

Scope

@@ -1404,6 +1413,8 @@ Such extension specifications are encour single [=sensor type=], exposing both [=high-level|high=] and [=low-level|low=] level as appropriate. +For an up-to-date list of [=extension specifications=], please refer to [[GENERIC-SENSOR-USECASES]] +and [[MOTION-SENSORS]] documents.

Security and Privacy

@@ -1503,7 +1514,7 @@ each [=sensor type=] in [=extension specifications=]: - An [=interface=] whose [=inherited interfaces=] contains {{Sensor}}. This interface must be constructible. - Its [{{Constructor!!extended-attribute}}] must take, as argument, + Its [{{Constructor!!extended-attribute}}] must take, as an argument, an optional [=dictionary=] whose [=inherited dictionaries=] contains {{SensorOptions}}. Its [=attributes=] which expose [=sensor readings=] are [=read only=] and their getters must return the result of invoking [=get value from latest reading=] @@ -1559,14 +1570,14 @@ for proximity [=device sensor|sensors=]. [Constructor(optional ProximitySensorOptions proximitySensorOptions), SecureContext, Exposed=Window] interface ProximitySensor : Sensor { - readonly attribute unrestricted double distance; + readonly attribute double? distance; }; dictionary ProximitySensorOptions : SensorOptions { - double? min = -Infinity; - double? max = Infinity; - ProximitySensorPosition? position; - ProximitySensorDirection? direction; + double min; + double max; + ProximitySensorPosition position; + ProximitySensorDirection direction; }; enum ProximitySensorPosition { diff --git a/index.html b/index.html index 2b3566d..cc0ab9d 100644 --- a/index.html +++ b/index.html @@ -1458,7 +1458,7 @@

Generic Sensor API

-

Editor’s Draft,

+

Editor’s Draft,

This version: @@ -1664,9 +1664,8 @@

1. low-level APIs, and increase the pace at which new sensors can be exposed to the Web by simplifying the specification and implementation processes.

-

This lacks an informative section with examples for developers. -Should contain different use of the API, -including using it in conjunction with requestAnimationFrame.

+

A comprehensive list of concrete sensors that are based on Generic Sensor API, applicable use +cases, and code examples can be found in [GENERIC-SENSOR-USECASES] and [MOTION-SENSORS] explainer documents.

2. Scope

This section is non-normative.

The scope of this specification is currently limited @@ -2808,8 +2807,9 @@

extension specifications are encouraged to focus on a single sensor type, exposing both high and low level as appropriate.

+

For an up-to-date list of extension specifications, please refer to [GENERIC-SENSOR-USECASES] and [MOTION-SENSORS] documents.

9.1. Security and Privacy

-

Extension specifications are expected to:

+

Extension specifications are expected to:

  • conform with the generic mitigation strategies,

    @@ -2841,7 +2841,7 @@

    9.2 A good starting point for naming are the Quantities, Units, Dimensions and Data Types Ontologies [QUDT].

    9.3. Unit

    -

    Extension specifications must specify the unit of sensor readings.

    +

    Extension specifications must specify the unit of sensor readings.

    As per the Technical Architecture Group’s (TAG) API Design Principles [API-DESIGN-PRINCIPLES], all time measurement should be in milliseconds. All other units should be specified using, @@ -2877,7 +2877,7 @@

    Providing low-level access enables Web application developers to leverage domain-specific constraints and design more performant systems.

    -

    Following the precepts of the Extensible Web Manifesto [EXTENNNNSIBLE], extension specifications should focus primarily on +

    Following the precepts of the Extensible Web Manifesto [EXTENNNNSIBLE], extension specifications should focus primarily on exposing low-level sensor APIs, but should also expose high-level APIs when they are clear benefits in doing so.

    9.5. When is Enabling Multiple Sensors of the Same Type Not the Right Choice?

    TODO: provide guidance on when to:

    @@ -2891,19 +2891,19 @@

    9.6. Definition Requirements

    The following definitions must be specified for -each sensor type in extension specifications:

    +each sensor type in extension specifications:

    -

    An extension specification may specify the following definitions +

    An extension specification may specify the following definitions for each sensor types:

    • @@ -2911,7 +2911,7 @@

      A default sensor. Generally, devices are equipped with a single platform sensor of each type, so defining a default sensor should be straightforward. - For sensor types where multiple sensors are common, extension specifications may choose not to define a default sensor, + For sensor types where multiple sensors are common, extension specifications may choose not to define a default sensor, especially when doing so would not make sense.

    • A set of identifying parameters. TODO: replace that by an abstract operation.

      @@ -2938,17 +2938,17 @@

      9.8. Example WebIDL

      Here’s example WebIDL for a possible extension of this specification for proximity sensors.

      -
      [Constructor(optional ProximitySensorOptions proximitySensorOptions),
+
      [Constructor(optional ProximitySensorOptions proximitySensorOptions),
  SecureContext, Exposed=Window]
 interface ProximitySensor : Sensor {
-    readonly attribute unrestricted double distance;
+    readonly attribute double? distance;
 };
 
 dictionary ProximitySensorOptions : SensorOptions {
-    double? min = -Infinity;
-    double? max = Infinity;
-    ProximitySensorPosition? position;
-    ProximitySensorDirection? direction;
+    double min;
+    double max;
+    ProximitySensorPosition position;
+    ProximitySensorDirection direction;
 };
 
 enum ProximitySensorPosition {
@@ -3424,12 +3424,16 @@ 
      The Extensible Web Manifesto. 10 June 2013. URL: https://extensiblewebmanifesto.org/
    
      [FEATURE-POLICY]
    
      Feature Policy. Living Standard. URL: https://wicg.github.io/feature-policy/
+   
      [GENERIC-SENSOR-USECASES]
+   
      Rick Waldron, Mikhail Pozdnyakov, Alexander Shalamov. Sensor Use Cases. 2017. Note. URL: https://w3c.github.io/sensors/usecases
    
      [GEOLOCATION-API]
    
      Andrei Popescu. Geolocation API Specification 2nd Edition. URL: http://dev.w3.org/geo/api/spec-source.html
    
      [GYROSPEECHRECOGNITION]
    
      Michalevsky, Y., Boneh, D. and Nakibly, G.. Gyrophone: Recognizing Speech from Gyroscope Signals. 2014. Informational. URL: https://www.usenix.org/system/files/conference/usenixsecurity14/sec14-paper-michalevsky.pdf
    
      [MOBILESENSORS]
    
      Manish J. Gajjar. Mobile Sensors and Context-Aware Computing. 2017. Informational. 
+   
      [MOTION-SENSORS]
+   
      Kenneth Christiansen; Alexander Shalamov. Motion Sensors Explainer. URL: https://w3c.github.io/motion-sensors/
    
      [ORIENTATION-EVENT]
    
      Rich Tibbett; et al. DeviceOrientation Event Specification. URL: https://w3c.github.io/deviceorientation/spec-source-orientation.html
    
      [QUDT]
@@ -3968,10 +3972,11 @@ 
      I