WebControls Commands

The REST calls are specified as CommandInfo-nodes. Each command specifies:

• Command id
• Command name
• Address as sub- URL including query information
• List arguments (input, inout and output)
• Properties specifying the REST call
  • Method MUST HTTP Method, like GET, POST, ...
  • ContentType OPT Content type of the request body
  • Accept OPT Accepted content type of the response
  • CustomHeader:<header> OPT App specific headers

Example:

{
  "Id": "56516249-915A-4B3E-9137-FBDF953B4342",
  "Name": "GetAllNodes",
  "Type": "CommandNode",
  "Address": "nodes",
  "Properties": [
    {
      "Name": "Method",
      "Value": "GET"
    },
    {
      "Name": "Accept",
      "Value": "text/xml"
    },
    {
      "Name": "CustomHeader:X-Restd-Session",
      "Value":  "close"
    }
  ],
  "Arguments": [
    {
      "Name": "Content",
      "Type": "Output",
      "DataType": "System.String"
    }
  ]
}

Dynamic querying

If the URL needs specific query parameters, then these parameter values can be passed to the command as arguments.

Use the syntax $(<varname>) to reference an argument of the command.

Example:

The ?id=$(id) is automatically resolved with the argument id which is passed to the command.

{
  "Id": "56516249-915A-4B3E-9137-FBDF953B4342",
  "Name": "GetNode",
  "Type": "CommandNode",
  "Address": "nodes/node?id=$(Id)",
  "Properties": [
    {
      "Name": "Method",
      "Value": "GET"
    },
    {
      "Name": "Accept",
      "Value": "text/xml"
    }
  ],
  "Arguments": [
    {
      "Name": "Id",
      "Type": "Input",
      "DataType": "System.Guid"
    },
    {
      "Name": "Content",
      "Type": "Output",
      "DataType": "System.String"
    }
  ]
}

Composing Request and Parsing Response Body

Some calls require a request body to transfer information from the HumanOS® to the web device. To compose such a body, dynamic C# Scripting is used.

The script files are located in the \$(ConfigPath)\HumanOS.UHAL.WebControl and must be bear the same name as the corresponding command, e.g. GetAllNodes => GetAllNodes.cs. If it is better to change this name, you can create a property named "ScriptFile" and specify the name here.

In following example: NodeHandling => NodeHandling.cs

{
  "Id": "56516249-915A-4B3E-9137-FBDF953B4342",
  "Name": "GetAllNodes",
  "Type": "CommandNode",
  "Address": "nodes/node?id=$(Id)",
  "Properties": [
    {
      "Name": "Method",
      "Value": "GET"
    },
    {
      "Name": "Accept",
      "Value": "text/xml"
    },
    {
      "Name": "ScriptFile",
      "Value": "NodeHandling.cs"
    }
  ],
  "Arguments": []
}

The class must be derived from TAbstractHttpScriptObject and overrides the methods

• composeRequest()
• parseResponse()
• parseError() [optional]

Example:

using System;
using System.Collections;
using System.Collections.Generic;
using HumanOS.Kernel.Communication.Protocols;
using HumanOS.Kernel.UHAL.Script;
using Orion.Base;
// Orion.Base is replaced by CyberTech for version 1.4 or newer

namespace HumanOS.UHAL.WebControl
{
  /// <summary>
  /// Content handler for composing and parsing the calls
  /// </summary>
  public class TContentHandler : TAbstractHttpScriptObject
  {
    ///<see cref="TAbstractHttpScriptObject"/>
    public override string composeRequest(ref string rstrAddress,
                                          Dictionary<string, string> dicProperties,
                                          Dictionary<string, object> dicInputArguments)
    {
      //check for a input value
      if (!dicInputArguments.ContainsKey("MyType"))
      {
        throw new ArgumentException($"Argument ‘MyType’ not found in command Arguments.");
      }

      EMyEnum eMyType = (EMyEnum)Enum.Parse(typeof(EMyEnum), (string)dicInputArguments["MyType"]);

      //add the associated url part
      switch (eMyType)
      {
        case EMyEnum.Test1:
          {
            rstrAddress += "/testprofile";
            break;
          }
        case EMyEnum.Test2:
          {
            rstrAddress += "/test2profile";
            break;
          }

        default:
          {
            throw new ArgumentException($"Profile type {eMyType.ToString()} is unknown or not supported.");
          }
      }

      return "";
    }

    ///<see cref="TAbstractHttpScriptObject"/>
    public override void parseResponse(string strAddress,
                                       Dictionary<string, string> dicProperties,
                                       string strContent,
                                       EContentType eContentType,
                                       Dictionary<string, object> dicInputArguments,
                                       Dictionary<string, object> dicOutputArguments)    
     {
      dicOutputArguments["Content"] = strContent;
      return true;
    }

    ///<see cref="TAbstractHttpScriptObject"/>
    public override TCommandResult parseError(Dictionary<string, string> dicProperties,
                                      Dictionary<string, object> dicInputArguments,
                                      string strMethod,
                                      string strAddress,
                                      string strRequestBody,
                                      THttpResponse Response)
    {
      TCommandResult nRetval;
      try
      {
        nRetval = new TCommandResult(EProcessingState.BadProcessing, Response.Content);
      }
      catch (ThreadAbortException) { throw; }
      catch (ThreadInterruptedException) { throw; }
      catch (Exception)
      {
        nRetval = new TCommandResult(EProcessingState.BadProcessing, Response.ReasonPhrase);
      }
      return nRetval;
    }
  }
}