v1.47.0 - Updates for Touch Portal API versions 7-10.

Author: mpaperno

README.md

@@ -53,6 +53,16 @@ Since `oddbear's` TouchPortalSDK v 0.30.0 release version, the paths have diverg
 
 ### New Features & Change Log
 
+#### v 1.47.0
+Updates for Touch Portal API versions 7-10.
+* Added `TriggerEvent(string eventId, Dictionary<string, object> states)` method & `TriggerEventCommand` type.
+* Added `StateListUpdate(string stateId, string[] values)` method & `StateListUpdateCommand` type.
+* Added `forceUpdate` option to `CreateState()` method and `CreateStateCommand.ForceUpdate` member.
+* Added `ListChangeEvent.Values` property for `listChangeEvent` incoming message. This is a `Dictionary<string, string>` type.
+* Added `InfoEvent.CurrentPagePathMainDevice` and `InfoIevent.CurrentPagePathSecondaryDevices` properties for `info` incoming message type.
+* Added `PreviousPageName`, `DeviceIP`, `DeviceName`, and `DeviceID` to `BroadcastEvent` incoming message type.
+* Added & improved some documentation comments.
+
 #### v 1.46.1
 * Updated for .NET8 and dropped .NET5 support.
 * Updated dependencies to 8.x versions (also fixes a security issue in the `System.Text.Json` library).

TouchPortalSDK/Clients/TouchPortalClient.cs

@@ -1,4 +1,4 @@
-using System;
+using System;
 using System.Collections.Concurrent;
 using System.Runtime.CompilerServices;
 using System.Text.Json;
@@ -144,10 +144,10 @@ bool ICommandHandler.SettingUpdate(string name, string value)
         }
 
         /// <inheritdoc cref="ICommandHandler" />
-        bool ICommandHandler.CreateState(string stateId, string desc, string defaultValue, string parentGroup)
+        bool ICommandHandler.CreateState(string stateId, string desc, string defaultValue, string parentGroup, bool forceUpdate)
         {
             try {
-                return SendCommand(new CreateStateCommand(stateId, desc, defaultValue, parentGroup));
+                return SendCommand(new CreateStateCommand(stateId, desc, defaultValue, parentGroup, forceUpdate));
             }
             catch (ArgumentException e) {
                 _logger?.LogWarning(e, "CreateStateCommand() validation failed.");
@@ -239,6 +239,37 @@ bool ICommandHandler.ConnectorUpdateShort(string shortId, int value)
             }
         }
 
+        /// <inheritdoc cref="ICommandHandler" />
+        bool ICommandHandler.TriggerEvent(string eventId, TriggerEventStates states)
+        {
+            try {
+                return SendCommand(new TriggerEventCommand(eventId, states));
+            }
+            catch (ArgumentException e) {
+                _logger?.LogWarning(e, "TriggerEvent() validation failed.");
+                return false;
+            }
+        }
+
+        /// <inheritdoc cref="ICommandHandler" />
+        bool ICommandHandler.StateListUpdate(string stateId, string[] values)
+        {
+            try {
+                return SendCommand(new StateListUpdateCommand(stateId, values));
+            }
+            catch (ArgumentException e) {
+                _logger?.LogWarning(e, "StateListUpdate() validation failed.");
+                return false;
+            }
+
+        }
+
+        /// <summary>
+        /// Send a Command directly to Touch Portal. All the other command sending methods are conveniences for this one.
+        /// </summary>
+        /// <typeparam name="TCommand">A type implementing from `ITouchPortalMessage`</typeparam>
+        /// <param name="command">One of `TouchPortalSDK.Messages.Commands` types.</param>
+        /// <returns></returns>
         public bool SendCommand<TCommand>(TCommand command, [CallerMemberName]string callerMemberName = "")
             where TCommand : ITouchPortalMessage
         {

TouchPortalSDK/Configuration/MessageResolver.cs

@@ -1,4 +1,4 @@
-using System.Collections.Generic;
+using System.Collections.Generic;
 using System.Collections.ObjectModel;
 using System.Text.Json;
 using TouchPortalSDK.Interfaces;
@@ -31,10 +31,12 @@ internal enum TpEventName : byte
             // RemoveState,
             // StateUpdate,
             // UpdateActionData,
-            // SettingsUpdate
+            // SettingsUpdate,
+            // TriggerEventCommand,
+            // StateListUpdate
         }
 
-        // Map the event name enums to the corresponding types.  (Benchamrked against using an Attribute on the enums and a dict lookup is several magnitudes faster.)
+        // Map the event name enums to the corresponding types.  (Benchmarked against using an Attribute on the enums and a dict lookup is several magnitudes faster.)
         private static readonly ReadOnlyDictionary<TpEventName, System.Type> eventTypeMap = new ReadOnlyDictionary<TpEventName, System.Type>(
             new Dictionary<TpEventName, System.Type>() {
                 { TpEventName.Action,                       typeof(ActionEvent) },
@@ -58,7 +60,7 @@ private class TouchPortalMessageType
         /// <summary>
         /// Resolves and parses a JSON string from byte array into a <see cref="ITouchPortalMessage"/> event Type.
         /// </summary>
-        /// <param name="message">byte array of UTF8-encdoed chars.</param>
+        /// <param name="message">byte array of UTF8-encoded chars.</param>
         /// <returns>A resolved <see cref="ITouchPortalMessage"/> type or <c>null</c> if the event type is unknown.</returns>
         /// <exception cref="JsonException">In case of any JSON string parsing errors.</exception>
         internal static ITouchPortalMessage ResolveMessage(System.ReadOnlySpan<byte> message)

TouchPortalSDK/Interfaces/ICommandHandler.cs

@@ -1,54 +1,59 @@
-using TouchPortalSDK.Messages.Models;
+using TouchPortalSDK.Messages.Models;
 using TouchPortalSDK.Messages.Models.Enums;
 
 namespace TouchPortalSDK.Interfaces
 {
     public interface ICommandHandler
     {
         /// <summary>
-        /// Send a custom command. There is no state tracking for this.
+        /// Send a custom command to Touch Portal. The message must be properly encoded JSON format.
         /// </summary>
-        /// <param name="message"></param>
-        /// <returns></returns>
+        /// <param name="message">A JSON message to send. A terminating newline will be added automatically when the message is sent.</param>
+        /// <returns>true on successful sending of the message, false otherwise.</returns>
         bool SendMessage(string message);
 
         /// <summary>
         /// Creates a dynamic state in Touch Portal Memory.
         /// This state will disappear when restarting Touch Portal.
         /// You will need to persist them yourself and reload them on plugin load.
         /// </summary>
-        /// <param name="stateId"></param>
+        /// <param name="stateId">A unique ID for the new state.</param>
         /// <param name="desc">Description of the created state (name in menus).</param>
         /// <param name="defaultValue">Default value of this state, default is empty string.</param>
         /// <param name="parentGroup">Parent group of this state (TP API v6). Default is an empty string.</param>
-        /// <returns></returns>
-        bool CreateState(string stateId, string desc, string defaultValue = "", string parentGroup = "");
+        /// <param name="forceUpate">
+        ///   This will force the update of the state if it is already created or existing and will trigger the state
+        ///   changed event even if the value is the same as the already existing one.
+        ///   Since TP API v7.
+        /// </param>
+        /// <returns>true on successful sending of the message, false otherwise.</returns>
+        bool CreateState(string stateId, string desc, string defaultValue = "", string parentGroup = "", bool forceUpate = false);
 
         /// <summary>
         /// Updates a setting in Touch Portal.
         /// </summary>
-        /// <param name="name"></param>
-        /// <param name="value"></param>
-        /// <returns></returns>
+        /// <param name="name">Setting name</param>
+        /// <param name="value">New value for the setting</param>
+        /// <returns>true on successful sending of the message, false otherwise.</returns>
         bool SettingUpdate(string name, string value = "");
 
         /// <summary>
         /// Removes the dynamic state from Touch Portal.
         /// </summary>
-        /// <param name="stateId"></param>
-        /// <returns></returns>
+        /// <param name="stateId">ID of the state to remove.</param>
+        /// <returns>true on successful sending of the message, false otherwise.</returns>
         bool RemoveState(string stateId);
 
         /// <summary>
         /// Value that can be displayed, or an event can trigger on.
-        /// Values are not persisted, and will fallback to default value on restart.
+        /// Values are not persisted, and will fall back to default value on restart.
         /// - Plugin: Defined in the Entry.tp
         /// - Dynamic: Created or removed at runtime. (in memory only)
         /// - Global: Defined in the Touch Portal UI. (state definition persisted in %AppData%\TouchPortal\states.tp)
         /// </summary>
-        /// <param name="stateId"></param>
-        /// <param name="value"></param>
-        /// <returns></returns>
+        /// <param name="stateId">ID of the state to update.</param>
+        /// <param name="value">The new value to set for the state. Must be a string.</param>
+        /// <returns>true on successful sending of the message, false otherwise.</returns>
         bool StateUpdate(string stateId, string value = "");
 
         /// <summary>
@@ -58,7 +63,7 @@ public interface ICommandHandler
         /// <param name="choiceId">Id of UI dropdown.</param>
         /// <param name="values">Values as string array that you can choose from.</param>
         /// <param name="instanceId">if set (fetched from listChange event), this will only update this particular list.</param>
-        /// <returns></returns>
+        /// <returns>true on successful sending of the message, false otherwise.</returns>
         bool ChoiceUpdate(string choiceId, string[] values, string instanceId = default);
 
         /// <summary>
@@ -69,7 +74,7 @@ public interface ICommandHandler
         /// <param name="maxValue">Max value the field can be.</param>
         /// <param name="dataType">Type of the data field.</param>
         /// <param name="instanceId">if set (fetched from listChange event), this will only update this particular list.</param>
-        /// <returns></returns>
+        /// <returns>true on successful sending of the message, false otherwise.</returns>
         bool UpdateActionData(string dataId, double minValue, double maxValue, ActionDataType dataType, string instanceId = default);
 
         /// <summary>
@@ -78,7 +83,7 @@ public interface ICommandHandler
         /// <param name="notificationId">If of the notification.</param>
         /// <param name="title">Title on the notification shown to the user.</param>
         /// <param name="message">Text / description of the notification shown to the user.</param>
-        /// <returns></returns>
+        /// <returns>true on successful sending of the message, false otherwise.</returns>
         bool ShowNotification(string notificationId, string title, string message, NotificationOptions[] notificationOptions);
 
         /// <summary>
@@ -87,15 +92,34 @@ public interface ICommandHandler
         /// <param name="connectorId">The long ID of the connector to update. The string "pc_{pluginId}_" is automatically prepended
         /// before sending to TP. The total length must not exceed 200 chars.</param>
         /// <param name="value">The value to send, must be between 0 and 100, inclusive.</param>
-        /// <returns>true on success, false otherwise.</returns>
+        /// <returns>true on successful sending of the message, false otherwise.</returns>
         bool ConnectorUpdate(string connectorId, int value);
 
         /// <summary>
         /// Sends a connector value update to Touch Portal using the short form of the connector ID.
         /// </summary>
         /// <param name="shortId">The short ID of the connector to update. This is obtained from a <see cref="ShortConnectorIdNotification"/> event.</param>
         /// <param name="value">The value to send, must be between 0 and 100, inclusive.</param>
-        /// <returns>true on success, false otherwise.</returns>
+        /// <returns>true on successful sending of the message, false otherwise.</returns>
         bool ConnectorUpdateShort(string shortId, int value);
+
+        /// <summary>
+        /// Trigger predefined Events by sending a message to Touch Portal with the given eventId and additional data.
+        /// Since TP API v7.
+        /// </summary>
+        /// <param name="eventId">The event id to trigger. This event must be defined in the plugin's entry.tp declaration.</param>
+        /// <param name="states">This gets serialized to a JSON Object that holds key value pairs of data that are used within Touch Portal as Local States.</param>
+        /// <returns>true on successful sending of the message, false otherwise.</returns>
+        bool TriggerEvent(string eventId, Messages.Commands.TriggerEventStates states = null);
+
+        /// <summary>
+        /// You can also update state lists in Touch Portal. These state lists needs to be defined in the entry file.
+        /// Since TP API v7.
+        /// </summary>
+        /// <param name="stateId">The state id to set/update.</param>
+        /// <param name="values">The collection of texts that should be the new list to display for this given choice list id. </param>
+        /// <returns>true on successful sending of the message, false otherwise.</returns>
+        bool StateListUpdate(string stateId, string[] values);
+
     }
 }

TouchPortalSDK/Messages/Commands/CreateStateCommand.cs

@@ -1,23 +1,48 @@
-using System;
+using System;
 using TouchPortalSDK.Interfaces;
 using TouchPortalSDK.Messages.Models;
 
 namespace TouchPortalSDK.Messages.Commands
 {
+    /// <summary>
+    /// States can be created on runtime using by sending a "createState" message to Touch Portal with the given information.
+    /// </summary>
     public class CreateStateCommand : ITouchPortalMessage
     {
         public string Type => "createState";
 
+        /// <summary>
+        /// The id of the newly created plug-in state. Please ensure unique names, otherwise you may corrupt other plug-ins.
+        /// </summary>
         public string Id { get; set; }
 
+        /// <summary> The displayed name within Touch Portal which represents the state. </summary>
         public string Desc { get; set; }
 
+        /// <summary> The default value the state will have on creation. </summary>
         public string DefaultValue { get; set; }
 
+        /// <summary>
+        /// The name of the parent group of this state. The parent group of this state will be used to group the state in
+        /// the menus used throughout Touch Portal. Every state belonging to the same parent group name will be in the same selection menu.
+        /// Since TP API v6.
+        /// </summary>
         public string ParentGroup { get; set; }
 
-        public CreateStateCommand(string stateId, string desc, string defaultValue = "", string parentGroup = "")
-        {
+        /// <summary>
+        /// This will force the update of the state if it is already created or existing and will trigger the state
+        /// changed event even if the value is the same as the already existing one.
+        /// Since TP API v7.
+        /// </summary>
+        public bool ForceUpdate { get; set; } = false;
+
+        public CreateStateCommand(
+          string stateId,
+          string desc,
+          string defaultValue = "",
+          string parentGroup = "",
+          bool forceUpdate = false
+        ) {
             if (TouchPortalOptions.ValidateCommandParameters) {
                 if (string.IsNullOrWhiteSpace(stateId))
                     throw new ArgumentNullException(nameof(stateId));
@@ -29,6 +54,7 @@ public CreateStateCommand(string stateId, string desc, string defaultValue = "",
             Desc = desc;
             DefaultValue = defaultValue ?? string.Empty;
             ParentGroup = parentGroup ?? string.Empty;
+            ForceUpdate = forceUpdate;
         }
 
         /// <inheritdoc cref="ITouchPortalMessage" />

TouchPortalSDK/Messages/Commands/StateListUpdateCommand.cs

@@ -0,0 +1,36 @@
+using System;
+using TouchPortalSDK.Interfaces;
+using TouchPortalSDK.Messages.Models;
+
+namespace TouchPortalSDK.Messages.Commands
+{
+    /// <summary>
+    /// You can also update state lists in Touch Portal. These state lists needs to be defined in the entry file.
+    /// Since TP API v7.
+    /// </summary>
+    public class StateListUpdateCommand : ITouchPortalMessage
+    {
+
+        /// <inheritdoc cref="ITouchPortalMessage" />
+        public string Type => "stateListUpdate";
+
+        /// <summary> The state id to set/update. </summary>
+        public string Id { get; set; }
+
+        /// <summary>The collection of texts that should be the new list to display for this given choice list id. </summary>
+        public string[] Value { get; set; }
+
+        public StateListUpdateCommand(string stateId, string[] value)
+        {
+            if (TouchPortalOptions.ValidateCommandParameters && string.IsNullOrWhiteSpace(stateId))
+                throw new ArgumentNullException(nameof(stateId));
+
+            Id = stateId;
+            Value = value ?? Array.Empty<string>();
+        }
+
+        /// <inheritdoc cref="ITouchPortalMessage" />
+        public Identifier GetIdentifier()
+            => new Identifier(Type, Id, default);
+    }
+}

TouchPortalSDK/Messages/Commands/TriggerEventCommand.cs

@@ -0,0 +1,44 @@
+using System;
+using System.Collections.Generic;
+using TouchPortalSDK.Interfaces;
+using TouchPortalSDK.Messages.Models;
+using TouchPortalSDK.Messages.Models.Enums;
+
+namespace TouchPortalSDK.Messages.Commands
+{
+  /// <summary>
+  /// You can trigger predefined Events by sending a message to Touch Portal with the given eventId and additional data.
+  /// Since: TP API v7
+  /// </summary>
+  public class TriggerEventCommand : ITouchPortalMessage
+  {
+    /// <inheritdoc cref="ITouchPortalMessage.Type" />
+    public string Type => "triggerEvent";
+
+    /// <summary> The event id to trigger. This event must be defined in the plugin's entry.tp declaration.</summary>
+    public string EventId;
+    /// <summary> This gets serialized to a JSON Object that holds key value pairs of data that are used within Touch Portal as Local States. </summary>
+    public TriggerEventStates States = null;
+
+    public TriggerEventCommand(string eventId, TriggerEventStates states = null)
+    {
+      if (TouchPortalOptions.ValidateCommandParameters && string.IsNullOrWhiteSpace(eventId))
+        throw new ArgumentNullException(nameof(eventId));
+
+      EventId = eventId;
+      States = states;
+    }
+
+    /// <inheritdoc cref="ITouchPortalMessage.GetIdentifier" />
+    public Identifier GetIdentifier()
+        => new Identifier(Type, EventId, default);
+  }
+
+
+  /// <summary>
+  /// This is a `Dictionary&lt;string, object&gt;` typedef for usage in TriggerEventCommand.States message value.
+  /// </summary>
+  public sealed class TriggerEventStates : System.Collections.Generic.Dictionary<string, object>
+  { }
+
+}