refactor: update prose and IDL based on discussion

Author: danielpeintner

index.html

@@ -1285,53 +1285,61 @@ <h2>The <dfn>ActionInteractionOutput</dfn> interface</h2>
       Note: The output of a synchronous action MAY be limited to the functionality of a regular {{InteractionOutput}} object, e.g., invoking the `cancel()` method might not have an effect.
     </p>
     <p>
-      This interface exposes an action status object. Its implementation
-      will allow cancelling asynchronous actions and report the status of a long running action.
+      This interface exposes functions which
+      will allow cancelling asynchronous actions and query the status of a long running action.
     </p>
     <pre class="idl">
-      enum ActionStatus {
-        "running",
-        "success",
-        "error"
-      };
-      
       [SecureContext, Exposed=(Window,Worker)]
       interface ActionInteractionOutput : InteractionOutput {
-        readonly attribute object? error;
-        Promise&lt;ActionStatus&gt; status();
-        Promise&lt;undefined&gt; cancel();
+        Promise&lt;InteractionOutput&gt; query(
+          optional InteractionInput params = {},
+          optional InteractionOptions options = {});
+        Promise&lt;undefined&gt; cancel(
+          optional InteractionInput params = {},
+          optional InteractionOptions options = {});
+        // Note: retrieving the result of an action via the implicit InteractionOutput interface
+        // will only work after the action has been completed
       };
     </pre>
-    <p>
-      The <dfn>error</dfn> property represents a possible error, initially `null`.
-    </p>
-    <p class="ednote" title="Should state be a function or an attribute only?">
 
     </p>
-    <p class="ednote" title="Additional action object functions needed?">
-      Should we allow pause/resume also? TD has no notion of it.
-    </p>
-    <section><h3>The <dfn>status()</dfn> function</h3>
-      Reports the status of an <a>Action</a> (one of <code>running</code>, <code>success</code>, or <code>error</code>), or rejects on error. The method MUST run the following steps:
+	
+    <section><h3>The <dfn>query()</dfn> function</h3>
+      Reports the status of an <a>Action</a>, or rejects on error. The method MUST run the following steps:
       <ol>
         <li>
           Return a {{Promise}} |promise:Promise| and execute the next steps
           [=in parallel=].
         </li>
         <li>
-          TODO
+          If invoking this method is not supported (e.g., synchronous action)
+          [=reject=] |promise| with a {{NotSupportedError}} and stop.
+        </li>
+        <li>
+          Let |res| be the result of making a request to the underlying platform (via the <a>Protocol Bindings</a>) to query the <a>Action</a> status given optional |params| and |options|. If quering |res| fails, [=reject=] |promise| with {{OperationError}} and stop.
+        </li>
+        <li>
+          [=Resolve=] |promise| with |res|.
         </li>
       </ol>
     </section>
     <section><h3>The <dfn>cancel()</dfn> function</h3>
-      Cancels a running WoT <a>Action</a> or rejects on error. The method MUST run the following steps:
+      Cancels a running WoT <a>Action</a>, or rejects on error. The method MUST run the following steps:
       <ol>
         <li>
           Return a {{Promise}} |promise:Promise| and execute the next steps
           [=in parallel=].
         </li>
-		<li>
-          TODO ... applicable when the state is running
+        <li>
+          If invoking this method is not supported (e.g., synchronous action)
+          [=reject=] |promise| with a {{NotSupportedError}} and stop.
+        </li>
+        <li>
+          Make a request to the underlying platform (via the <a>Protocol Bindings</a>) to cancel the <a>Action</a> given optional |params| and |options|.
+		  If cancelling fails, [=reject=] |promise| with {{OperationError}} and stop.
+        </li>
+        <li>
+          [=Resolve=] |promise|</a>.
         </li>
       </ol>
     </section>

typescript/scripting-api/index.d.ts

@@ -93,7 +93,7 @@ declare namespace WoT {
         query(params?: InteractionInput, options?: InteractionOptions): Promise<InteractionOutput>
         // cancel a pending/running action
         cancel(params?: InteractionInput, options?: InteractionOptions): Promise<void>
-        // Note: retrieving the result of the action via implicit InteractionOutput interface will only work after the action has been completed
+        // Note: retrieving the result of an action via the implicit InteractionOutput interface will only work after the action has been completed
     }
 
     export interface Subscription {