- IEC 61850 client: added new function ControlObjectClient_getCtlValType to simplify control handling

dotnet/IEC61850forCSharp/Control.cs

@@ -118,6 +118,9 @@ namespace IEC61850
 			[DllImport("iec61850", CallingConvention = CallingConvention.Cdecl)]
 			private static extern int ControlObjectClient_getControlModel(IntPtr self);
 
+			[DllImport("iec61850", CallingConvention = CallingConvention.Cdecl)]
+			private static extern int ControlObjectClient_getCtlValType(IntPtr self);
+
 			[DllImport("iec61850", CallingConvention = CallingConvention.Cdecl)]
             [return: MarshalAs(UnmanagedType.I1)]
 			private static extern bool ControlObjectClient_operate(IntPtr self, IntPtr ctlVal, UInt64 operTime);
@@ -196,6 +199,17 @@ namespace IEC61850
 				return controlModel;
 			}
 
+			/// <summary>
+			/// Get the type of ctlVal.
+			/// </summary>
+			/// <returns>MmsType required for the ctlVal value.</returns>
+			public MmsType GetCtlValType ()
+			{
+				MmsType ctlValType = (MmsType) ControlObjectClient_getCtlValType (controlObject);
+
+				return ctlValType;
+			}
+
             /// <summary>
             /// Sets the origin parameter used by control commands.
             /// </summary>

dotnet/control/ControlExample.cs

@@ -40,6 +40,7 @@ namespace control
 				ControlModel controlModel = control.GetControlModel();
 
 				Console.WriteLine(objectReference + " has control model " + controlModel.ToString());
+				Console.WriteLine("  type of ctlVal: " + control.GetCtlValType().ToString());
 
 
 				switch (controlModel) {

src/iec61850/client/client_control.c

@@ -270,6 +270,15 @@ ControlObjectClient_getControlModel(ControlObjectClient self)
     return self->ctlModel;
 }
 
+MmsType
+ControlObjectClient_getCtlValType(ControlObjectClient self)
+{
+    if (self->analogValue != NULL)
+        return MmsValue_getType(self->analogValue);
+    else
+        return MmsValue_getType(self->ctlVal);
+}
+
 void
 ControlObjectClient_setOrigin(ControlObjectClient self, const char* orIdent, int orCat)
 {

src/iec61850/inc/iec61850_client.h

@@ -1595,6 +1595,19 @@ ControlObjectClient_getObjectReference(ControlObjectClient self);
 ControlModel
 ControlObjectClient_getControlModel(ControlObjectClient self);
 
+/**
+ * \brief Get the type of ctlVal.
+ *
+ * This type is required for the ctlVal parameter of the \ref ControlObjectClient_operate
+ * and \ref  ControlObjectClient_selectWithValue functions.
+ *
+ * \param self the control object instance to use
+ *
+ * \return MmsType required for the ctlVal value.
+ */
+MmsType
+ControlObjectClient_getCtlValType(ControlObjectClient self);
+
 /**
  * \brief Send an operate command to the server
  *
@@ -1607,12 +1620,25 @@ ControlObjectClient_getControlModel(ControlObjectClient self);
 bool
 ControlObjectClient_operate(ControlObjectClient self, MmsValue* ctlVal, uint64_t operTime);
 
+/**
+ * \brief Send a select command to the server
+ *
+ * The select command is only used for the control model "select-before-operate with normal security"
+ * (CONTROL_MODEL_SBO_NORMAL). The select command has to be sent before the operate command can be used.
+ *
+ * \param self the control object instance to use
+ *
+ * \return true if operation has been successful, false otherwise.
+ */
 bool
 ControlObjectClient_select(ControlObjectClient self);
 
 /**
  * \brief Send an select with value command to the server
  *
+ * The select-with-value command is only used for the control model "select-before-operate with enhanced security"
+ * (CONTROL_MODEL_SBO_ENHANCED). The select-with-value command has to be sent before the operate command can be used.
+ *
  * \param self the control object instance to use
  * \param ctlVal the control value (for APC the value may be either AnalogueValue (MMS_STRUCT) or MMS_FLOAT/MMS_INTEGER
  *
@@ -1621,6 +1647,16 @@ ControlObjectClient_select(ControlObjectClient self);
 bool
 ControlObjectClient_selectWithValue(ControlObjectClient self, MmsValue* ctlVal);
 
+/**
+ * \brief Send a cancel command to the server
+ *
+ * The cancel command can be used to stop an ongoing operation (when the server and application
+ * support this) and to cancel a former select command.
+ *
+ * \param self the control object instance to use
+ *
+ * \return true if operation has been successful, false otherwise.
+ */
 bool
 ControlObjectClient_cancel(ControlObjectClient self);
 
@@ -1630,9 +1666,25 @@ ControlObjectClient_setLastApplError(ControlObjectClient self, LastApplError las
 LastApplError
 ControlObjectClient_getLastApplError(ControlObjectClient self);
 
+/**
+ * \brief Send commands in test mode.
+ *
+ * When the server supports test mode the commands that are sent with the test flag set
+ * are not executed (will have no effect on the attached physical process).
+ *
+ * \param self the control object instance to use
+ * \param value value if the test flag (true = test mode).
+ */
 void
 ControlObjectClient_setTestMode(ControlObjectClient self, bool value);
 
+/**
+ * \brief Set the origin parameter for control commands
+ *
+ * The origin parameter is used to identify the client/application that sent a control
+ * command. It is intended for later analysis.
+ *
+ */
 void
 ControlObjectClient_setOrigin(ControlObjectClient self, const char* orIdent, int orCat);
 

src/vs/libiec61850-wo-goose.def

@@ -603,3 +603,4 @@ EXPORTS
     ClientGooseControlBlock_getMinTime
     ClientGooseControlBlock_getMaxTime
     ClientGooseControlBlock_getFixedOffs
+    ControlObjectClient_getCtlValType

src/vs/libiec61850.def

@@ -730,3 +730,5 @@ EXPORTS
     ClientGooseControlBlock_getMinTime
     ClientGooseControlBlock_getMaxTime
     ClientGooseControlBlock_getFixedOffs
+    ControlObjectClient_getCtlValType
+