v1.3-beta.15

- Module parameters can now hold any kind of object value through the new `SetData` method. Internally, the value of this method is directly bound to the `ModuleParameter.Value` property. `ModuleParameter.Value` will return the string representation of the object stored by the `SetData` method, JSON serializing it when needed (see updated docs).
- Fixed reporting of line numbers of runtime errors for csharp programs
- Program apps can now exchange any data object instance via `ModuleHelper.RaiseEvent` and `Program.ApiCall` methods (see updated docs).

BaseFiles/Common/html/index.html

@@ -97,15 +97,15 @@
     <script src="js/jqm-datebox.lang.utf8.min.js"></script>
 
     <!-- HomeGenie Javascript includes -->
-    <script src="js/homegenie.api.js?version=v1.3-stable.14b"></script>
-    <script src="js/homegenie.webapp.js?version=v1.3-stable.14b"></script>
+    <script src="js/homegenie.api.js?version=v1.3-stable.15"></script>
+    <script src="js/homegenie.webapp.js?version=v1.3-stable.15"></script>
 
     <!-- custom javascript --><!-- TODO: check wheter this can be deprecated/moved -->
-    <script src="js/my.js?version=v1.3-stable.14b"></script>
+    <script src="js/my.js?version=v1.3-stable.15"></script>
 
     <!-- local css definitions and overrides -->
-    <link rel="stylesheet" href="css/my.css?version=v1.3-stable.14b" />
-    <link rel="stylesheet" href="css/fonts/hg-fonts.css?version=v1.3-stable.14b" />
+    <link rel="stylesheet" href="css/my.css?version=v1.3-stable.15" />
+    <link rel="stylesheet" href="css/fonts/hg-fonts.css?version=v1.3-stable.15" />
 
     <script type="text/javascript">
 

HomeGenie/Automation/ProgramDynamicApi.cs

@@ -92,8 +92,17 @@ public static object TryApiCall(MigInterfaceCommand command)
                 if (handler != null)
                 {
                     // other command API handlers
-                    // receives the full request string
-                    response = handler(command.OriginalRequest.Trim('/'));
+                    if (command.Data == null || (command.Data is byte[] && (command.Data as byte[]).Length == 0))
+                    {
+                        // receives the full request as string if there is no `request.Data` payload
+                        handler(command.OriginalRequest.Trim('/'));
+                    }
+                    else
+                    {
+                        // receives the original MigInterfaceCommand if `request.Data` actually holds some data
+                        // TODO: this might be be the only entry point in future releases (line #98 and #87 cases will be deprecated)
+                        handler(command);
+                    }
                 }
             }
             return response;

HomeGenie/Automation/Scripting/EventsHelper.cs

@@ -171,29 +171,68 @@ public EventsHelper ModuleParameterIsChanging(Func<ModuleHelper, ModuleParameter
         }
 
         /// <summary>
-        /// Define a `handler` function to call when a web service call starting with `apiCall` is received.
-        /// This is used to create and handle user-defined web service API methods.
+        /// Define a `handler` function that will be called when a web service call starting with `apiCall` is received.
+        /// Use this to create user-defined web service API methods.
         /// </summary>
         /// <returns>EventsHelper</returns>
         /// <param name="apiCall">API call.</param>
         /// <param name="handler">Handler.</param>
         /// <remarks />
         /// <example>
-        /// Example:
+        /// API methods should respect the following format:
+        /// <code>
+        /// <domain>/<address>/<command>[/<option_0>[/.../<option_n>]]
+        /// </code>
+        /// For instance, a program that control Philips Hue lights will implement API methods like this:
+        /// <code>
+        ///     When.WebServiceCallReceived( "HomeAutomation.PhilipsHue", (args) =>
+        ///     {
+        ///         // handle the received request
+        ///     });
+        /// </code>
+        ///
+        /// So an API call to set a Philips Hue light with address *3* to *50%* can be done via HTTP GET
+        /// <code>
+        /// GET /api/HomeAutomation.PhilipsHue/3/Control.Level/50
+        /// </code>
+        /// or from a csharp program
+        /// <code>
+        /// var responseObject = Program.ApiCall("HomeAutomation.PhilipsHue/3/Control.Level/50");
+        /// </code>
+        /// When this call is received by the handler, the object `args` passed to it must be parsed using `Program.ParseApiCall` method, which will return an object containing the following fields
+        /// <code>
+        /// var request = Program.ParseApiCall(args);
+        /// //  request -> {
+        /// //      Domain,         // (string)
+        /// //      Address,        // (string)
+        /// //      Command,        // (string)
+        /// //      Data,           // (object)
+        /// //      OriginalRequest // (string)
+        /// //  }
+        /// </code>
+        /// This object also provide a method `request.GetOption(<index>)` to get eventual options passed with this call.
+        ///
+        /// **Example**
         /// <code>
-        ///     When.WebServiceCallReceived( "Hello.World", (args) =>
+        ///     When.WebServiceCallReceived( "HomeAutomation.PhilipsHue", (args) =>
         ///     {
-        ///         var returnstring = "";
-        ///         if (args == "Hello.World/Greet")
+        ///         var request = Program.ParseApiCall(args);
+        ///         // request.Domain          -> "HomeAutomtion.PhilipsHue"
+        ///         // request.Address         -> 3
+        ///         // request.Command         -> Control.Level
+        ///         // request.GetOption(0)    -> 50
+        ///         // request.Data            -> null (not used in this case)
+        ///         // request.OriginalRequest -> "HomeAutomation.PhilipsHue/3/Control.Level/50"
+        ///         if (request.Domain == "HomeAutomtion.PhilipsHue" && request.Command == "Control.Level")
         ///         {
-        ///             returnstring = "Hello HomeGenie World!";
+        ///             var deviceAddress = request.Address;
+        ///             var deviceLevel = request.GetOption(0); // the first option has index 0
+        ///             // TODO: set dimming level of light with address 'deviceAddress' to 'dimmerLevel' %
+        ///             return new ResponseText("OK");
         ///         }
-        ///         return returnstring;
+        ///         return new ResponseText("ERROR");
         ///     });
         /// </code>
-        /// In the snippet above, if we wanted to create an "Hello World" program that respond to the custom API call:
-        /// \n
-        /// http://<hg_server_address>/api/Hello.World/Greet
         /// </example>
         public EventsHelper WebServiceCallReceived(string apiCall, Func<object, object> handler)
         {

HomeGenie/Automation/Scripting/ProgramHelperBase.cs

@@ -1,4 +1,5 @@
 using System;
+using System.Globalization;
 using System.Threading;
 using System.IO;
 using System.Net;
@@ -10,6 +11,10 @@
 
 namespace HomeGenie
 {
+    /// <summary>
+    /// Program Helper Base class.\n
+    /// Class instance accessor: **Program**
+    /// </summary>
     public class ProgramHelperBase
     {
         protected HomeGenieService homegenie;
@@ -111,7 +116,11 @@ public MigInterfaceCommand ParseApiCall(string apiCall)
         }
         public MigInterfaceCommand ParseApiCall(object apiCall)
         {
-            return ParseApiCall((string)apiCall);
+            if (apiCall is MigInterfaceCommand)
+            {
+                return (MigInterfaceCommand)apiCall;
+            }
+            return ParseApiCall(apiCall.ToString());
         }
 
         /// <summary>

appveyor.yml

@@ -2,7 +2,7 @@ version: 1.0.{build}
 branches:
   except:
   - gh-pages
-image: Visual Studio 2015
+image: Visual Studio 2017
 configuration: Debug
 before_build:
   - nuget restore .\HomeGenie\packages.config -SolutionDirectory .\HomeGenie_Windows