feat(scripting_api): add Scripting API interfaces

lib/scripting_api.dart

@@ -0,0 +1,23 @@
+// Copyright 2021 The NAMIB Project Developers
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+/// WoT Scripting API Definitions
+///
+///
+export 'src/scripting_api/consumed_thing.dart';
+export 'src/scripting_api/discovery/discovery_method.dart';
+export 'src/scripting_api/discovery/thing_discovery.dart';
+export 'src/scripting_api/discovery/thing_filter.dart';
+export 'src/scripting_api/exposed_thing.dart';
+export 'src/scripting_api/interaction_options.dart';
+export 'src/scripting_api/interaction_output.dart';
+export 'src/scripting_api/subscription.dart';
+export 'src/scripting_api/types.dart';
+export 'src/scripting_api/wot.dart';

lib/src/scripting_api/consumed_thing.dart

@@ -0,0 +1,72 @@
+// Copyright 2021 The NAMIB Project Developers
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+import '../definitions/thing_description.dart';
+import 'interaction_options.dart';
+import 'interaction_output.dart';
+import 'subscription.dart';
+import 'types.dart';
+
+/// User provided callback that is given an argument of type [InteractionOutput]
+/// and is used for observing Property changes and handling Event notifications.
+typedef InteractionListener = void Function(InteractionOutput data);
+
+/// User provided callback that is given an argument of type Error and is used
+/// for conveying critical and non-critical errors from the Protocol Bindings to
+/// applications.
+typedef ErrorListener = void Function(Exception data);
+
+/// Represents a client API to operate a Thing. Belongs to the WoT Consumer
+/// conformance class.
+///
+/// See [WoT Scripting API Specification, Section 8][spec link].
+///
+/// [spec link]: https://w3c.github.io/wot-scripting-api/#the-consumedthing-interface
+abstract class ConsumedThing {
+  /// Returns the [ThingDescription] that represents the consumed Thing.
+  ThingDescription get thingDescription;
+
+  /// Reads a property with the given [propertyName].
+  Future<InteractionOutput> readProperty(String propertyName,
+      [InteractionOptions? options]);
+
+  /// Reads all properties.
+  Future<PropertyReadMap> readAllProperties([InteractionOptions? options]);
+
+  /// Reads a number of properties with the given [propertyNames].
+  Future<PropertyReadMap> readMultipleProperties(List<String> propertyNames,
+      [InteractionOptions? options]);
+
+  /// Writes a [value] to a property with the given [propertyName].
+  Future<void> writeProperty(String propertyName, InteractionInput value,
+      [InteractionOptions? options]);
+
+  /// Writes multiple values to multiple properties, as described in a
+  /// [valueMap].
+  Future<void> writeMultipleProperties(PropertyWriteMap valueMap,
+      [InteractionOptions? options]);
+
+  /// Invokes an action with the given [actionName]. Accepts an optional
+  /// [input].
+  ///
+  /// After (asynchronous )completion, it might return an [InteractionOutput].
+  Future<InteractionOutput> invokeAction(String actionName,
+      [InteractionInput input, InteractionOptions? options]);
+
+  /// Observes a property with the given [propertyName].
+  Future<Subscription> observeProperty(
+      String propertyName, InteractionListener listener,
+      [ErrorListener? onError, InteractionOptions? options]);
+
+  /// Subscribes to an event with the given [eventName].
+  Future<Subscription> subscribeEvent(
+      String eventName, InteractionListener listener,
+      [ErrorListener? onError, InteractionOptions? options]);
+}

lib/src/scripting_api/discovery/discovery_method.dart

@@ -0,0 +1,32 @@
+// Copyright 2021 The NAMIB Project Developers
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+/// Enumeration of possible discovery methods.
+///
+/// See [WoT Scripting API Specification, Section 10.2][spec link].
+///
+/// [spec link]: https://w3c.github.io/wot-scripting-api/#the-discoverymethod-enumeration
+// TODO(JKRhb): `any` and `multicast` have been removed in later versions. We
+//              probably need to ask/discuss with the Scripting API Taskforce
+//              how to deal with CoAP (multicast) discovery from CoRE Resource
+//              Directories.
+enum DiscoveryMethod {
+  /// "Any" discovery (unspecified).
+  any,
+
+  /// Direct fetching of a Thing's Thing Description from the ThingFilter's url.
+  direct,
+
+  /// Discovery from a Directory specified by the ThingFilter's url.
+  directory,
+
+  /// Multicast discovery (unspecified).
+  multicast,
+}

lib/src/scripting_api/discovery/thing_discovery.dart

@@ -0,0 +1,36 @@
+// Copyright 2021 The NAMIB Project Developers
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+import '../../definitions/thing_description.dart';
+import 'thing_filter.dart';
+
+/// Interface
+abstract class ThingDiscovery {
+  /// The [thingFilter] that is applied during the discovery process.
+  ThingFilter? get thingFilter;
+
+  /// Indicates if this [ThingDiscovery] object is active.
+  bool get active;
+
+  /// Indicates if this [ThingDiscovery] object is done.
+  bool get done;
+
+  /// The [Exception] that is thrown when an error occurs.
+  Exception? get error;
+
+  /// Starts the discovery process.
+  void start();
+
+  /// Stops the discovery process.
+  void stop();
+
+  /// Returns the next discovered [ThingDescription].
+  Future<ThingDescription> next();
+}

lib/src/scripting_api/discovery/thing_filter.dart

@@ -0,0 +1,33 @@
+// Copyright 2021 The NAMIB Project Developers
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+import 'discovery_method.dart';
+
+/// Contains the constraints for discovering Things as key-value pairs.
+///
+/// See [WoT Scripting API Specification, Section 10.3][spec link].
+///
+/// [spec link]: https://w3c.github.io/wot-scripting-api/#the-thingfilter-dictionary
+// TODO(JKRhb): This part of the specification has to be improved IMHO.
+abstract class ThingFilter {
+  /// Represents the discovery type that should be used in the discovery process
+  DiscoveryMethod method = DiscoveryMethod.directory;
+
+  /// Represents the URL of the target entity serving the discovery request.
+  ///
+  /// This is, for instance the URL of a Thing Directory (if method is
+  /// "directory"), or the URL of a directly targeted Thing (if method is
+  /// "direct").
+  String? url;
+
+  /// Represents a template object used for matching property by property
+  /// against discovered Things.
+  Map<String, dynamic>? fragment;
+}

lib/src/scripting_api/exposed_thing.dart

@@ -0,0 +1,113 @@
+// Copyright 2021 The NAMIB Project Developers
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+import '../definitions/thing_description.dart';
+import 'interaction_options.dart';
+import 'interaction_output.dart';
+import 'types.dart';
+
+/// A function that is called when an external request for reading a Property is
+/// received and defines what to do with such requests.
+typedef PropertyReadHandler = Future<InteractionInput> Function(
+    InteractionOptions? options);
+
+/// A function that is called when an external request for writing a Property is
+///  received and defines what to do with such requests.
+typedef PropertyWriteHandler = Future<void> Function(
+    InteractionOutput value, InteractionOptions? options);
+
+/// A function that is called when an external request for invoking an Action
+/// is received and defines what to do with such requests.
+typedef ActionHandler = Future<void> Function(
+    InteractionOutput params, InteractionOptions? options);
+
+/// A function that is called when an external request for subscribing to an
+/// Event is received and defines what to do with such requests.
+typedef EventSubscriptionHandler = Future<void> Function(
+    InteractionOptions? options);
+
+/// A function that is called when an associated Event is triggered and provides
+/// the data to be sent with the Event to subscribers.
+typedef EventListenerHandler = Future<InteractionInput> Function();
+
+/// The ExposedThing interface is the server API to operate the Thing that
+/// allows defining request handlers, Property, Action, and Event interactions.
+///
+/// See [WoT Scripting API Specification, Section 9][spec link].
+///
+/// [spec link]: https://w3c.github.io/wot-scripting-api/#the-exposedthing-interface
+abstract class ExposedThing {
+  /// The [ThingDescription] that represents this [ExposedThing].
+  ThingDescription get thingDescription;
+
+  /// Starts exposing the Thing.
+  Future<void> expose();
+
+  /// Destroys the [ExposedThing].
+  Future<void> destroy();
+
+  /// Assigns a [handler] function to a property with a given [name].
+  ///
+  /// If the property is being read, the [handler] function will be called to
+  /// handle the interaction.
+  void setPropertyReadHandler(String name, PropertyReadHandler handler);
+
+  /// Assigns a [handler] function to a property with a given [name].
+  ///
+  /// If the property is being written to, the [handler] function will be called
+  /// to handle the interaction.
+  void setPropertyWriteHandler(String name, PropertyWriteHandler handler);
+
+  /// Assigns a [handler] function to a property with a given [name].
+  ///
+  /// If the property is being observed, the [handler] function will be called
+  /// to handle the interaction.
+  void setPropertyObserveHandler(String name, PropertyReadHandler handler);
+
+  /// Assigns a [handler] function to a property with a given [name].
+  ///
+  /// If the observation of a property is cancelled, the [handler] function will
+  ///  be called to handle the interaction.
+  void setPropertyUnobserveHandler(String name, PropertyReadHandler handler);
+
+  /// Informs all subscribers about the change of the property with the given
+  /// [name].
+  Future<void> emitPropertyChange(String name);
+
+  /// Assigns a [handler] function to an action with a given [name].
+  ///
+  /// If the action is invoked, the [handler] function will be called to handle
+  /// the interaction.
+  void setActionHandler(String name, ActionHandler handler);
+
+  /// Assigns a [handler] function to an event with a given [name].
+  ///
+  /// If the event is subscribed to, the [handler] function will be called
+  /// to handle the interaction.
+  void setEventSubscribeHandler(String name, EventSubscriptionHandler handler);
+
+  /// Assigns a [handler] function to an event with a given [name].
+  ///
+  /// If the event is ubsubscribed, the [handler] function will be called
+  /// to handle the interaction.
+  void setEventUnsubscribeHandler(
+      String name, EventSubscriptionHandler handler);
+
+  /// Assigns a [handler] function to an event with a given [name].
+  ///
+  /// If the event is emitted, the [handler] function will be called.
+  void setEventHandler(String name, EventListenerHandler handler);
+
+  /// Informs all subscribers of an Event with the given [name] that it has
+  /// occured.
+  ///
+  /// You can provide (optional) input [data] that is emitted with the event.
+  Future<void> emitEvent(String name, InteractionInput data);
+}

lib/src/scripting_api/interaction_options.dart

@@ -0,0 +1,28 @@
+// Copyright 2021 The NAMIB Project Developers
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+/// Holds the interaction options that need to be exposed for application
+/// scripts according to the Thing Description.
+///
+/// See [WoT Scripting API Specification, Section 8.12][spec link].
+///
+/// [spec link]: https://w3c.github.io/wot-scripting-api/#the-interactionoptions-dictionary
+class InteractionOptions {
+  /// Represents an application hint for which Form definition should be used
+  /// for the given interaction.
+  int? formIndex;
+
+  /// Represents the URI template variables to be used with the interaction.
+  Object? uriVariables;
+
+  /// Represents additional opaque data that needs to be passed to the
+  /// interaction.
+  Object? data;
+}

lib/src/scripting_api/interaction_output.dart

@@ -0,0 +1,43 @@
+// Copyright 2021 The NAMIB Project Developers
+//
+// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
+// https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
+// <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your
+// option. This file may not be copied, modified, or distributed
+// except according to those terms.
+//
+// SPDX-License-Identifier: MIT OR Apache-2.0
+
+import 'dart:typed_data';
+
+import '../definitions/data_schema.dart';
+import '../definitions/form.dart';
+
+/// Exposes the data obtained by Thing interactions.
+///
+/// See [WoT Scripting API Specification, Section 7.2][spec link].
+///
+/// [spec link]: https://w3c.github.io/wot-scripting-api/#the-interactionoutput-interface
+abstract class InteractionOutput {
+  /// The raw payload of the [InteractionOutput] as a Byte [Stream].
+  Stream<List<int>>? get data;
+
+  /// Indicates if the [data] has already been retrieved from this
+  /// [InteractionOutput].
+  bool get dataUsed;
+
+  /// The [Form] corresponding to this [InteractionOutput].
+  Form? get form;
+
+  /// An optional [DataSchema] which can be used for validating the
+  /// [InteractionOutput].
+  DataSchema? get schema;
+
+  /// Asyncronously creates a [ByteBuffer] representation of the value of
+  /// of the [InteractionOutput].
+  Future<ByteBuffer> arrayBuffer();
+
+  // TODO(JKRhb): Replace with some kind of DataSchemaValue
+  /// The parsed value of the [InteractionOutput].
+  Future<Object?> value();
+}