From c8e100bc73e031bd829c4bc9a805d3b53d36c3ee Mon Sep 17 00:00:00 2001 From: Fady Salama Date: Wed, 7 Feb 2024 21:44:19 +0100 Subject: [PATCH] add documentation --- WoT/SimpleHTTPConsumer.cs | 18 +++++- WoT/WoT-Definitions.cs | 2 +- WoT/WoT.cs | 122 +++++++++++++++++++++++++++++++++++++- 3 files changed, 137 insertions(+), 5 deletions(-) diff --git a/WoT/SimpleHTTPConsumer.cs b/WoT/SimpleHTTPConsumer.cs index 0879656..8dfa7ed 100644 --- a/WoT/SimpleHTTPConsumer.cs +++ b/WoT/SimpleHTTPConsumer.cs @@ -14,7 +14,7 @@ namespace WoT.Implementation { - public class SimpleHTTPConsumer : IConsumer + public class SimpleHTTPConsumer : IConsumer, IDiscovery { private readonly JsonSerializer _serializer; public readonly HttpClient httpClient; @@ -50,6 +50,22 @@ public async Task RequestThingDescription(string url) Console.WriteLine($"Info: Parsed TD successfully"); return td; } + + public async Task RequestThingDescription(Uri tdUrl) + { + if (tdUrl.Scheme != "http") throw new Exception($"The protocol for accessing the TD url {tdUrl.OriginalString} is not HTTP"); + Console.WriteLine($"Info: Fetching TD from {tdUrl.OriginalString}"); + HttpResponseMessage tdResponse = await httpClient.GetAsync(tdUrl); + tdResponse.EnsureSuccessStatusCode(); + Console.WriteLine($"Info: Fetched TD from {tdUrl.OriginalString} successfully"); + Console.WriteLine($"Info: Parsing TD"); + HttpContent body = tdResponse.Content; + string tdData = await body.ReadAsStringAsync(); + TextReader reader = new StringReader(tdData); + ThingDescription td = _serializer.Deserialize(reader, typeof(ThingDescription)) as ThingDescription; + Console.WriteLine($"Info: Parsed TD successfully"); + return td; + } } public class SimpleConsumedThing : IConsumedThing diff --git a/WoT/WoT-Definitions.cs b/WoT/WoT-Definitions.cs index 706715d..55e6966 100644 --- a/WoT/WoT-Definitions.cs +++ b/WoT/WoT-Definitions.cs @@ -1253,7 +1253,7 @@ public BasicSecurityScheme() { } /// "query" /// "body" /// "cookie" - /// "cookie" + /// "auto" /// /// /// diff --git a/WoT/WoT.cs b/WoT/WoT.cs index 5f81493..afe14d1 100644 --- a/WoT/WoT.cs +++ b/WoT/WoT.cs @@ -6,27 +6,70 @@ namespace WoT { + /// + /// An interface describing the capabilities of a WoT Consumer + /// public interface IConsumer { + /// + /// Expects an td argument and returns a that resolves with an object implementing interface that represents a client interface to operate with the Thing. + /// + /// TD of the client Thing + /// Task that resolves with an object implementing interface + /// WoT Scripting API Task Consume(ThingDescription td); - Task RequestThingDescription(string url); } + /// + /// An interface describing the capabilities of WoT Producer + /// public interface IProducer { Task Produce(ThingDescription td); } - public interface IServient: IConsumer, IProducer + /// + /// An interface describing the capabilities of requesting a TD, part of WoT Discovery interface + /// + public interface IRequester + { + /// + /// Requests a Thing Description from the given URL. + /// + /// URL as a string + /// Deserialized TD + Task RequestThingDescription(string url); + + /// + /// Requests a Thing Description from the given URL. + /// + /// URL as a URI object + /// Deserialized TD + Task RequestThingDescription(Uri url); + } + + /// + /// An interface describing the capabilities of WoT Discovery + /// + public interface IDiscovery: IRequester + { + + } + + /// + /// An interface describing the capabilities of Servient implementing all other conformance interfaces , , + /// + public interface IServient: IConsumer, IProducer, IDiscovery { } /// - /// An Interface for InteractionOutputs with no output data + /// An interface for InteractionOutputs with no output data /// public interface IInteractionOutput { + Stream Data { get; } bool DataUsed { get; } Form Form { get; } @@ -34,8 +77,16 @@ public interface IInteractionOutput Task ArrayBuffer(); Task Value(); } + + /// + /// An interface for InteractionOutputs with output data + /// + /// output data type public interface IInteractionOutput { + /// + /// + /// Stream Data { get; } bool DataUsed { get; } Form Form { get; } @@ -45,19 +96,84 @@ public interface IInteractionOutput } + /// + /// Represents a subscription to Property change and Event interactions. + /// + /// + /// The boolean property denotes if the subscription is active, i.e. it is not stopped because of an error or because of invocation of the method. + /// public interface ISubscription { bool Active { get; } + + /// + /// Stops delivering notifications for the subscription. It takes an optional parameter options and returns a . + /// + /// options passed for interaction + /// that resolves when the stopping process finishes Task Stop(InteractionOptions? options = null); } + /// + /// Represents a client API to operate a Thing. Belongs to the WoT Consumer conformance class. + /// public interface IConsumedThing { + /// + /// Reads a Property value. + /// + /// type of Property value + /// name of Property that should be read + /// additional options for performing the interaction + /// that resolves with that represents Property value Task> ReadProperty(string propertyName, InteractionOptions? options = null); + + /// + /// Writes a single Property. + /// + /// type of Property value + /// name of Property that should be written to + /// value that should be written + /// additional options for performing the interaction + /// that finishes when interaction is performed and a response is received Task WriteProperty(string propertyName, T value, InteractionOptions? options = null); + + /// + /// Makes a request for invoking an Action. Does not send or receive a payload. + /// + /// name of Action to be invoked + /// additional options for performing the interaction + /// that finishes when interaction is performed and a response is received Task InvokeAction(string actionName, InteractionOptions? options = null); + + /// + /// Makes a request for invoking an Action. Sends a payload. Does not receive a payload. + /// + /// type of payload parameters + /// name of Action to be invoked + /// paramters send in the payload + /// additional options for performing the interaction + /// that finishes when interaction is performed and a response is received Task InvokeAction(string actionName, U parameters, InteractionOptions? options = null); + + /// + /// Makes a request for invoking an Action. Does not send a payload. Receives a payload. + /// + /// type of response payload value + /// name of Action to be invoked + /// additional options for performing the interaction + /// that resolves with representing value of response payload Task> InvokeAction(string actionName, InteractionOptions? options = null); + + /// + /// Makes a request for invoking an Action. Sends and receives payload. + /// + /// type of response payload value + /// type of payload parameters + /// name of Action to be invoked + /// paramters send in the payload + /// additional options for performing the interaction + /// that resolves with representing value of response payload Task> InvokeAction(string actionName, U parameters, InteractionOptions? options = null); Task ObserveProperty(string propertyName, Action> listener, InteractionOptions? options = null); Task ObserveProperty(string propertyName, Action> listener, Action onerror, InteractionOptions? options = null);