Methods - Stateless and Stateful Interface
Below are listed the SCI methods available in the API using the stateless interface, including the parameters and example code for each method.
CheckCredentials
Checks if security credentials are valid. Returns true if access to root ("/") object is granted for the given security credentials.
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
Example Code:
//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
//the following call return true if:
//profile exists and password is correct and profile has LIST access granted for root ("/") object
bool result = sli.CheckCredentials(new SecurityCredentials() { ProfileName = "so", Password = "inmation" });
CreateObject
Create an inmation object using the stateless interface
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
parentPath |
path of parent object as a string |
items |
list of objects to create, uses ObjectItem container class for inmation objects (properties for object set using PropertyItem container class for object properties) |
timeout |
Timeout in milliseconds (default 1000) |
Example Code:
//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
//First create path of the parent object
string path = "/";
//Then create name of the object
string name = "General";
//Define the object to create (in this case lets create new Profile)
ObjectItem obi = new ObjectItem(string.Empty);
obi.ClassType = SciModelClasses.MODEL_CLASS_PROFILE;
obi.ObjectType = SysObjectType.OT_OBJECT;
obi.Model = SciModelScope.MODEL_SCOPE_ACCESS;
//Define manadatory property value
PropertyItem p1 = new PropertyItem();
p1.RelativePath = "ObjectName";
p1.Value = name;
//Define additional property (its not mandatory property)
PropertyItem p2 = new PropertyItem();
p2.RelativePath = "ObjectDescription";
p2.Value = "description";
obi.Properties = new List<PropertyItem> { p1, p2 };
List<ObjectItem> lioi = new List<ObjectItem> { obi };
//Now create the object
Result result = sli.CreateObject(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, path, lioi);
DeleteObject
Delete an inmation object using the stateless interface
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
item |
Object to delete, instance of ObjectItem class including the path of the object |
timeout |
Timeout in milliseconds (default 1000) |
Example Code:
//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(
new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 }
);
//Now delete the object and all children
//Note that this also deletes all history data
Result result = sli.DeleteObject(
new SecurityCredentials() { ProfileName = "so", Password = "inmation" },
new ObjectItem("/System/Core/Item1")
);
DisableObject
Disable an inmation object using the stateless interface
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
item |
Object to disable, instance of ObjectItem class including the path of the object |
timeout |
Timeout in milliseconds (default 1000) |
Example Code:
//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(
new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 }
);
//now disable the object
Result result = sli.DisableObject(
new SecurityCredentials() { ProfileName = "so", Password = "inmation" },
new ObjectItem("/System/Core/Item1")
);
EnableObject
Enable an inmation object using the stateless interface
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
item |
Object to enable, instance of ObjectItem class including the path of the object |
timeout |
Timeout in milliseconds (default 1000) |
Example Code:
//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(
new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 }
);
//now enable the object
Result result = sli.EnableObject(
new SecurityCredentials() { ProfileName = "so", Password = "inmation" },
new ObjectItem("/System/Core/Item1")
);
Find
Calls a server side search for inmation objects
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
search |
String to be searched for in object name or object path |
model |
SciModelScope class, define the model to search for objects in (I/O Model, KPI Model etc.) |
dynonly |
Set this to true, to find only objects with dynamic property (excludes static object types, like folders) |
fullpath |
Set this to true, if the search parameter contains a full path to an object |
foundItems |
List of found objects, list of ObjectItem containers |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code:
//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig());
//list of ObjectItem to store search results
List<ObjectItem> items;
//define parameters for Find method
string searchFor = "localhost";
SciModelScope scope = SciModelScope.MODEL_SCOPE_IO;
bool searchOnlyForDynamicObjects = false;
bool searchForFullPath = false;
//query for the objects
//note that properties of the object are not returned
//use GetObjectItem() or ReadValue() to request properties of the object
Result r1 = sli.Find(
new SecurityCredentials() { ProfileName = "so", Password = "inmation" },
searchFor,
scope,
searchOnlyForDynamicObjects,
searchForFullPath,
out items);
if (r1.Succeeded())
{
foreach (var item in items)
{
Console.WriteLine(item.TagName);
Console.WriteLine(item.Path);
}
}
GetChild
Retrieves the specified child object of a given parent
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
parentPath |
Path of parent object, in string format |
childName |
Object name of child to fetch as a string |
child |
Fetched child object as an ObjectItem object |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code:
// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
// set path to parent object
string parentPath = "/System/Core";
// set ObjectName of the child object string child
Name = "localhost";
ObjectItem child;
// request child object information
// note that properties of the object are not returned
// use GetObjectItem() or ReadValue() to request properties of the object
Result r1 = sli.GetChild(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, parentPath, childObjectName, out child);
GetChildren
Retrieve a list of children for a specified object
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
parentPath |
Path of parent object, in string format |
children |
Fetched children objects as a list of ObjectItem objects |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code:
// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
// create the path to the parent object
string parentPath = "/System/Core";
List<ObjectItem> children;
// try to retrieve list of all children
var r1 = sli.GetChildren(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, parentPath, out children);
GetEventHistory
Retreives event history from the repository for specified time period using MongoDB query operators to filter results.
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
start |
Beginning of period to read as DateTime object |
end |
End of period to read as DateTime object |
aeEventList |
Retrieved events as List of AeEvent objects |
eventDataFilter |
MongoDB query operators to be applied. Instance of the FilterDescription class. Default is null - no filters applied |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code
// create the stateless call interface object
StatelessInterface sli = new StatelessInterface(tcpcfg);
// create list of event to generate
List<AeEvent> aeEventList = new List<AeEvent>();
// create a filter definition
FilterDefinition filter = new FilterDefinition();
filter.AddLogicalAndClause(MongoComparisonOperators.MCO_EQ, "datakey1", "value1");
filter.AddLogicalAndClause(MongoComparisonOperators.MCO_EQ, "datakey2", "value2");
// run api call
Result result = sli.GetEventHistory(credentials, DateTime.UtcNow - TimeSpan.FromHours(1), DateTime.UtcNow, out aeEventList, filter);
GetHistoricalFrame
Writes a list of object dynamic properties' values according to passed arguments
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
HistoryFrameItem |
Container object hosting read parameters (including start and end parameters after a successfull call) |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code:
// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
// set path to object
string path = "/System/Core/Item1";
// Container object hosting read parameters (including start and end parameters after a successfull call) HistoryFrameItem item = new HistoryFrameItem();
item.Path = path;
// request start and end timestamps of historical data
Result result = sli.GetHistoricalFrame(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, item);
GetObjectItem
Retrieves a container object ObjectItem instance for an inmation object
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
path |
Path of the object you wish to get, in string format |
fullGet |
Set to true if all properties of the object should be retrieved in the same call |
oItem |
Fetched object as an instance of the ObjectItem class |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code:
// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
//set path to object
string path = "/System/Core/localhost";
// set this to true, if all properties of the object should be fetched in the same call
bool fullGet = true;
// the object container
ObjectItem oItem;
// request object information
Result r1 = sli.GetObjectItem(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, path, fullGet, out oItem);
GetParent
Retrieves the parent object of a specified child object
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
path |
Path of the child object who’s parent you wish to get, in string format |
parent |
Fetched parent object as an instance of the ObjectItem class |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code:
// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig());
// set path to child object
string path = "/System/Core/localhost";
ObjectItem parent;
// request parent object information
// note that properties of the object are not returned
// use GetObjectItem() or ReadValue() to request properties of the object
Result r1 = sli.GetParent(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, path, out parent);
GetUserState
Reads the current value of an object’s user state
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
path |
Path of the object you wish to get, in string format |
states |
User states of the object as an instance of the ModUserState class |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code:
// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
// set path to object
string path = "/System/Core/localhost";
// User states are stored in array instance of ModUserState class ModUserState[] states;
// request user state of the object
Result r1 = sli.GetUserState(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, path, out states);
ReadHistoricalData
Read History values for a specified time range
Name | Description |
---|---|
historicalData |
Result set for the retrieved historical items as an instance of the HistoryResponse class |
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
start |
Beginning of period to read as DateTime object |
end |
End of period to read as DateTime object |
forSteppedLine |
ForSteppedLine parameter determines how intervals with no value will be treated during creation of BestFit aggregates (Default: False) |
numberOfIntervals |
Number of Intervals to be returned |
items |
Definition of the item for which history will be retrieved, instance of HistoricalDataItem class (containing path to item) |
treatUncertainAsBad |
Indicates how data with a StatusCode 'Uncertain' is treated with respect to Aggregate calculations (Default: True) |
percentageBad |
Indicates the minimum percentage of bad data in a given interval required for the StatusCode for to be set to Bad (Default: 100) |
percentageGood |
Indicates the minimum percentage of Good data in a given interval required for the StatusCode to be set to Good (Default: 100) |
useSlopedExtrapolation |
Indicates how the server interpolates data when no boundary value exists (Default: False) |
rawBoundvalue |
This argument takes effect only if the requested number of intervals is 1 (one), and it only affects the Raw aggregate. If this argument is true, bounding values are returned. The bounding values are defined by the OPC classic and OPC UA standards as closest values outside the requested interval, if the values at the exact start and end time of the intervals are absent |
Example Code:
// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
string itemPath = "/System/Core/Item1";
// Create item definition for history read call, contains path and aggregate that is used
HistoricalDataItem historyItem = new HistoricalDataItem(itemPath);
historyItem.Aggregates = new Aggregates[] {Aggregates.AGG_TYPE_INTERPOLATIVE};
HistoryResponse historyResponse;
// Read historical data
Result result = sli.ReadHistoricalData(
out historyResponse,
new SecurityCredentials() { ProfileName = "so", Password = "inmation" },
DateTime.UtcNow.AddDays(-1),
DateTime.UtcNow, //End time
false,
10,
new HistoricalDataItem[] { historyItem },
true,
100,
100,
false
false);
History calls made in system:inmation, using the SCI or otherwise, are compliant with the OPC UA Historical Access specification. For more information please refer to the OPC Foundation website.
ReadValue
Reads the value of an item using the stateless interface
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
item |
Object hosting the read parameters and the read value after a successful call, instance of the ReadItem class |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code:
// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
// pass credentials of the system owner and read
Result result = sli.ReadValue(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, new ReadItem("/System/Core/Item1"));
RunScript
Run a Lua script in the context of a specific object in the tree. The script execution is similar to the script execution in Action Items, but the result of the script is returned in the ReadItem object and NOT written to the object. The path of the ReadItem is used for specifying the script context. The Lua script can use any Lua libraries available to the object provided in the script context.
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
script |
Lua script to be run, defined as a string |
items |
List of ReadItem objects. Each ReadItem object in the list can contain a path that specifies script context. If multiple items are provided, the script will be executed on each of these context’s. The scripts results are returned in the ReadItem results. If no path is provided for a ReadItem, the script runs on system level. |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code:
// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
// create the ReadItem container based on given object path
// it will be used for the script result
ReadItem readItem = new ReadItem("/System/INMWS011/Examples/DemoData/ProcessData/DC4711");
List<ReadItem> readItems = new List<ReadItem> { readItem };
// define lua script
string script = "return math.random";
// Run the script in the context of the objects provided in containers
// the script result will NOT be written to the object
Result result = sli.RunScript(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, script, readItems);
RunScript is particularly useful when you want to use functionality that is available in Lua but not the SCI, for example, the setreferences Lua function. To set a security reference on an object in the I/O Model the following example code can be used:
public void assignProfile(string path, string profilepath)
{
ReadItem scriptcontext = new ReadItem(path);
string scriptcode = "";
scriptcode += "syslib.setreferences(syslib.getself(), " + Environment.NewLine;
scriptcode += " {" + Environment.NewLine;
scriptcode += " { " + Environment.NewLine;
scriptcode += " path='" + profilepath + "', " + Environment.NewLine;
scriptcode += " type = (syslib.model.codes.ReferenceType.SECURITY << 32) -- this is actually == 0, but it is here to show the principle" + Environment.NewLine;
scriptcode += " | syslib.model.flags.SecurityAttributes.INHERITABLE " + Environment.NewLine;
scriptcode += " | syslib.model.flags.SecurityAttributes.READ " + Environment.NewLine;
scriptcode += " }" + Environment.NewLine;
scriptcode += " })" + Environment.NewLine;
// This overwrites the current profile assignments!!
// if you want to add profiles, first use syslib.getreferences in the lua script above!
Result res = insi.RunScript(creds, scriptcode, new List<ReadItem>() { scriptcontext });
}
References are a 64bit mask, upper 32bit contain the ReferenceType and lower 32bit contain the SecurityAttributes (only valid for security references).
SetEvent
Set an event or events to a source according to the OPC specification
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
aeEventList |
List of AeEvent objects. Each instance of the AeEvent class requires the event source path, message, severity code and timestamp to be defined. The event type and event state can also be defined (defaults are simple event type and enabled state respectively). |
timeout |
Timeout in milliseconds (default 1000) |
Example Code
// create the stateless call interface object
StatelessInterface sli = new StatelessInterface(tcpcfg);
// events need to be written to object of type script events
string pathScriptEvents = "/System/CoreVM/Examples/DemoData/Events/ScriptEvent1";
// create list of event to generate
List<AeEvent> aeEventList = new List<AeEvent>();
// declare event and add to list
AeEvent event1 = new AeEvent(pathScriptEvents, "Message 1", 500, DateTime.UtcNow, EventNewState.OPC_CONDITION_ACTIVE);
event1.AddEventData("datakey1", "value1");
event1.AddEventData("datakey2", "value2");
aeEventList.Add(event1);
// Run SetEvents call
Result result = sli.SetEvents(credentials, aeEventList);
UpdateObject
Update inmation objects using the stateless interface
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
oItem |
Object to be updated, instance of the ObjectItem class containing path of update object and properties to update |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code:
// Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
// create the object item container object based on given path
string path = "/System/Core/Item1";
ObjectItem oItem = new ObjectItem(path);
// Prepare data to modify "ObjectDescription"
string relativePath1 = "ObjectDescription";
PropertyItem property1 = new PropertyItem() { RelativePath = ".ObjectDescription", Value = "TestObject" }
// Add "PropertyItem" to "Properties" collection of the "ObjectItem"
oItem.Properties.Add(property1);
// Now update the object
Result result = sli.UpdateObject(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, oItem);
UpdateProperty
Updates a list of properties according to passed arguments
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
item |
Property to be updated, instance of the UpdatePropertyItem class |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code:
//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
//First create the "ClassDefinition" object for the selected class type
ClassDefinition classDefinitionef = new ClassDefinition(SciModelClasses.MODEL_CLASS_GENITEM);
//Then create "PropertyDefinition" object for selected property. Use relative path as a parameter.
PropertyDefinition propertyDefinition = classDefinitionef.GetPropertyDefinition("ObjectDescription");
//Then create "UpdatePropertyItem" object
UpdatePropertyItem property = new UpdatePropertyItem();
//Set "PropertyDefinition" property
property.PropertyDefinition = propertyDefinition;
//Set path to the object containing the property which will be updated
property.Path = "/System/Core/Item1";
//Set new property value
property.Value = "New description";
//Now update property
Result rs = sli.UpdateProperty(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, property);
WriteHistoricalData
Writes a list of object dynamic properties' values according to passed arguments
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
items |
List of items containing VQT data, instances of the HistoryWriteItem class |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code:
//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
string itemPath = "/System/Core/h";
//Create item containing all data needed
HistoryWriteItem witem = new HistoryWriteItem();
//Set item path
witem.Path = itemPath;
//Prepare list of values to write
List<VQT> list = new List<VQT>();
VQT v1 = new VQT();
v1.Value = EmptyValue.Value;
v1.Timestamp = DateTime.UtcNow.AddSeconds(-10);
v1.QualityMask = QualityMaskCodes.GoodNoData; list.Add(v1);
VQT v2 = new VQT();
v2.Value = EmptyValue.Value;
v2.Timestamp = DateTime.UtcNow.AddSeconds(-5);
v2.QualityMask = QualityMaskCodes.Bad; list.Add(v2);
VQT v3 = new VQT();
v3.Value = 44; v3.Timestamp = DateTime.UtcNow;
v3.QualityMask = QualityMaskCodes.Good; list.Add(v3);
witem.Values = list;
//now write historical data
Result re = sli.WriteHistoricalData(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, new List<HistoryWriteItem> { witem }, 1000);
WriteValue
Write values to an object using the stateless interface
Name | Description |
---|---|
credentials |
Security credentials to connect to the Core, requires Profile Credentials and password. Instance of the SecurityCredentials class |
item |
Specific write parameters for the item. instance of the WriteItem class containing path and value |
mode |
Write mode specification |
packDelay |
Number of writes to group |
suppressAuditWrite |
Set to false to prevent creation of log entry for the write |
enforceDa20Write |
Set to true to force a write command using the OPC DA 2.0 specification |
timeout |
Timeout in milliseconds (default = 1000) |
Example Code:
//Create the stateless call interface object
StatelessInterface sli = new StatelessInterface(new TcpConfig() { HostNameOrIp = "localhost", Port = 6512 });
//Create the write item container object based on given object path.
//Note that no property is indicated in the path, because this method
//is only used to modify a value of the ItemValue property.
//Note that the value to be written is also passed here.
string path = "/System/CoreVM/Examples/DemoData/ProcessValues/Static";
WriteItem writeItem = new WriteItem(22, path);
//now write the value to the item
Result result = sli.WriteValue(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, writeItem);
//now write quality and timestamp with empty value
writeItem = new WriteItem(EmptyValue.Value, QualityMaskCodes.Uncertain, DateTime.UtcNow, path);
result = sli.WriteValue(new SecurityCredentials() { ProfileName = "so", Password = "inmation" }, writeItem);