diff --git a/index.html b/index.html index f5a79f5..67fae42 100644 --- a/index.html +++ b/index.html @@ -5,11 +5,10 @@ Geolocation Sensor - + - - - + - + - + - + - - + - + - - +

Geolocation Sensor

-

Editor’s Draft,

-
-
-
This version: -
https://w3c.github.io/geolocation-sensor/ -
Latest published version: -
https://www.w3.org/TR/geolocation-sensor/ -
Feedback: -
public-device-apis@w3.org with subject line “[geolocation-sensor] … message topic …” (archives) -
Geolocation Sensor Issues Repository -
Editors: -
Anssi Kostiainen (Intel Corporation) -
Thomas Steiner (Google Inc.) -
Marijn Kruisselbrink (Google Inc.) -
Tests: -
web-platform-tests -
Polyfills: -
geolocation-sensor.js
geolocation.js -
-
+

Editor’s Draft,

+
+ More details about this document +
+
+
This version: +
https://w3c.github.io/geolocation-sensor/ +
Latest published version: +
https://www.w3.org/TR/geolocation-sensor/ +
Feedback: +
public-device-apis@w3.org with subject line “[geolocation-sensor] … message topic …” (archives) +
Geolocation Sensor Issues Repository +
Editors: +
Anssi Kostiainen (Intel Corporation) +
Thomas Steiner (Google Inc.) +
Marijn Kruisselbrink (Google Inc.) +
Tests: +
web-platform-tests +
Polyfills: +
geolocation-sensor.js
geolocation.js +
+
+
-

Copyright © 2022 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.

+

Copyright © 2023 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.

@@ -633,11 +716,11 @@

This document was produced by the Devices and Sensors Working Group.

This document was produced by a group operating under - the W3C Patent Policy. + the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

-

This document is governed by the 2 November 2021 W3C Process Document.

+

This document is governed by the 12 June 2023 W3C Process Document.

The Devices and Sensors Working Group will perform a round of self-review and @@ -677,7 +760,7 @@

Table of Contents

  • 7 Automation
      -
    1. 7.1 Mock Sensor Type +
    2. 7.1 Geolocation reading parsing algorithm
  • 8 Use Cases @@ -733,9 +816,9 @@

    Table of Contents

    1. Introduction

    -

    The GeolocationSensor API extends the Sensor interface [GENERIC-SENSOR] to provide +

    The GeolocationSensor API extends the Sensor interface [GENERIC-SENSOR] to provide information about the geolocation of the hosting device.

    -

    The feature set of the GeolocationSensor is similar to that of the Geolocation API [GEOLOCATION-API], but it is surfaced through a modern API that is consistent across contemporary sensor APIs, improves security and privacy, and is extensible. The API aims to be polyfillable (example) +

    The feature set of the GeolocationSensor is similar to that of the Geolocation API [GEOLOCATION-API], but it is surfaced through a modern API that is consistent across contemporary sensor APIs, improves security and privacy, and is extensible. The API aims to be polyfillable (example) on top of the existing Geolocation API.

    2. Examples

    Get a new geolocation reading every second:

    @@ -758,20 +841,20 @@

    2.

    • 3. Security and Privacy Considerations

    -

    Note: Investigate any geolocation-specific security and privacy considerations that are not -mitigated by the Generic Sensor API [GENERIC-SENSOR], and define geolocation-specific +

    Note: Investigate any geolocation-specific security and privacy considerations that are not +mitigated by the Generic Sensor API [GENERIC-SENSOR], and define geolocation-specific mitigations.

    4. Model

    The term geolocation refers to the real-world geographic location of the -hosting device represented in geographic coordinates [WGS84].

    -

    Note: An implementation can use multiple location information sources to acquire geolocation information, and this specification is agnostic with respect +hosting device represented in geographic coordinates [WGS84].

    +

    Note: An implementation can use multiple location information sources to acquire geolocation information, and this specification is agnostic with respect to those sources.

    The Geolocation Sensor sensor type’s associated Sensor subclass is the GeolocationSensor class.

    The Geolocation Sensor has an associated PermissionName which is "geolocation".

    -

    The Geolocation Sensor is a policy-controlled feature identified by the string "geolocation". Its default allowlist is 'self'.

    +

    The Geolocation Sensor is a policy-controlled feature identified by the string "geolocation". Its default allowlist is 'self'.

    A latest geolocation reading is a latest reading for a Sensor of Geolocation Sensor sensor type. It includes entries whose keys are "latitude", "longitude", "altitude", "accuracy", "altitudeAccuracy", "heading", "speed" and whose values contain the device’s geolocation.

    -

    Note: Consider adding a visual of the standard coordinate system for the Earth.

    +

    Note: Consider adding a visual of the standard coordinate system for the Earth.

    5. API

    5.1. The GeolocationSensor Interface

    [SecureContext,
@@ -882,15 +965,15 @@ 
    5.1.2. GeolocationSensor.latitude
    
    
    The latitude attribute of the GeolocationSensor interface
 returns the result of invoking get value from latest reading with this and "latitude" as
-arguments. It represents the latitude coordinate of the geolocation in decimal degrees [WGS84].
    
+arguments. It represents the latitude coordinate of the geolocation in decimal degrees [WGS84].
    
    
    5.1.3. GeolocationSensor.longitude
    
    
    The longitude attribute of the GeolocationSensor interface
 returns the result of invoking get value from latest reading with this and "longitude" as
-arguments. It represents the longitude coordinate of the geolocation in decimal degrees [WGS84].
    
+arguments. It represents the longitude coordinate of the geolocation in decimal degrees [WGS84].
    
    
    5.1.4. GeolocationSensor.altitude
    
    
    The altitude attribute of the GeolocationSensor interface
 returns the result of invoking get value from latest reading with this and "altitude" as
-arguments. It represents the geolocation in meters above the WGS 84 ellipsoid [WGS84].
    
+arguments. It represents the geolocation in meters above the WGS 84 ellipsoid [WGS84].
    
    
    5.1.5. GeolocationSensor.accuracy
    
    
    The accuracy attribute of the GeolocationSensor interface
 returns the result of invoking get value from latest reading with this and "accuracy" as
@@ -940,20 +1023,51 @@ 
    
    
    
    7. Automation
    
-    This section extends the automation section defined in the Generic Sensor API [GENERIC-SENSOR] to provide mocking information about the geolocation of the hosting device for the purposes of
-testing a user agent’s implementation of GeolocationSensor API. 
-   
    7.1. Mock Sensor Type
    
-   
    The GeolocationSensor class has an associated mock sensor type which is "geolocation", its mock sensor reading values dictionary is defined as follows:
    
-
    dictionary GeolocationReadingValues {
-  required double? latitude;
-  required double? longitude;
-  required double? altitude;
-  required double? accuracy;
-  required double? altitudeAccuracy;
-  required double? heading;
-  required double? speed;
-};
-
    
+   
    This section extends Generic Sensor API § 9 Automation by providing Geolocation Sensor-specific virtual sensor metadata.
    
+   
    The per-type virtual sensor metadata map must have the following entry:
    
+   
    
+    
    key
+    
    
+     
    "geolocation"
    
+    
    value
+    
    
+     
    A virtual sensor metadata whose virtual sensor type is Geolocation Sensor and reading parsing algorithm is the geolocation reading parsing algorithm.
    
+   
    
+   
    7.1. Geolocation reading parsing algorithm
    
+   
    
+    
    
+     
    input
+     
    
+      
    parameters, a JSON Object
    
+     
    output
+     
    
+      
    A sensor reading or undefined
    
+    
    
+    
      
+     
    1. 
+      
      Let reading be a new sensor reading.
      
+     
    2. 
+      
      Let keys be the list « "latitude", "longitude", "altitude", "accuracy", "altitudeAccuracy", "heading", "speed" ».
      
+     
    3. 
+      
      For each key of keys
      
+      
        
+       
      1. 
+        
        Let value be the result of invoking parse single-value number reading with parameters and key.
        
+        
          
+         
        1. 
+          
          If value is undefined.
          
+          
            
+           
          1. 
+            
            Return undefined.
            
+          
          
+        
        
+       
      2. 
+        
        Set reading[key] to value[key].
        
+      
      
+     
    4. 
+      
      Return reading.
      
+    
    
+   
    
    
    8. Use Cases
    
    
    8.1. Categorization of use cases
    
    
    The mentioned use cases can roughly be grouped into four categories:
    
@@ -975,7 +1089,7 @@ 
    Getting a one-off geolocation fence alert (aka. background geofencing).
    
      
    
-   
    Note: Only the foreground operations were possible with [GEOLOCATION-API],
+   
    Note: Only the foreground operations were possible with [GEOLOCATION-API],
 the background operations are completely novel.
    
    
    Core constraints when obtaining the gelocation are accuracy (how close to the
 actual position of the user is the determined position) and latency (how long does the user want to wait for a result). Both are tradeoffs:
@@ -984,7 +1098,7 @@ 
    
    
    In the following, we list use cases based on the previously defined categories.
    
-   
    Note: The categories are not mutually exclusive and overlaps exist.
+   
    Note: The categories are not mutually exclusive and overlaps exist.
 A task might start in the foreground, then continue in the background (for example,
 while the user quickly responds to an incoming email),
 and then eventually terminate in the foreground when the user multitasks back.
    
@@ -1076,28 +1190,25 @@ 
    attribute for GeolocationSensor, in § 5.1
-     
  • dict-member for GeolocationReadingValues, in § 7.1
      
  • dict-member for GeolocationSensorReading, in § 5.1
     
    
  • 
     altitude
     
    
  • 
     altitudeAccuracy
     
    
  • Construct a geolocation sensor object, in § 6
    
  • constructor(), in § 5.1
    
  • constructor(options), in § 5.1
    
  • geolocation, in § 4
-   
  • GeolocationReadingValues, in § 7.1
+   
  • Geolocation reading parsing algorithm, in § 7
    
  • Geolocation Sensor, in § 4
    
  • GeolocationSensor, in § 5.1
    
  • GeolocationSensor(), in § 5.1
@@ -1108,7 +1219,6 @@ 
    attribute for GeolocationSensor, in § 5.1
-     
  • dict-member for GeolocationReadingValues, in § 7.1
      
  • dict-member for GeolocationSensorReading, in § 5.1
     
    
  • latest geolocation reading, in § 4
@@ -1116,14 +1226,12 @@ 
    attribute for GeolocationSensor, in § 5.1
-     
  • dict-member for GeolocationReadingValues, in § 7.1
      
  • dict-member for GeolocationSensorReading, in § 5.1
     
    
  • 
     longitude
     
    
  • read(), in § 5.1
@@ -1135,318 +1243,88 @@ 
    attribute for GeolocationSensor, in § 5.1
-     
  • dict-member for GeolocationReadingValues, in § 7.1
      
  • dict-member for GeolocationSensorReading, in § 5.1
     
    
  • timestamp, in § 5.1
   
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
-  
   
    Terms defined by reference
    
   
      
    
    • 
     [DOM] defines the following terms:
     
        
-     
      • AbortSignal
-     
      • abort reason
-     
      • aborted
-     
      • add the following abort steps
+     
      • AbortSignal
+     
      • abort reason
+     
      • aborted
+     
      • add the following abort steps
+    
      
+   
    • 
+    [ECMASCRIPT] defines the following terms:
+    
        
+     
      • Object
     
      
    
    • 
     [GENERIC-SENSOR] defines the following terms:
     
        
-     
      • "geolocation"
-     
      • Sensor
-     
      • SensorOptions
-     
      • automation
-     
      • check sensor policy-controlled features
-     
      • extensible
-     
      • get value from latest reading
-     
      • initialize a sensor object
-     
      • latest reading
-     
      • mock sensor reading values
-     
      • mock sensor type
-     
      • notify error
-     
      • notify new reading
-     
      • security and privacy
-     
      • sensor type
-     
      • start()
-     
      • stop()
+     
      • Sensor
+     
      • SensorOptions
+     
      • check sensor policy-controlled features
+     
      • extensible
+     
      • get value from latest reading
+     
      • initialize a sensor object
+     
      • latest reading
+     
      • notify error
+     
      • notify new reading
+     
      • parse single-value number reading
+     
      • per-type virtual sensor metadata
+     
      • reading parsing algorithm
+     
      • security and privacy
+     
      • sensor reading
+     
      • sensor type
+     
      • start()
+     
      • stop()
+     
      • virtual sensor metadata
+     
      • virtual sensor type
     
      
    
    • 
-    [hr-time-2] defines the following terms:
+    [HR-TIME-2] defines the following terms:
     
        
-     
      • DOMHighResTimeStamp
+     
      • DOMHighResTimeStamp
     
      
    
    • 
     [HTML] defines the following terms:
     
        
-     
      • in parallel
+     
      • in parallel
     
      
    
    • 
     [INFRA] defines the following terms:
     
        
-     
      • entry
-     
      • for each
-     
      • keys
-     
      • set
-     
      • values
+     
      • entry
+     
      • for each
+     
      • key
+     
      • keys
+     
      • list
+     
      • map
+     
      • set
+     
      • value
+     
      • values
     
      
    
    • 
-    [permissions-policy-1] defines the following terms:
+    [PERMISSIONS-POLICY-1] defines the following terms:
     
        
-     
      • default allowlist
-     
      • policy-controlled feature
+     
      • default allowlist
+     
      • policy-controlled feature
     
      
    
    • 
     [WEBIDL] defines the following terms:
     
        
-     
      • DOMException
-     
      • Exposed
-     
      • Promise
-     
      • SecureContext
-     
      • SecurityError
-     
      • double
-     
      • throw
-     
      • unrestricted double
+     
      • DOMException
+     
      • Exposed
+     
      • Promise
+     
      • SecureContext
+     
      • SecurityError
+     
      • double
+     
      • throw
+     
      • unrestricted double
     
      
   
    
   
    References
    
@@ -1454,6 +1332,8 @@ 
    N
   
    
    
    [DOM]
    
    Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
+   
    [ECMASCRIPT]
+   
    ECMAScript Language Specification. URL: https://tc39.es/ecma262/multipage/
    
    [GENERIC-SENSOR]
    
    Rick Waldron. Generic Sensor API. URL: https://w3c.github.io/sensors/
    
    [HR-TIME-2]
@@ -1508,278 +1388,670 @@ 
    I
   double? speed;
 };
 
-dictionary GeolocationReadingValues {
-  required double? latitude;
-  required double? longitude;
-  required double? altitude;
-  required double? accuracy;
-  required double? altitudeAccuracy;
-  required double? heading;
-  required double? speed;
-};
-
    • - - - - - - - - - - - - - - - - - - + - + + \ No newline at end of file + function previousHighlightIndex(algoName, varName) { + return indexNames.get(algoName+"///"+varName); + } + function nameFromIndex(index) { + return "selected" + index; + } +} + \ No newline at end of file