From 8ab29ca80e824b47f5256e0c43bdb85c4b235f36 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Mon, 26 Aug 2024 16:15:54 +0200 Subject: [PATCH 1/4] refactor: start experimenting with extending invokeAction --- index.html | 70 +++++++++++++++++++++++++++-- typescript/scripting-api/index.d.ts | 12 ++++- 2 files changed, 77 insertions(+), 5 deletions(-) diff --git a/index.html b/index.html index b0b2ee8..01b4c41 100644 --- a/index.html +++ b/index.html @@ -1275,7 +1275,71 @@

The InteractionOutput interface

-

Using {{InteractionInput}} and {{InteractionOutput}}

+ +
+

The ActionInteractionOutput interface

+

+ Belongs to the WoT Consumer conformance class. + An {{ActionInteractionOutput}} object is always created by the implementations + and exposes the data returned from WoT Interactions to application + scripts. +

+

+ This interface exposes an action status object. Its implementation + will allow cancelling asynchronous actions and report the status of a long running action. +

+ 
+      enum ActionStatus {
+        /* "pending", Profile has pending. Not sure what it would mean? */
+        "running",
+        "success", /* Profile uses completed? */
+        "error" /* Profile uses failed? */
+      };
+      
+      [SecureContext, Exposed=(Window,Worker)]
+      interface ActionInteractionOutput : InteractionOutput {
+        readonly attribute object? error;
+        Promise<ActionStatus> status();
+        Promise<undefined> cancel();
+      };
+
+

+ The error property represents a possible error, initially `null`. +

+

+ +

+

+ Should we allow pause/resume also? TD has no notion of it. +

+

The status() function

+ Reports the status of an Action (one of running, success or error) or rejects on error. The method MUST run the following steps: +
    +
  1. + Return a {{Promise}} |promise:Promise| and execute the next steps + [=in parallel=]. +
    2. +
  2. + TODO +
    3. +
+
+

The cancel() function

+ Cancels a running WoT Action or rejects on error. The method MUST run the following steps: +
    +
  1. + Return a {{Promise}} |promise:Promise| and execute the next steps + [=in parallel=]. +
    2. +
  2. + TODO +
    3. +
+
+ +
+ +

Using {{InteractionInput}}, {{InteractionOutput}} and {{ActionInteractionOutput}}

As illustrated in the next pictures, the {{InteractionOutput}} interface is used every time implementations provide data to scripts, while @@ -1323,7 +1387,7 @@

The InteractionOutput interface

When a {{ConsumedThing}} invokes an Action, it provides the parameters as {{InteractionInput}} and receives the output of the - Action as an {{InteractionOutput}} object. + Action as an {{ActionInteractionOutput}} object.

An {{ExposedThing}} @@ -1386,7 +1450,7 @@

The ConsumedThing interface

/*Promise<undefined> writeAllProperties( PropertyWriteMap valueMap, optional InteractionOptions options = {});*/ - Promise<InteractionOutput> invokeAction(DOMString actionName, + Promise<ActionInteractionOutput> invokeAction(DOMString actionName, optional InteractionInput params = {}, optional InteractionOptions options = {}); Promise<Subscription> observeProperty(DOMString name, diff --git a/typescript/scripting-api/index.d.ts b/typescript/scripting-api/index.d.ts index 06a3fad..8d0e9d6 100644 --- a/typescript/scripting-api/index.d.ts +++ b/typescript/scripting-api/index.d.ts @@ -88,6 +88,14 @@ declare namespace WoT { value(): Promise; } + export enum ActionStatus { "running", "success", "error" } + + export interface ActionInteractionOutput extends InteractionOutput { + error?: Error; + status(): Promise + cancel(): Promise + } + export interface Subscription { active:boolean, stop(options?: InteractionOptions):Promise @@ -140,9 +148,9 @@ declare namespace WoT { * Makes a request for invoking an Action and return the result. * Takes as arguments actionName, optionally params and optionally options. * It returns a Promise that resolves with the result of the Action represented - * as an InteractionOutput object, or rejects with an error. + * as an ActionInteractionOutput object, or rejects with an error. */ - invokeAction(actionName: string, params?: InteractionInput, options?: InteractionOptions): Promise; + invokeAction(actionName: string, params?: InteractionInput, options?: InteractionOptions): Promise; /** * Makes a request for Property value change notifications. From b73fdb1b6ad2f994a3eee19a5cd1b3bea0daac78 Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Mon, 26 Aug 2024 16:27:07 +0200 Subject: [PATCH 2/4] refactor: improve initial text --- index.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index 01b4c41..381809d 100644 --- a/index.html +++ b/index.html @@ -1281,8 +1281,8 @@

The ActionInteractionOutput interface

Belongs to the WoT Consumer conformance class. An {{ActionInteractionOutput}} object is always created by the implementations - and exposes the data returned from WoT Interactions to application - scripts. + and exposes functionality to interact with long running (asynchronous) actions.
+ Note: a synchronous action MAY not offer any additional sensible interaction beyond the ones from {{InteractionOutput}}.

This interface exposes an action status object. Its implementation @@ -1332,7 +1332,7 @@

The ActionInteractionOutput interface

[=in parallel=].
  • - TODO + TODO ... applicable when the state is running
    • From bb69456d1a11b2d3b3c26540d75cda9867fca39b Mon Sep 17 00:00:00 2001 From: danielpeintner Date: Mon, 14 Oct 2024 13:45:13 +0200 Subject: [PATCH 3/4] refactor: remove ActionStatus "pending" --- index.html | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index 381809d..0ad4238 100644 --- a/index.html +++ b/index.html @@ -1290,10 +1290,9 @@

    The ActionInteractionOutput interface

           enum ActionStatus {
-        /* "pending", Profile has pending. Not sure what it would mean? */
         "running",
-        "success", /* Profile uses completed? */
-        "error" /* Profile uses failed? */
+        "success",
+        "error"
       };
       
       [SecureContext, Exposed=(Window,Worker)]

From 54a2f5075d83a0860b7314d27fb998a68eff0537 Mon Sep 17 00:00:00 2001
From: danielpeintner 
Date: Tue, 15 Oct 2024 09:52:25 +0200
Subject: [PATCH 4/4] Update index.html

Co-authored-by: Jan Romann 
---
 index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 0ad4238..d8fe179 100644
--- a/index.html
+++ b/index.html
@@ -1280,7 +1280,7 @@ 
    The InteractionOutput interface
    
     
    The ActionInteractionOutput interface
    
     
    
       Belongs to the WoT Consumer conformance class.
-      An {{ActionInteractionOutput}} object is always created by the implementations
+      An {{ActionInteractionOutput}} object is always created by a consumer implementation
       and exposes functionality to interact with long running (asynchronous) actions.
    
       Note: a synchronous action MAY not offer any additional sensible interaction beyond the ones from {{InteractionOutput}}.