Add information to "Extending the Permission API" section (#265)

* Add information to "Extending the Permission API" section Fixes: #132 Fixes: #22
w3c · Sep 20, 2017 · 298c81d · 298c81d
1 parent d5f75e3
commit 298c81d
Show file tree

Hide file tree

Showing 2 changed files with 57 additions and 15 deletions.
diff --git a/index.bs b/index.bs
@@ -1568,12 +1568,33 @@ for each [=sensor types=]:
     especially when doing so would not make sense.
 -   A set of [=identifying parameters=]. TODO: replace that by an abstract operation.
 
-
 <h3 id="permission-api">Extending the Permission API</h3>
 
-Provide guidance on how to extend the Permission API [[PERMISSIONS]]
-for each [=sensor types=].
+An implementation of the {{Sensor}} interface for each [=sensor type=] must protect its
+[=sensor reading|reading=] by associated {{PermissionName}} or {{PermissionDescriptor}}.
+A [=Low-level=] {{Sensor|sensor}} may use its interface name as a {{PermissionName}},
+for instance, "gyroscope" or "accelerometer". [=sensor fusion|Fusion sensors=] must
+[=request permission to use|request permission to access=] each of the sensors that are
+used as a source of fusion.
+
+Even though, it might be difficult to reconstruct [=low-level=] [=sensor readings=] from
+fused data, some of the original information might be inferred. For example, it is easy to
+deduce user's orientation in space if absolute or geomagnetic orientation sensors are used,
+therefore, these sensors must [=request permission to use|request permission to use=]
+magnetometer as it provides information about orientation of device in relation to Earth's
+magnetic field. In contrast, relative orientation sensor does not expose such information, thus,
+it does not need to [=request permission to use|request permission to use=] magnetometer.
+
+{{PermissionDescriptor|Permission descriptors}} can also be used to set maximum allowed limits
+for accuracy or [=sampling frequency=]. An example for a possible extension of the Permission API
+for accelerometer sensor is given below.
 
+<pre class=example>
+    dictionary AccelerometerPermissionDescriptor : PermissionDescriptor {
+        boolean highAccuracy = false;
+        boolean highFrequency = false;
+    };
+</pre>
 
 <h3 id="example-webidl">Example WebIDL</h3>
 

diff --git a/index.html b/index.html
@@ -1183,9 +1183,8 @@
       background-attachment: fixed;
     }
   </style>
-  <meta content="Bikeshed version 6e949445d0006e32e94031287e7088aa812092a0" name="generator">
+  <meta content="Bikeshed version df778ba2d9793f77f64705dbba65d0c50f68e0d9" name="generator">
   <link href="https://www.w3.org/TR/generic-sensor/" rel="canonical">
-  <meta content="a271b771f69cb3be985187585eb39f4467226e1c" name="document-revision">
 <style>
     emu-val {
       font-weight: bold;
@@ -1459,7 +1458,7 @@
   <div class="head">
    <p data-fill-with="logo"><a class="logo" href="https://www.w3.org/"> <img alt="W3C" height="48" src="https://www.w3.org/StyleSheets/TR/2016/logos/W3C" width="72"> </a> </p>
    <h1 class="p-name no-ref" id="title">Generic Sensor API</h1>
-   <h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Editor’s Draft, <time class="dt-updated" datetime="2017-09-18">18 September 2017</time></span></h2>
+   <h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="content">Editor’s Draft, <time class="dt-updated" datetime="2017-09-20">20 September 2017</time></span></h2>
    <div data-fill-with="spec-metadata">
     <dl>
      <dt>This version:
@@ -1470,15 +1469,15 @@ <h2 class="no-num no-toc no-ref heading settled" id="subtitle"><span class="cont
      <dd><a href="https://www.w3.org/TR/2017/WD-generic-sensor-20170530/" rel="prev">https://www.w3.org/TR/2017/WD-generic-sensor-20170530/</a>
      <dt>Feedback:
      <dd><span><a href="mailto:public-device-apis@w3.org?subject=%5Bgeneric-sensor%5D%20YOUR%20TOPIC%20HERE">public-device-apis@w3.org</a> with subject line “<kbd>[generic-sensor] <i data-lt="">… message topic …</i></kbd>” (<a href="https://lists.w3.org/Archives/Public/public-device-apis/" rel="discussion">archives</a>)</span>
-     <dd><span><a href="https://github.com/w3c/sensors">GitHub</a> (<a href="https://github.com/w3c/sensors/issues/new">new issue</a>, <a href="https://github.com/w3c/sensors/milestone/2">level 1 issues</a>, <a href="https://github.com/w3c/sensors/issues">all issues</a>)</span>
+     <dd><a href="https://github.com/w3c/sensors">GitHub</a> (<a href="https://github.com/w3c/sensors/issues/new">new issue</a>, <a href="https://github.com/w3c/sensors/milestone/2">level 1 issues</a>, <a href="https://github.com/w3c/sensors/issues">all issues</a>)
      <dt class="editor">Editors:
      <dd class="editor p-author h-card vcard" data-editor-id="50572"><span class="p-name fn">Rick Waldron</span> (<span class="p-org org">JS Foundation</span>)
      <dd class="editor p-author h-card vcard" data-editor-id="78325"><a class="p-name fn u-url url" href="https://intel.com/">Mikhail Pozdnyakov</a> (<span class="p-org org">Intel Corporation</span>)
      <dd class="editor p-author h-card vcard" data-editor-id="78335"><a class="p-name fn u-url url" href="https://intel.com/">Alexander Shalamov</a> (<span class="p-org org">Intel Corporation</span>)
      <dt class="editor">Former Editor:
      <dd class="editor p-author h-card vcard" data-editor-id="60809"><a class="p-name fn u-url url" href="http://tobie.me">Tobie Langel</a> (<span class="p-org org">Codespeaks, formerly on behalf of Intel Corporation</span>) <a class="u-email email" href="mailto:tobie@codespeaks.com">tobie@codespeaks.com</a>
      <dt>Other:
-     <dd><span><a href="https://github.com/w3c/web-platform-tests/tree/master/generic-sensor">Test suite</a>, <a href="https://github.com/w3c/sensors/commits/master/index.bs">latest version history</a>, <a href="https://github.com/w3c/sensors/commits/gh-pages/index.bs">previous version history</a></span>
+     <dd><a href="https://github.com/w3c/web-platform-tests/tree/master/generic-sensor">Test suite</a>, <a href="https://github.com/w3c/sensors/commits/master/index.bs">latest version history</a>, <a href="https://github.com/w3c/sensors/commits/gh-pages/index.bs">previous version history</a>
     </dl>
    </div>
    <div data-fill-with="warning"></div>
@@ -1732,7 +1731,7 @@ <h2 class="heading settled" data-level="3" id="background"><span class="secno">3
    <div class="example" id="example-fdd94e11">
     <a class="self-link" href="#example-fdd94e11"></a> For example checking the pressure of the left rear tire: 
 <pre class="highlight"><span class="kd">var</span> sensor <span class="o">=</span> <span class="k">new</span> DirectTirePressureSensor<span class="p">({</span> position<span class="o">:</span> <span class="s2">"rear"</span><span class="p">,</span> side<span class="o">:</span> <span class="s2">"left"</span> <span class="p">});</span>
-sensor<span class="p">.</span>onreading <span class="o">=</span> _ <span class="o">=></span> console<span class="p">.</span>log<span class="p">(</span>sensor<span class="p">.</span>pressure<span class="p">);</span>
+sensor<span class="p">.</span>onreading <span class="o">=</span> _ <span class="p">=></span> console<span class="p">.</span>log<span class="p">(</span>sensor<span class="p">.</span>pressure<span class="p">);</span>
 sensor<span class="p">.</span>start<span class="p">();</span>
 </pre>
    </div>
@@ -1796,8 +1795,8 @@ <h2 class="heading settled" data-level="4" id="feature-detection"><span class="s
 <pre class="highlight"><span class="k">try</span> <span class="p">{</span> <span class="c1">// No need to feature detect thanks to try..catch block.</span>
 <span class="c1"></span>    <span class="kd">var</span> sensor <span class="o">=</span> <span class="k">new</span> GeolocationSensor<span class="p">();</span>
     sensor<span class="p">.</span>start<span class="p">();</span>
-    sensor<span class="p">.</span>onerror <span class="o">=</span> error <span class="o">=></span> gracefullyDegrade<span class="p">(</span>error<span class="p">);</span>
-    sensor<span class="p">.</span>onreading <span class="o">=</span> _ <span class="o">=></span> updatePosition<span class="p">(</span>sensor<span class="p">.</span>latitude<span class="p">,</span> sensor<span class="p">.</span>longitude<span class="p">);</span>
+    sensor<span class="p">.</span>onerror <span class="o">=</span> error <span class="p">=></span> gracefullyDegrade<span class="p">(</span>error<span class="p">);</span>
+    sensor<span class="p">.</span>onreading <span class="o">=</span> _ <span class="p">=></span> updatePosition<span class="p">(</span>sensor<span class="p">.</span>latitude<span class="p">,</span> sensor<span class="p">.</span>longitude<span class="p">);</span>
 <span class="p">}</span> <span class="k">catch</span><span class="p">(</span>error<span class="p">)</span> <span class="p">{</span>
     gracefullyDegrade<span class="p">(</span>error<span class="p">);</span>
 <span class="p">}</span>
@@ -2142,9 +2141,9 @@ <h3 class="heading settled" data-level="8.1" id="the-sensor-interface"><span cla
     <p>The <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/webappapis.html#event-handler-event-type" id="ref-for-event-handler-event-type">event handler event types</a> for the corresponding <a href="#the-sensor-interface"> Sensor Interface</a>'s <a data-link-type="dfn" href="https://html.spec.whatwg.org/multipage/webappapis.html#event-handlers" id="ref-for-event-handlers">event handler</a> attributes are defined in <a href="#event-handlers">Event handlers</a> section.</p>
 <pre class="highlight"><span class="kd">let</span> acl <span class="o">=</span> <span class="k">new</span> Accelerometer<span class="p">({</span>frequency<span class="o">:</span> <span class="mi">30</span><span class="p">});</span>
 <span class="kd">let</span> max_magnitude <span class="o">=</span> <span class="mi">0</span><span class="p">;</span>
-acl<span class="p">.</span>addEventListener<span class="p">(</span><span class="s1">'activate'</span><span class="p">,</span> <span class="p">()</span> <span class="o">=></span> console<span class="p">.</span>log<span class="p">(</span><span class="s1">'Ready to measure.'</span><span class="p">));</span>
-acl<span class="p">.</span>addEventListener<span class="p">(</span><span class="s1">'error'</span><span class="p">,</span> error <span class="o">=></span> console<span class="p">.</span>log<span class="p">(</span><span class="s1">'Error: '</span> <span class="o">+</span> error<span class="p">.</span>name<span class="p">));</span>
-acl<span class="p">.</span>addEventListener<span class="p">(</span><span class="s1">'reading'</span><span class="p">,</span> <span class="p">()</span> <span class="o">=></span> <span class="p">{</span>
+acl<span class="p">.</span>addEventListener<span class="p">(</span><span class="s1">'activate'</span><span class="p">,</span> <span class="p">()</span> <span class="p">=></span> console<span class="p">.</span>log<span class="p">(</span><span class="s1">'Ready to measure.'</span><span class="p">));</span>
+acl<span class="p">.</span>addEventListener<span class="p">(</span><span class="s1">'error'</span><span class="p">,</span> error <span class="p">=></span> console<span class="p">.</span>log<span class="p">(</span><span class="s1">'Error: '</span> <span class="o">+</span> error<span class="p">.</span>name<span class="p">));</span>
+acl<span class="p">.</span>addEventListener<span class="p">(</span><span class="s1">'reading'</span><span class="p">,</span> <span class="p">()</span> <span class="p">=></span> <span class="p">{</span>
     <span class="kd">let</span> magnitude <span class="o">=</span> Math<span class="p">.</span>hypot<span class="p">(</span>acl<span class="p">.</span>x<span class="p">,</span> acl<span class="p">.</span>y<span class="p">,</span> acl<span class="p">.</span>z<span class="p">);</span>
     <span class="k">if</span> <span class="p">(</span>magnitude <span class="o">></span> max_magnitude<span class="p">)</span> <span class="p">{</span>
         max_magnitude <span class="o">=</span> magnitude<span class="p">;</span>
@@ -2972,7 +2971,24 @@ <h3 class="heading settled" data-level="10.6" id="definition-reqs"><span class="
      <p>A set of <a data-link-type="dfn" href="#identifying-parameters" id="ref-for-identifying-parameters②">identifying parameters</a>. TODO: replace that by an abstract operation.</p>
    </ul>
    <h3 class="heading settled" data-level="10.7" id="permission-api"><span class="secno">10.7. </span><span class="content">Extending the Permission API</span><a class="self-link" href="#permission-api"></a></h3>
-   <p>Provide guidance on how to extend the Permission API <a data-link-type="biblio" href="#biblio-permissions">[PERMISSIONS]</a> for each <a data-link-type="dfn" href="#sensor-type" id="ref-for-sensor-type③⑥">sensor types</a>.</p>
+   <p>An implementation of the <code class="idl"><a data-link-type="idl" href="#sensor" id="ref-for-sensor③⓪">Sensor</a></code> interface for each <a data-link-type="dfn" href="#sensor-type" id="ref-for-sensor-type③⑥">sensor type</a> must protect its <a data-link-type="dfn" href="#sensor-readings" id="ref-for-sensor-readings④⑦">reading</a> by associated <code class="idl"><a data-link-type="idl" href="https://w3c.github.io/permissions/#enumdef-permissionname" id="ref-for-enumdef-permissionname⑥">PermissionName</a></code> or <code class="idl"><a data-link-type="idl" href="https://w3c.github.io/permissions/#dictdef-permissiondescriptor" id="ref-for-dictdef-permissiondescriptor①">PermissionDescriptor</a></code>.
+A <a data-link-type="dfn" href="#low-level" id="ref-for-low-level①③">Low-level</a> <code class="idl"><a data-link-type="idl" href="#sensor" id="ref-for-sensor③①">sensor</a></code> may use its interface name as a <code class="idl"><a data-link-type="idl" href="https://w3c.github.io/permissions/#enumdef-permissionname" id="ref-for-enumdef-permissionname⑦">PermissionName</a></code>,
+for instance, "gyroscope" or "accelerometer". <a data-link-type="dfn" href="#sensor-fusion" id="ref-for-sensor-fusion⑦">Fusion sensors</a> must <a data-link-type="dfn" href="https://w3c.github.io/permissions/#request-permission-to-use" id="ref-for-request-permission-to-use①">request permission to access</a> each of the sensors that are
+used as a source of fusion.</p>
+   <p>Even though, it might be difficult to reconstruct <a data-link-type="dfn" href="#low-level" id="ref-for-low-level①④">low-level</a> <a data-link-type="dfn" href="#sensor-readings" id="ref-for-sensor-readings④⑧">sensor readings</a> from
+fused data, some of the original information might be inferred. For example, it is easy to
+deduce user’s orientation in space if absolute or geomagnetic orientation sensors are used,
+therefore, these sensors must <a data-link-type="dfn" href="https://w3c.github.io/permissions/#request-permission-to-use" id="ref-for-request-permission-to-use②">request permission to use</a> magnetometer as it provides information about orientation of device in relation to Earth’s
+magnetic field. In contrast, relative orientation sensor does not expose such information, thus,
+it does not need to <a data-link-type="dfn" href="https://w3c.github.io/permissions/#request-permission-to-use" id="ref-for-request-permission-to-use③">request permission to use</a> magnetometer.</p>
+   <p><code class="idl"><a data-link-type="idl" href="https://w3c.github.io/permissions/#dictdef-permissiondescriptor" id="ref-for-dictdef-permissiondescriptor②">Permission descriptors</a></code> can also be used to set maximum allowed limits
+for accuracy or <a data-link-type="dfn" href="#sampling-frequency" id="ref-for-sampling-frequency⑥">sampling frequency</a>. An example for a possible extension of the Permission API
+for accelerometer sensor is given below.</p>
+<pre class="example" id="example-6d08453b"><a class="self-link" href="#example-6d08453b"></a>dictionary AccelerometerPermissionDescriptor : PermissionDescriptor {
+    boolean highAccuracy = false;
+    boolean highFrequency = false;
+};
+</pre>
    <h3 class="heading settled" data-level="10.8" id="example-webidl"><span class="secno">10.8. </span><span class="content">Example WebIDL</span><a class="self-link" href="#example-webidl"></a></h3>
    <p>Here’s example WebIDL for a possible extension of this specification
 for proximity <a data-link-type="dfn" href="#concept-sensor" id="ref-for-concept-sensor⑤①">sensors</a>.</p>
@@ -3549,6 +3565,7 @@ <h2 class="no-num no-ref heading settled" id="idl-index"><span class="content">I
     <li><a href="#ref-for-sensor-readings④③">10.2. Naming</a> <a href="#ref-for-sensor-readings④④">(2)</a>
     <li><a href="#ref-for-sensor-readings④⑤">10.3. Unit</a>
     <li><a href="#ref-for-sensor-readings④⑥">10.6. Definition Requirements</a>
+    <li><a href="#ref-for-sensor-readings④⑦">10.7. Extending the Permission API</a> <a href="#ref-for-sensor-readings④⑧">(2)</a>
    </ul>
   </aside>
   <aside class="dfn-panel" data-for="low-level">
@@ -3559,6 +3576,7 @@ <h2 class="no-num no-ref heading settled" id="idl-index"><span class="content">I
     <li><a href="#ref-for-low-level⑧">10. Extensibility</a>
     <li><a href="#ref-for-low-level⑨">10.2. Naming</a>
     <li><a href="#ref-for-low-level①⓪">10.4. Exposing High-Level vs. Low-Level Sensors</a> <a href="#ref-for-low-level①①">(2)</a> <a href="#ref-for-low-level①②">(3)</a>
+    <li><a href="#ref-for-low-level①③">10.7. Extending the Permission API</a> <a href="#ref-for-low-level①④">(2)</a>
    </ul>
   </aside>
   <aside class="dfn-panel" data-for="high-level">
@@ -3576,6 +3594,7 @@ <h2 class="no-num no-ref heading settled" id="idl-index"><span class="content">I
    <ul>
     <li><a href="#ref-for-sensor-fusion">6.1. Sensors</a> <a href="#ref-for-sensor-fusion①">(2)</a>
     <li><a href="#ref-for-sensor-fusion②">6.2. Sensor Types</a> <a href="#ref-for-sensor-fusion③">(2)</a> <a href="#ref-for-sensor-fusion④">(3)</a> <a href="#ref-for-sensor-fusion⑤">(4)</a> <a href="#ref-for-sensor-fusion⑥">(5)</a>
+    <li><a href="#ref-for-sensor-fusion⑦">10.7. Extending the Permission API</a>
    </ul>
   </aside>
   <aside class="dfn-panel" data-for="smart-sensors">
@@ -3625,6 +3644,7 @@ <h2 class="no-num no-ref heading settled" id="idl-index"><span class="content">I
     <li><a href="#ref-for-sampling-frequency②">5.3.3. Limit number of delivered readings</a>
     <li><a href="#ref-for-sampling-frequency③">7.2. Sensor</a> <a href="#ref-for-sampling-frequency④">(2)</a>
     <li><a href="#ref-for-sampling-frequency⑤">8.1.2. Sensor internal slots</a>
+    <li><a href="#ref-for-sampling-frequency⑥">10.7. Extending the Permission API</a>
    </ul>
   </aside>
   <aside class="dfn-panel" data-for="sensor-type">
@@ -3757,6 +3777,7 @@ <h2 class="no-num no-ref heading settled" id="idl-index"><span class="content">I
     <li><a href="#ref-for-sensor②⑤">10.2. Naming</a> <a href="#ref-for-sensor②⑥">(2)</a> <a href="#ref-for-sensor②⑦">(3)</a>
     <li><a href="#ref-for-sensor②⑧">10.5. When is Enabling Multiple Sensors of the Same Type Not the Right Choice?</a>
     <li><a href="#ref-for-sensor②⑨">10.6. Definition Requirements</a>
+    <li><a href="#ref-for-sensor③⓪">10.7. Extending the Permission API</a> <a href="#ref-for-sensor③①">(2)</a>
    </ul>
   </aside>
   <aside class="dfn-panel" data-for="dom-sensor-activated">