+This [=extension command=] makes a new [=sensor reading=] available to [=platform sensors=].
- The
[=extension command=] updates
- a given type of [=mock sensor=]'s [=mock sensor reading|reading=].
+Note: A [=virtual sensor=] acts like a [=device sensor=], so the [=sensor reading=] produced here
+still has to be processed by a [=platform sensor=], which might discard it due to, for example, a
+[=sensor type=]'s [=threshold check algorithm=] or [=can expose sensor readings=]'s result.
+
The [=remote end steps=] are:
- 1. Let |type| be a [=url variable=], [=converted to an IDL value=] of type {{MockSensorType}}.
- If this throws an exception, return an [=invalid argument=] [=error=].
- 1. If the [=current browsing context=] is [=no longer open=], return a [=no such window=] [=error=].
- 1. [=Handle any user prompts=], and return its value if it is an [=error=].
- 1. If |type| does not match a [=mock sensor type=] amongst all associated [=mock sensors=] of the
- [=current browsing context=], return a [=no such mock sensor=] [=error=].
- 1. Let |reading| be the |reading| argument, [=converted to an IDL value=] of the |type|'s
- associated {{MockSensorReadingValues}}. If this throws an exception, return an
- [=invalid argument=] [=error=].
- 1. [=map/For each=] |key| → value of |reading|.
- 1. [=map/Set=] [=mock sensor reading=][|key|] to the corresponding value of |reading|.
+ 1. Let |reading| be the result of invoking [=get a property=] "`reading`" from parameters.
+ 1. If |reading| is not an {{Object}}, return [=error=] with [=WebDriver error code=] [=invalid
+ argument=].
+ 1. Let |type| be the value of the `type` [=url variable=].
+ 1. If [=per-type virtual sensor metadata=] does not [=map/contain=] |type|, return [=error=]
+ with [=WebDriver error code=] [=invalid argument=].
+ 1. Let |metadata| be [=per-type virtual sensor metadata=][|type|].
+ 1. Let |sensorType| be |metadata|'s [=virtual sensor metadata/virtual sensor type=].
+ 1. Let |topLevelVirtualSensorMapping| be the [=current browsing context=]'s
+ [=browsing context/top-level traversable=]'s [=virtual sensor mapping=].
+ 1. If |topLevelVirtualSensorMapping| does not [=map/contain=] |sensorType|, return [=error=] with
+ [=WebDriver error code=] [=invalid argument=].
+ 1. Let |virtualSensor| be |topLevelVirtualSensorMapping|[|sensorType|].
+ 1. Let |parsedReading| be the result of invoking |metadata|'s [=virtual sensor metadata/reading
+ parsing algorithm=] with |reading|.
+ 1. If |parsedReading| is **undefined**, return [=error=] with [=WebDriver error code=]
+ [=invalid argument=].
+ 1. In an [=implementation-defined=] way, make |parsedReading| available so that it can be
+ obtained by [=platform sensors=] connected to |virtualSensor|.
1. Return [=success=] with data `null`.
-### Delete mock sensor ### {#delete-mock-sensor-command}
+#### Algorithms for parsing readings #### {#algorithms-for-parsing-readings}
+
+This specification defines some algorithms that [=extension specifications=] can use when defining
+a [=virtual sensor metadata=] for use in [=per-type virtual sensor metadata=].
+
+
+
+ : input
+ :: |parameters|, a JSON {{Object}}
+ :: |valueName|, a [=string=]
+ : output
+ :: A [=sensor reading=] or **undefined**
+
+ 1. Let |value| be the result of invoking [=get a property=] from |parameters| with |valueName|.
+ 1. If |value| is not a {{Number}}, or its value is **NaN**, +∞, or −∞, return **undefined**.
+ 1. Let |reading| be a new [=sensor reading=].
+ 1. [=map/Set=] |reading|[|valueName|] to |value|.
+ 1. Return |reading|.
+
+
+Parse XYZ reading
+
+
+ : input
+ :: |parameters|, a JSON {{Object}}
+ : output
+ :: A [=sensor reading=] or **undefined**
+
+ 1. Let |x| be the result of invoking [=get a property=] from |parameters| with "`x`".
+ 1. If |x| is not a {{Number}}, or its value is **NaN**, +∞, or −∞, return **undefined**.
+ 1. Let |y| be the result of invoking [=get a property=] from |parameters| with "`y`".
+ 1. If |y| is not a {{Number}}, or its value is **NaN**, +∞, or −∞, return **undefined**.
+ 1. Let |z| be the result of invoking [=get a property=] from |parameters| with "`z`".
+ 1. If |z| is not a {{Number}}, or its value is **NaN**, +∞, or −∞, return **undefined**.
+ 1. Let |reading| be a new [=sensor reading=].
+ 1. [=map/Set=] |reading|["`x`"] to |x|.
+ 1. [=map/Set=] |reading|["`y`"] to |y|.
+ 1. [=map/Set=] |reading|["`z`"] to |z|.
+ 1. Return |reading|.
+
+
+Parse quaternion reading
+
+
+ : input
+ :: |parameters|, a JSON {{Object}}
+ : output
+ :: A [=sensor reading=] or **undefined**
+
+ 1. Let |quaternionArray| be the result of invoking [=get a property=] from |parameters| with
+ "`quaternion`".
+ 1. If |quaternionArray| is not an {{Array}}, or if its "`length`" property is not 4, return
+ **undefined**.
+ 1. Let |x| be the result of invoking [=get a property=] from |quaternionArray| with 0.
+ 1. If |x| is not a {{Number}}, or its value is **NaN**, +∞, or −∞, return **undefined**.
+ 1. Let |y| be the result of invoking [=get a property=] from |quaternionArray| with 1.
+ 1. If |y| is not a {{Number}}, or its value is **NaN**, +∞, or −∞, return **undefined**.
+ 1. Let |z| be the result of invoking [=get a property=] from |quaternionArray| with 2.
+ 1. If |z| is not a {{Number}}, or its value is **NaN**, +∞, or −∞, return **undefined**.
+ 1. Let |w| be the result of invoking [=get a property=] from |quaternionArray| with 3.
+ 1. If |w| is not a {{Number}}, or its value is **NaN**, +∞, or −∞, return **undefined**.
+ 1. Let |reading| be a new [=sensor reading=].
+ 1. [=map/Set=] |reading|["`quaternion`"] be the [=/list=] « |x|, |y|, |z|, |w| ».
+ 1. Return |reading|.
+
+
+### Delete virtual sensor ### {#delete-virtual-sensor-command}
+
+
| HTTP Method |
@@ -1875,51 +1937,27 @@ Each [=mock sensor type=] has a [=mock sensor reading values=] dictionary:
-
-
- The
delete mock sensor [=extension command=] deletes
- a given type of [=mock sensor=].
+This [=extension command=] deletes a given type of [=virtual sensor=].
+
The [=remote end steps=] are:
- 1. Let |type| be a [=url variable=].
- 1. If {{MockSensorType}} [=set/contains|does not contain=] |type|, return an [=invalid argument=] [=error=].
- 1. If the [=current browsing context=] is [=no longer open=], return a [=no such window=] [=error=].
- 1. [=Handle any user prompts=], and return its value if it is an [=error=].
- 1. If |type| does not match a [=mock sensor type=] amongst all associated [=mock sensors=] of the
- [=current browsing context=], return a [=no such mock sensor=] [=error=].
- 1. Delete |type| of [=mock sensor=] in [=current browsing context=].
+ 1. Let |type| be the value of the `type` [=url variable=].
+ 1. If [=per-type virtual sensor metadata=] does not [=map/contain=] |type|, return [=error=]
+ with [=WebDriver error code=] [=invalid argument=].
+ 1. Let |sensorType| be [=per-type virtual sensor metadata=][|type|]'s [=virtual sensor
+ metadata/virtual sensor type=].
+ 1. Let |topLevelVirtualSensorMapping| be the [=current browsing context=]'s
+ [=browsing context/top-level traversable=]'s [=virtual sensor mapping=].
+ 1. [=map/Remove=] |topLevelVirtualSensorMapping|[|sensorType|].
1. Return [=success=] with data `null`.
-
Handling errors
-
-This section extends the [[WEBDRIVER2#errors]] section and defines extended [=WebDriver error codes=]
-specific for [=mock sensor=] in following table.
-
-
-
-
- | Error Code | HTTP Status | JSON Error Code | Description |
-
-
-
-
- | no such mock sensor |
- 404 |
- no such mock sensor |
- no mock sensor matching the given type was found. |
-
-
- | mock sensor already created |
- 500 |
- mock sensor already created |
-
- A [[#section-extension-commands|command]] to create a [=mock sensor=] could not be
- satisfied because the given type of [=mock sensor=] is already existed.
- |
-
-
-
+Note: The behavior of [=platform sensors=] and {{Sensor}} instances when a [=device sensor=] in use
+stops being available (e.g. it has been physically disconnected, or stopped due to a factor
+unrelated to the User Agent) is not specified. Implementations may, among other things, keep
+existing {{Sensor}} instances unchanged (they simply will not report new readings), [=deactivate a
+sensor object=] or cause the [=platform sensor=] to report an error that will ultimately result in
+[=notify error=] being invoked.
Extensibility
@@ -2088,10 +2126,28 @@ for each [=sensor type=]:
In order to enable user-agent automation and application testing,
[=extension specifications=] are encouraged to:
-- Add new [=mock sensor type=] for each [=extension sensor interface=]
- to the {{MockSensorType}} enum.
-- Define a [=mock sensor reading values=] dictionary.
+- Add one or more [=map/entries=] to [=per-type virtual sensor metadata=].
+- Consequently, define one or more [=virtual sensor metadata=] instances.
+
+
+ The [=extension specification=] for proximity sensors described in [[#example-webidl]] could
+ contain the following text:
+
+
+ The **Proximity Sensor** is a [=sensor type=] with one associated [=extension sensor
+ interface=], `ProximitySensor`.
+
+ *[...]*
+ The **proximity reading parsing algorithm**, given a JSON {{Object}} *parameters*, must
+ invoke [=parse single-value number reading=] with *parameters* and "`distance`".
+
+ The [=per-type virtual sensor metadata=] [=map=] must have an entry whose key is "`proximity`"
+ and whose value is a [=virtual sensor metadata=] whose [=virtual sensor metadata/virtual sensor
+ type=] is the *Proximity Sensor* [=sensor type=] and with a [=virtual sensor metadata/reading
+ parsing algorithm=] of *proximity reading parsing algorithm*.
+
+
Extending the Permission API