umati Transformation Engine - API documentation Release Candidate
Transformation Engine API (south side)
|
Data Structures | |
struct | tek_sa_additional_file |
Configuration class which describes an additional file which is passed to the data client. More... | |
struct | tek_sa_data_client_configuration |
Configuration object containing the contents of the configuration files for the tek_sa_data_client_plugin or tek_sa_data_client instances. More... | |
struct | tek_sa_configuration |
Configuration struct that contains generic properties and settings for TEK instance. More... | |
struct | tek_sa_guid |
The representation of a GUID when used as a field type. More... | |
struct | tek_sa_byte_string |
The representation of a byte array with variable length when used as a field type. More... | |
struct | tek_sa_string |
The representation of a string with variable length when used as a field type. More... | |
struct | tek_sa_complex_data |
The representation of a field value which has a type which is not a predefined type. More... | |
struct | tek_sa_complex_data_array_item |
The representation of the items of an array of complex data values with exactly one dimension. More... | |
struct | tek_sa_complex_data_array |
The representation of an array of complex data with exactly one dimension. More... | |
struct | tek_sa_complex_data_matrix |
The representation of array of complex data with more than one dimension. More... | |
struct | tek_sa_variant_array |
The representation of a one dimensional array of the supported base types. More... | |
struct | tek_sa_variant_matrix |
The representation of an array with more than one dimension of the supported base types. More... | |
struct | tek_sa_variant |
The representation of a single value (which may be of array type too). More... | |
struct | tek_sa_struct_field_type_definition |
The type definition of a record field in a user defined struct type. More... | |
struct | tek_sa_struct_definition |
The type definition of a user defined record type. More... | |
struct | tek_sa_enum_item_definition |
The definition of an enum item which is defined in a user defined enum type. More... | |
struct | tek_sa_enum_definition |
The type definition of a user defined enum type. More... | |
struct | tek_sa_method_argument_description |
The description of a method parameter. More... | |
struct | tek_sa_field_write_request |
Structure to encapsulate the parameters of a write field request. More... | |
struct | tek_sa_write_result |
Structure to encapsulate the result of a write field request. More... | |
struct | tek_sa_read_result |
Structure to encapsulate the result of a read operation of a single field. More... | |
struct | tek_sa_event_parameter |
Structure to encapsulate an event parameter. More... | |
struct | tek_sa_dc_event |
An event which may be sent from the data client to tek_sa_transformation_engine::post_event. More... | |
union | tek_sa_variant_array.data |
The array values. More... | |
union | tek_sa_variant.data |
The value. More... | |
Macros | |
#define | TEK_SA_ERR_UNSPECIFIED 1000 |
unspecified error to be used when no more specific error is available. More... | |
Typedefs | |
typedef int64_t | tek_sa_type_handle |
The type of a handle which is returned for user defined types. More... | |
typedef int64_t | tek_sa_type_handle_or_type_enum |
The type for a reference handle which references either a user defined type (see tek_sa_type_handle) or a predefined type (See tek_sa_variant_type.) More... | |
typedef int64_t | tek_sa_datetime |
The type of date and time values wen used as a field type. More... | |
typedef struct tek_sa_variant | tek_sa_field_value |
Type of data client field values. More... | |
typedef uint32_t | tek_sa_field_handle |
Handle type for a field definition. More... | |
typedef uint32_t | tek_sa_event_handle |
Handle type for an event definition. More... | |
typedef uint32_t | tek_sa_alarm_handle |
Handle type for an alarm definition. More... | |
typedef uint32_t | tek_sa_method_handle |
Handle type for a method definition. More... | |
StatusCodes | |
typedef int | TEK_SA_RESULT |
The return value type of all interface functions (which need to return information about success of the operation). More... | |
#define | TEK_SA_ERR_SUCCESS 0 |
An operation was completed successfully. More... | |
#define | TEK_SA_ERR_NON_BLOCKING_IMPOSSIBLE 10 |
A data client function was called in an asynchronous manner while the implementation can not use multiple threads. More... | |
#define | TEK_SA_ERR_OUT_OF_MEMORY 11 |
The data client or the Transformation Engine can not process a request because it has no more system resources. More... | |
#define | TEK_SA_ERR_INVALID_PARAMETER 12 |
The parameters passed to the function are invalid. More... | |
#define | TEK_SA_ERR_RETRY_LATER 0xffffffff |
A data client function was called in an asynchronous manner while the number of inflight calls is already active. More... | |
#define | TEK_SA_READ_RESULT_STATUS_OK 0 |
A read operation completed successfully. More... | |
#define | TEK_SA_READ_RESULT_STATUS_NOK 1 |
A read operation failed. More... | |
#define | TEK_SA_READ_RESULT_STATUS_TIMEOUT 2 |
A read operation did not complete within the specified time limit. More... | |
#define | TEK_SA_READ_RESULT_STATUS_INVALID_HANDLE 3 |
The read operation failed because the passed field handle was invalid. More... | |
#define | TEK_SA_BLOCK_TRANSFER_END_OF_FILE 26 |
The read operation read until the end of file. More... | |
#define | TEK_SA_BLOCK_TRANSFER_ABORT 24 |
The block read or write operation should be stopped. More... | |
The module Common Definitions contains functions, structs and typedefs which are used by the Data Client as well as the Transformation Engine.
struct tek_sa_additional_file |
Configuration class which describes an additional file which is passed to the data client.
Definition at line 245 of file south_api.h.
Data Fields | ||
---|---|---|
char * | name |
The name of the additional file as written in the configuration. |
char * | content |
The content of additional file. |
struct tek_sa_data_client_configuration |
Configuration object containing the contents of the configuration files for the tek_sa_data_client_plugin or tek_sa_data_client instances.
Definition at line 260 of file south_api.h.
Data Fields | ||
---|---|---|
char * | config |
The configuration file as UTF-8 encoded JSON string |
struct tek_sa_additional_file * | additional_files |
The additional files which are referenced in the configuration. |
uint32_t | additional_files_count |
The number of additional files |
struct tek_sa_configuration |
Configuration struct that contains generic properties and settings for TEK instance.
Definition at line 278 of file south_api.h.
Data Fields | ||
---|---|---|
uint32_t | request_timeout_ms |
generic definition for timeouts with linkage to communication to connected dataclients (e.g. requests), value is given in milli-seconds |
struct tek_sa_guid |
The representation of a GUID when used as a field type.
See also https://reference.opcfoundation.org/v104/Core/docs/Part6/5.1.3/
Definition at line 310 of file south_api.h.
Data Fields | ||
---|---|---|
uint32_t | data1 |
The Data1 field. |
uint16_t | data2 |
The Data2 field. |
uint16_t | data3 |
The Data3 field. |
uint8_t | data4[8] |
The Data4 field. |
struct tek_sa_byte_string |
The representation of a byte array with variable length when used as a field type.
See https://reference.opcfoundation.org/Core/docs/Part6/5.2.2/#5.2.2.7
Definition at line 335 of file south_api.h.
Data Fields | ||
---|---|---|
int32_t | length | The length of the byte string. |
unsigned char * | data |
The bytes of the byte string |
struct tek_sa_string |
The representation of a string with variable length when used as a field type.
See https://reference.opcfoundation.org/Core/docs/Part6/5.2.2/#5.2.2.4
Definition at line 353 of file south_api.h.
Data Fields | ||
---|---|---|
int32_t | length | The length of the byte string. |
unsigned char * | data | The UTF-8 encoded characters of the string. |
struct tek_sa_complex_data |
The representation of a field value which has a type which is not a predefined type.
A value with a complex data type which was registered at the tek by calling tek_sa_transformation_engine::register_struct_type.
Definition at line 378 of file south_api.h.
Data Fields | ||
---|---|---|
tek_sa_type_handle | type | The type handle of the registered data type. |
uint32_t | data_length |
The number of bytes in the data field. This is needed because the encoded length may differ for items of the same type. |
unsigned char * | data |
The bytes of the serialized value. The serialization is compatible with the binary OPC UA encoding of structures as described in https://reference.opcfoundation.org/v104/Core/docs/Part6/5.2.6/. |
struct tek_sa_complex_data_array_item |
The representation of the items of an array of complex data values with exactly one dimension.
See also tek_sa_complex_data_array
Definition at line 408 of file south_api.h.
Data Fields | ||
---|---|---|
uint32_t | data_length |
The number of bytes in the data field. This is needed because the encoded length may differ for items of the same type. |
unsigned char * | data |
The bytes of the serialized value. See also tek_sa_complex_data::data |
struct tek_sa_complex_data_array |
The representation of an array of complex data with exactly one dimension.
A one-dimensional array of values which are of a complex data type.
Definition at line 434 of file south_api.h.
Data Fields | ||
---|---|---|
tek_sa_type_handle | type | The type handle of the registered type of the array items. |
uint32_t | number_of_items | The number of items in the array. |
struct tek_sa_complex_data_array_item * | data | The array data, which consists of the concatenation of all serialized items. |
struct tek_sa_complex_data_matrix |
The representation of array of complex data with more than one dimension.
A multi-dimensional array of values which are of a complex data type.
Definition at line 456 of file south_api.h.
Data Fields | ||
---|---|---|
tek_sa_type_handle | type | The type handle of the registered type of the array items. |
uint32_t | dimension_length |
The number of dimensions in the array.
|
uint32_t * | dimensions |
The array dimensions. Multi-dimensional arrays are encoded as a one-dimensional array and this field specifies the dimensions of the array. The original array can be reconstructed using this information. Higher rank dimensions are serialized first. For example, an array with dimensions [2,2,2] is written in this order: [0,0,0], [0,0,1], [0,1,0], [0,1,1], [1,0,0], [1,0,1], [1,1,0], [1,1,1] This is compatible with the encoding used by OPC UA array types: https://reference.opcfoundation.org/v104/Core/docs/Part6/5.2.2/#5.2.2.16 |
struct tek_sa_complex_data_array_item * | data | The array data, which consists of the concatenation of all serialized items. |
struct tek_sa_variant_array |
The representation of a one dimensional array of the supported base types.
Definition at line 564 of file south_api.h.
Data Fields | ||
---|---|---|
uint32_t | length | The number of elements in the array. |
union tek_sa_variant_array.data | data | The array values. |
struct tek_sa_variant_matrix |
The representation of an array with more than one dimension of the supported base types.
Definition at line 592 of file south_api.h.
Data Fields | ||
---|---|---|
uint32_t | dimension_length | The number of array dimensions. |
uint32_t * | dimensions |
The array dimensions. Multi-dimensional arrays are encoded as a one-dimensional array and this field specifies the dimensions of the array. The original array can be reconstructed using this information. Higher rank dimensions are serialized first. For example, an array with dimensions [2,2,2] is written in this order: [0,0,0], [0,0,1], [0,1,0], [0,1,1], [1,0,0], [1,0,1], [1,1,0], [1,1,1] This is compatible with the encoding used by OPC UA array types: https://reference.opcfoundation.org/v104/Core/docs/Part6/5.2.2/#5.2.2.16 |
struct tek_sa_variant_array | data | The array values. |
struct tek_sa_variant |
The representation of a single value (which may be of array type too).
The built-in types (bool, (u)int_{8,16,32,64}_t, strings, guids, datetime correspond to a subset of the types defined at https://reference.opcfoundation.org/Core/docs/Part6/5.1.2/ and are encoded as described in https://reference.opcfoundation.org/Core/docs/Part6/5.2.2/.
Definition at line 624 of file south_api.h.
Data Fields | ||
---|---|---|
uint8_t | type |
The type of the value. Must be one of the values described in tek_sa_variant_type. |
union tek_sa_variant.data | data | The value. |
struct tek_sa_struct_field_type_definition |
The type definition of a record field in a user defined struct type.
Definition at line 669 of file south_api.h.
Data Fields | ||
---|---|---|
char * | name | The name of the data field. |
tek_sa_type_handle_or_type_enum | type | The type of the field, represented as type_handle or type enum. |
struct tek_sa_struct_definition |
The type definition of a user defined record type.
Definition at line 682 of file south_api.h.
Data Fields | ||
---|---|---|
char * | name | The name of the type. |
struct tek_sa_struct_field_type_definition * | items | The definition of the record fields. |
uint32_t | item_count | The number of fields in the record type. |
struct tek_sa_enum_item_definition |
The definition of an enum item which is defined in a user defined enum type.
Definition at line 700 of file south_api.h.
Data Fields | ||
---|---|---|
char * | name | The name of the enum item. |
int32_t | value | The numeric value of the enum item. |
struct tek_sa_enum_definition |
The type definition of a user defined enum type.
Definition at line 713 of file south_api.h.
Data Fields | ||
---|---|---|
char * | name | The name of the type. |
struct tek_sa_enum_item_definition * | items | The defined enum values of this type. |
uint32_t | item_count | The number of defined enum values. |
struct tek_sa_method_argument_description |
The description of a method parameter.
See tek_sa_transformation_engine::register_method
Definition at line 732 of file south_api.h.
Data Fields | ||
---|---|---|
char const * | name | The name of the method parameter. |
enum tek_sa_variant_type | type | The type of the method parameter. |
struct tek_sa_field_write_request |
Structure to encapsulate the parameters of a write field request.
Definition at line 859 of file south_api.h.
Data Fields | ||
---|---|---|
tek_sa_field_handle | handle | The field handle as returned from tek_sa_transformation_engine::register_field. |
tek_sa_field_value | value | The value to be written to the field. |
struct tek_sa_write_result |
Structure to encapsulate the result of a write field request.
Definition at line 871 of file south_api.h.
Data Fields | ||
---|---|---|
TEK_SA_RESULT | status | The write operation result. |
tek_sa_field_handle | handle | The handle of the field written. |
struct tek_sa_read_result |
Structure to encapsulate the result of a read operation of a single field.
Definition at line 883 of file south_api.h.
Data Fields | ||
---|---|---|
TEK_SA_RESULT | status | The read operation result. |
tek_sa_field_handle | handle | The handle of the read field. |
tek_sa_field_value | value |
The read value.
|
struct tek_sa_event_parameter |
Structure to encapsulate an event parameter.
Definition at line 903 of file south_api.h.
Data Fields | ||
---|---|---|
char const * | name | The name of the parameter. |
tek_sa_field_value | value | The value of the event parameter. |
struct tek_sa_dc_event |
An event which may be sent from the data client to tek_sa_transformation_engine::post_event.
Definition at line 915 of file south_api.h.
Data Fields | ||
---|---|---|
tek_sa_datetime | timestamp |
The Timestamp of the event.
|
int16_t | severity |
The severity level of the event. The severity is defined as in https://reference.opcfoundation.org/v104/Core/docs/Part5/6.4.2/ which is cited here: Severity is an indication of the urgency of the Event. This is also commonly called “priority”. Values will range from 1 to 1 000, with 1 being the lowest severity and 1 000 being the highest. Typically, a severity of 1 would indicate an Event which is informational in nature, while a value of 1 000 would indicate an Event of catastrophic nature, which could potentially result in severe financial loss or loss of life. |
tek_sa_event_handle | event_type |
The event type handle as returned by the call to tek_sa_transformation_engine::register_event.
|
tek_sa_field_handle | source |
The handle of the source of the event. The source of the event is a field in the data client. As not all events have a source, this field may be equal to TEK_SA_FIELD_HANDLE_INVALID.
|
uint32_t | number_of_parameters | The number of event parameters. |
struct tek_sa_event_parameter * | parameters | The event parameters. |
union tek_sa_variant_array.data |
The array values.
Definition at line 569 of file south_api.h.
Data Fields | ||
---|---|---|
bool * | b | |
uint8_t * | ui8 | |
int8_t * | i8 | |
uint16_t * | ui16 | |
int16_t * | i16 | |
uint32_t * | ui32 | |
int32_t * | i32 | |
uint64_t * | ui64 | |
int64_t * | i64 | |
float * | f | |
double * | d | |
tek_sa_datetime * | dt | |
struct tek_sa_string * | s | |
struct tek_sa_guid * | guid | |
struct tek_sa_byte_string * | bs |
union tek_sa_variant.data |
The value.
Definition at line 633 of file south_api.h.
Data Fields | ||
---|---|---|
bool | b | |
uint8_t | ui8 | |
int8_t | i8 | |
uint16_t | ui16 | |
int16_t | i16 | |
uint32_t | ui32 | |
int32_t | i32 | |
uint64_t | ui64 | |
int64_t | i64 | |
float | f | |
double | d | |
tek_sa_datetime | dt | |
struct tek_sa_string | s | |
struct tek_sa_guid | guid | |
struct tek_sa_byte_string | bs | |
struct tek_sa_variant_array | array | |
struct tek_sa_variant_matrix | matrix | |
struct tek_sa_complex_data | complex | |
struct tek_sa_complex_data_array | complex_array | |
struct tek_sa_complex_data_matrix | complex_matrix |
#define TEK_SA_ERR_SUCCESS 0 |
An operation was completed successfully.
Definition at line 784 of file south_api.h.
#define TEK_SA_ERR_NON_BLOCKING_IMPOSSIBLE 10 |
A data client function was called in an asynchronous manner while the implementation can not use multiple threads.
The TEK will call the function in a synchronous manner again.
See Asynchronous Data Client calls and tek_sa_data_client_capabilities
Definition at line 795 of file south_api.h.
#define TEK_SA_ERR_OUT_OF_MEMORY 11 |
The data client or the Transformation Engine can not process a request because it has no more system resources.
Definition at line 801 of file south_api.h.
#define TEK_SA_ERR_INVALID_PARAMETER 12 |
The parameters passed to the function are invalid.
Definition at line 804 of file south_api.h.
#define TEK_SA_ERR_RETRY_LATER 0xffffffff |
A data client function was called in an asynchronous manner while the number of inflight calls is already active.
The TEK will call the function again at a later time.
See Asynchronous Data Client calls and tek_sa_data_client_capabilities
Definition at line 816 of file south_api.h.
#define TEK_SA_READ_RESULT_STATUS_OK 0 |
A read operation completed successfully.
Definition at line 819 of file south_api.h.
#define TEK_SA_READ_RESULT_STATUS_NOK 1 |
A read operation failed.
Definition at line 822 of file south_api.h.
#define TEK_SA_READ_RESULT_STATUS_TIMEOUT 2 |
A read operation did not complete within the specified time limit.
Definition at line 825 of file south_api.h.
#define TEK_SA_READ_RESULT_STATUS_INVALID_HANDLE 3 |
The read operation failed because the passed field handle was invalid.
Definition at line 829 of file south_api.h.
#define TEK_SA_BLOCK_TRANSFER_END_OF_FILE 26 |
The read operation read until the end of file.
This result value applies to the tek_sa_transformation_engine::block_read_data callback.
Definition at line 837 of file south_api.h.
#define TEK_SA_BLOCK_TRANSFER_ABORT 24 |
The block read or write operation should be stopped.
This result value applies to the tek_sa_transformation_engine::block_read_data and the tek_sa_transformation_engine::block_write_data callback.
Definition at line 846 of file south_api.h.
#define TEK_SA_ERR_UNSPECIFIED 1000 |
unspecified error to be used when no more specific error is available.
Definition at line 852 of file south_api.h.
typedef int64_t tek_sa_type_handle |
The type of a handle which is returned for user defined types.
The TEK creates a unique type handle for every type registered with a call to tek_sa_transformation_engine::register_struct_type or tek_sa_transformation_engine::register_enum_type. The TEK also ensures that the value range of these handles does not overlap with tek_sa_variant_type.
Definition at line 298 of file south_api.h.
typedef int64_t tek_sa_type_handle_or_type_enum |
The type for a reference handle which references either a user defined type (see tek_sa_type_handle) or a predefined type (See tek_sa_variant_type.)
Definition at line 304 of file south_api.h.
typedef int64_t tek_sa_datetime |
The type of date and time values wen used as a field type.
The definition is based on OPC UA DateTime (see https://reference.opcfoundation.org/Core/docs/Part6/5.2.2/#5.2.2.5)
Definition at line 369 of file south_api.h.
typedef struct tek_sa_variant tek_sa_field_value |
Type of data client field values.
Definition at line 660 of file south_api.h.
typedef uint32_t tek_sa_field_handle |
Handle type for a field definition.
Definition at line 759 of file south_api.h.
typedef uint32_t tek_sa_event_handle |
Handle type for an event definition.
Definition at line 762 of file south_api.h.
typedef uint32_t tek_sa_alarm_handle |
Handle type for an alarm definition.
Definition at line 765 of file south_api.h.
typedef uint32_t tek_sa_method_handle |
Handle type for a method definition.
Definition at line 768 of file south_api.h.
typedef int TEK_SA_RESULT |
The return value type of all interface functions (which need to return information about success of the operation).
Definition at line 781 of file south_api.h.
enum tek_sa_variant_type |
The predefined types which can be processed in the TE.
This enum type is a composition of enum and flag values. Each enum value (the ones not starting with "TEK_SA_VARIANT_TYPE_FLAG") may be combined with zero or one flags (the ones starting with "TEK_SA_VARIANT_TYPE_FLAG").
Enumerator | |
---|---|
TEK_SA_VARIANT_TYPE_NULL | The invalid type id. |
TEK_SA_VARIANT_TYPE_BOOL | The type id of a bool value. |
TEK_SA_VARIANT_TYPE_UINT8_T | The type id of an unsigned byte value. |
TEK_SA_VARIANT_TYPE_INT8_T | The type id of a signed byte value. |
TEK_SA_VARIANT_TYPE_UINT16_T | The type id of an unsigned short value. |
TEK_SA_VARIANT_TYPE_INT16_T | The type id of a signed short value. |
TEK_SA_VARIANT_TYPE_UINT32_T | The type id of an unsigned 32bit integer value. |
TEK_SA_VARIANT_TYPE_INT32_T | The type id of a signed 32bit integer value value. |
TEK_SA_VARIANT_TYPE_UINT64_T | The type id of an unsigned 64bit integer value. |
TEK_SA_VARIANT_TYPE_INT64_T | The type id of a signed 64bit integer value. |
TEK_SA_VARIANT_TYPE_FLOAT | The type id of a 32bit floating point value. |
TEK_SA_VARIANT_TYPE_DOUBLE | The type id of a 64bit floating point value. |
TEK_SA_VARIANT_TYPE_DATETIME | The type id of a date and time value. See tek_sa_datetime. |
TEK_SA_VARIANT_TYPE_STRING | The type id of a string value. See tek_sa_string. |
TEK_SA_VARIANT_TYPE_GUID | The type id of a GUID value. See tek_sa_guid. |
TEK_SA_VARIANT_TYPE_BYTE_STRING | The type id of a byte string value. See tek_sa_byte_string. |
TEK_SA_VARIANT_TYPE_COMPLEX | The type id of a value with a complex data type. See tek_sa_transformation_engine::register_struct_type. |
TEK_SA_VARIANT_TYPE_FLAG_ARRAY | The flag which is set to declare an array with one dimension of the base type. |
TEK_SA_VARIANT_TYPE_FLAG_MATRIX | The flag which is set to declare an array with more than one dimension of the base type. |
Definition at line 500 of file south_api.h.
Flags type which contains the attributes of a data client field.
Definition at line 747 of file south_api.h.
enum tek_sa_log_level_t |
Definition of the possible logging levels which can be used in tek_sa_transformation_engine::log.
Enumerator | |
---|---|
TEK_SA_LOG_LEVEL_TRACE | |
TEK_SA_LOG_LEVEL_DEBUG | |
TEK_SA_LOG_LEVEL_INFO | |
TEK_SA_LOG_LEVEL_WARNING | |
TEK_SA_LOG_LEVEL_ERROR | |
TEK_SA_LOG_LEVEL_CRITICAL |
Definition at line 978 of file south_api.h.