Interface ot the Transformation Engine. More...

#include <south_api.h>

Data Fields
Registration functions for data client operations and data fields
TEK_SA_RESULT(*	register_field )(tek_sa_data_client_handle dc, const char name, enum tek_sa_field_attributes attributes, enum tek_sa_variant_type type, tek_sa_field_handle new_field_handle)
	Registers a new field of a data client with a name inside the TEK. More...

TEK_SA_RESULT(*	register_method )(tek_sa_data_client_handle dc, const char name, struct tek_sa_method_argument_description input_parameter[], uint32_t number_of_input_parameters, struct tek_sa_method_argument_description output_parameter[], uint32_t number_of_output_parameters, tek_sa_method_handle new_method_handle)
	Registers a new method at the TEK. More...

TEK_SA_RESULT(*	register_event )(tek_sa_data_client_handle dc, const char name, tek_sa_event_handle new_event_handle)
	Registers a new Event that a data client might raise. More...

TEK_SA_RESULT(*	register_alarm )(tek_sa_data_client_handle dc, const char name, const int16_t severity, const tek_sa_field_handle source, tek_sa_alarm_handle new_alarm_handle)
	Registers an alarm at the TEK. More...

Registration functions for extended types
TEK_SA_RESULT(*	register_enum_type )(tek_sa_data_client_handle dc, struct tek_sa_enum_definition const type_definition, tek_sa_type_handle new_type_handle)
	Register a user defined enum type. More...

TEK_SA_RESULT(*	register_struct_type )(tek_sa_data_client_handle dc, struct tek_sa_struct_definition const type_definition, tek_sa_type_handle new_type_handle)
	Register a user defined struct type. More...

Alarm and Event functions
TEK_SA_RESULT(*	post_event )(tek_sa_data_client_handle dc, struct tek_sa_dc_event const *event)
	Post an event which was declared with a call to either get_global_event or register_event. More...

TEK_SA_RESULT(*	set_alarm )(tek_sa_data_client_handle dc, const tek_sa_alarm_handle alarm)
	Sets an alarm. More...

TEK_SA_RESULT(*	reset_alarm )(tek_sa_data_client_handle dc, const tek_sa_alarm_handle alarm)
	Clears/resets an alarm. More...

Miscellaneous functions
TEK_SA_RESULT(*	log )(tek_sa_data_client_handle source, enum tek_sa_log_level_t lvl, const char *format, va_list args)
	Logging function for data clients. More...

tek_sa_event_handle(*	get_global_event )(const char *name)
	Get a handle of a globally defined event. More...

TEK_SA_RESULT(*	update_capabilities )(tek_sa_data_client_handle dc, struct tek_sa_data_client_capabilities const *capabilities)
	Notifies the TEK of the change of the client's capabilities. More...

Data client callbacks
TEK_SA_RESULT(*	read_progress )(tek_sa_data_client_handle dc, uint64_t request_id, uint64_t progress)
	Callback to signal progress of a read operation to the TEK. More...

TEK_SA_RESULT(*	read_result )(tek_sa_data_client_handle dc, uint64_t request_id, TEK_SA_RESULT result, const struct tek_sa_read_result results[], uint32_t number_of_results)
	Callback of the data client read operation. More...

TEK_SA_RESULT(*	notify_change )(tek_sa_data_client_handle dc, const struct tek_sa_read_result changes[], uint32_t number_of_changes)
	Callback to notify about a change of subscribed data fields. More...

TEK_SA_RESULT(*	write_result )(tek_sa_data_client_handle dc, uint64_t request_id, TEK_SA_RESULT result, const struct tek_sa_write_result results[], uint32_t number_of_results)
	Callback of the data client write operation. More...

TEK_SA_RESULT(*	call_method_result )(tek_sa_data_client_handle dc, uint64_t request_id, TEK_SA_RESULT result, const tek_sa_field_value results[], uint32_t number_of_results)
	Callback of a data client method call. More...

TEK_SA_RESULT(*	block_read_data )(tek_sa_data_client_handle dc, uint64_t request_id, TEK_SA_RESULT result, unsigned char buffer[], uint32_t buffer_length)
	Callback from the data client to the TEK signaling the next data chunk of the block transfer. More...

TEK_SA_RESULT(*	block_write_data )(tek_sa_data_client_handle dc, uint64_t request_id, unsigned char buffer[], uint32_t buffer_length, uint32_t *bytes_written)
	Callback from the data client to the TEK requesting another chunk to write to the data client. More...

TEK_SA_RESULT(*	block_write_result )(tek_sa_data_client_handle dc, uint64_t request_id, TEK_SA_RESULT result)
	Callback from the data client to the TEK with the final result of the block transfer. More...

Detailed Description

Interface ot the Transformation Engine.

Interface exported by the TEK, which is given a data client plugin (dll/so) to interact with the TEK.

Definition at line 1440 of file south_api.h.

Field Documentation

◆ register_field

TEK_SA_RESULT(* tek_sa_transformation_engine::register_field) (tek_sa_data_client_handle dc, const char *name, enum tek_sa_field_attributes attributes, enum tek_sa_variant_type type, tek_sa_field_handle *new_field_handle)

Registers a new field of a data client with a name inside the TEK.

Parameters

dc	The data client that registers at the TEK.
name	The name of the field. The data client decides the name.
attributes	The attributes of the field, e.g. is writeable.
type	The data type of the field.
new_field_handle	result of registration, only valid when method returns TEK_SA_ERR_SUCCESS.

Returns: TEK_SA_ERR_SUCCESS or error code when registration failed (e.g. duplicate registration, empty name...).

Definition at line 1458 of file south_api.h.

◆ register_method

TEK_SA_RESULT(* tek_sa_transformation_engine::register_method) (tek_sa_data_client_handle dc, const char *name, struct tek_sa_method_argument_description input_parameter[], uint32_t number_of_input_parameters, struct tek_sa_method_argument_description output_parameter[], uint32_t number_of_output_parameters, tek_sa_method_handle *new_method_handle)

Registers a new method at the TEK.

Parameters

dc	The data client that registers at the TEK.
name	The name of the method.
tek_sa_method_argument_description	The description of the method input arguments.
number_of_input_parameters	The number of input parameters.
tek_sa_method_argument_description	The description of the method output arguments.
number_of_output_parameters	The number of output parameters.
new_method_handle	result of registration, only valid when method returns TEK_SA_ERR_SUCCESS.

Returns: TEK_SA_ERR_SUCCESS or error code when registration failed (e.g. duplicate registration, empty name...).

Definition at line 1481 of file south_api.h.

◆ register_event

TEK_SA_RESULT(* tek_sa_transformation_engine::register_event) (tek_sa_data_client_handle dc, const char *name, tek_sa_event_handle *new_event_handle)

Registers a new Event that a data client might raise.

Parameters

dc	The data client that registers at the TEK.
name	The name of the event. Must be unique within all events registered from this dc.
new_event_handle	result of registration, only valid when method returns TEK_SA_ERR_SUCCESS.

Returns: TEK_SA_ERR_SUCCESS or error code when registration failed (e.g. duplicate registration, empty name...).

The TEK ensures that the set of handles between the predefined events and the registered events are disjoint.

Definition at line 1504 of file south_api.h.

◆ register_alarm

TEK_SA_RESULT(* tek_sa_transformation_engine::register_alarm) (tek_sa_data_client_handle dc, const char *name, const int16_t severity, const tek_sa_field_handle source, tek_sa_alarm_handle *new_alarm_handle)

Registers an alarm at the TEK.

Parameters

dc	The data client that registers at the TEK.
name	The name of the new alarm, must be unique within all alarms registered for this data client.
severity	The alarm severity level.
source	field the alarm relates to, the same field can be used for multiple alarms.
new_alarm_handle	result of registration only valid when method returns TEK_SA_ERR_SUCCESS.

Returns: TEK_SA_ERR_SUCCESS or error code when registration failed (e.g. duplicate registration, empty name...).

Definition at line 1523 of file south_api.h.

◆ register_enum_type

TEK_SA_RESULT(* tek_sa_transformation_engine::register_enum_type) (tek_sa_data_client_handle dc, struct tek_sa_enum_definition const *type_definition, tek_sa_type_handle *new_type_handle)

Register a user defined enum type.

Parameters

dc	The data client that registers at the TEK.
tek_sa_enum_definition	The definition of the enumeration.
result	A tek_sa_type_handle associated to the registered enum.
new_type_handle	result of registration, only valid when method returns TEK_SA_ERR_SUCCESS.

Returns: TEK_SA_ERR_SUCCESS or error code when registration failed (e.g. duplicate registration, empty name...).

Definition at line 1547 of file south_api.h.

◆ register_struct_type

TEK_SA_RESULT(* tek_sa_transformation_engine::register_struct_type) (tek_sa_data_client_handle dc, struct tek_sa_struct_definition const *type_definition, tek_sa_type_handle *new_type_handle)

Register a user defined struct type.

Parameters

dc	The data client that registers at the TEK.
tek_sa_struct_definition	The definition of the struct.
new_type_handle	result of registration call when successful, only valid when method returns TEK_SA_ERR_SUCCESS.

Returns: indicator whether the type definition was successfully registered

Definition at line 1561 of file south_api.h.

◆ post_event

TEK_SA_RESULT(* tek_sa_transformation_engine::post_event) (tek_sa_data_client_handle dc, struct tek_sa_dc_event const *event)

Post an event which was declared with a call to either get_global_event or register_event.

Parameters

dc	Handle of the data client which sends the event.
event	A event structure. See `dc_event`.

Returns: indicator whether the event was successfully posted or not

Definition at line 1581 of file south_api.h.

◆ set_alarm

TEK_SA_RESULT(* tek_sa_transformation_engine::set_alarm) (tek_sa_data_client_handle dc, const tek_sa_alarm_handle alarm)

Sets an alarm.

Parameters

dc	Handle of the data client that sets the alarm.
alarm	Handle of the alarm to be set.

Returns: indicator whether setting the alarm was successful or not

Todo:: [C, TEAM] called by data_client after connect, regardless of "acknowledge" calls during previous connection?

Definition at line 1594 of file south_api.h.

◆ reset_alarm

TEK_SA_RESULT(* tek_sa_transformation_engine::reset_alarm) (tek_sa_data_client_handle dc, const tek_sa_alarm_handle alarm)

Clears/resets an alarm.

Parameters

dc	Handle of the data client that clears/resets the alarm.
alarm	Handle of the alarm to be cleared/reset.

Returns: indicator whether resetting the alarm was successful or not

Definition at line 1604 of file south_api.h.

◆ log

TEK_SA_RESULT(* tek_sa_transformation_engine::log) (tek_sa_data_client_handle source, enum tek_sa_log_level_t lvl, const char *format, va_list args)

Logging function for data clients.

The TEK bundles the messages of all data clients.

The TEK must be aware of data clients running in different threads than the TEK itself and is responsible for handling multi-threaded access to the function.

Parameters

data_client_handle	The data client that logs a message.
lvl	The logging level.
format	The message format string. Format must be compatible to `printf`.
args	A va_list that contains all the arguments for the format string.

Returns: log result status code; can be ignored normally or used for debugging.

Definition at line 1630 of file south_api.h.

◆ get_global_event

tek_sa_event_handle(* tek_sa_transformation_engine::get_global_event) (const char *name)

Get a handle of a globally defined event.

Parameters

name	name of globally defined event.

Returns: handle to globally defined event

Todo:

[C, TEAM] define the predefined events

[C, TEAM] define return value when event with given name does not exist?

The TEK ensures that the set of handles between the predefined events and the registered events are disjoint.

Definition at line 1648 of file south_api.h.

◆ update_capabilities

TEK_SA_RESULT(* tek_sa_transformation_engine::update_capabilities) (tek_sa_data_client_handle dc, struct tek_sa_data_client_capabilities const *capabilities)

Notifies the TEK of the change of the client's capabilities.

Parameters

dc	Handle of the data client that informs about the change of its capabilities.
tek_sa_data_client_capabilities	The updated client capabilities.

Returns: (void)

Definition at line 1657 of file south_api.h.

◆ read_progress

TEK_SA_RESULT(* tek_sa_transformation_engine::read_progress) (tek_sa_data_client_handle dc, uint64_t request_id, uint64_t progress)

Callback to signal progress of a read operation to the TEK.

Parameters

dc	Handle of the data client that is the source of the call
request_id	id of request to data client which triggered the call back
progress	?? (percentage? why uint64?)

Todo:: [B, TEAM] when should a data client report progress?

Todo:: [B, TEAM] when can the TEK stop the client (after progress was not reported)?

Definition at line 1679 of file south_api.h.

◆ read_result

TEK_SA_RESULT(* tek_sa_transformation_engine::read_result) (tek_sa_data_client_handle dc, uint64_t request_id, TEK_SA_RESULT result, const struct tek_sa_read_result results[], uint32_t number_of_results)

Callback of the data client read operation.

Parameters

dc	Handle of the data client that is the source of the call
request_id	id of request to data client that triggered the call back
result	status code for read request
results	read values
number_of_results	length of results array

If the result is success, then the following constraints must hold:

The number of results MUST be equal to the number of fields requested in read_fields. The order of results MUST be the same as the order of fields in read_fields. The results array is only valid during the execution of the callback.

If the result is failure, the TEK MUST ignore the results and number_of_results parameters.

Definition at line 1704 of file south_api.h.

◆ notify_change

TEK_SA_RESULT(* tek_sa_transformation_engine::notify_change) (tek_sa_data_client_handle dc, const struct tek_sa_read_result changes[], uint32_t number_of_changes)

Callback to notify about a change of subscribed data fields.

Parameters

dc	Handle of the data client that is the source of the change
changes	changed field values
number_of_changes	length of changes array

Definition at line 1717 of file south_api.h.

◆ write_result

TEK_SA_RESULT(* tek_sa_transformation_engine::write_result) (tek_sa_data_client_handle dc, uint64_t request_id, TEK_SA_RESULT result, const struct tek_sa_write_result results[], uint32_t number_of_results)

Callback of the data client write operation.

Parameters

dc	Handle of the data client data was written to
request_id	id of write request to data client that triggered the call back
result	overall result of write operation
results	write results for each written field
number_of_results	length of results array

Definition at line 1731 of file south_api.h.

◆ call_method_result

TEK_SA_RESULT(* tek_sa_transformation_engine::call_method_result) (tek_sa_data_client_handle dc, uint64_t request_id, TEK_SA_RESULT result, const tek_sa_field_value results[], uint32_t number_of_results)

Callback of a data client method call.

Parameters

dc	Handle of the data client a method was called at
request_id	id of method call request to data client that triggered the call back
result	error/success indicator of method call
results	return values of method call, only valid for successful results
number_of_results	length of results array

Definition at line 1748 of file south_api.h.

◆ block_read_data

TEK_SA_RESULT(* tek_sa_transformation_engine::block_read_data) (tek_sa_data_client_handle dc, uint64_t request_id, TEK_SA_RESULT result, unsigned char buffer[], uint32_t buffer_length)

Callback from the data client to the TEK signaling the next data chunk of the block transfer.

Parameters

dc	The data client handle.
request_id	The request id of the block transfer.
result	The data client signals success, error, or end-of-file. Buffer may contain a last chunk when end-of-file is signalled. If an error is signalled, the data client has aborted the process and will not call this callback again for the request.
buffer	The current chunk of the file. The TEK must copy the data into it's own process.
buffer_length	The length of the chunk.

Returns: The TEK responds with success, or can abort the transfer.

Definition at line 1770 of file south_api.h.

◆ block_write_data

TEK_SA_RESULT(* tek_sa_transformation_engine::block_write_data) (tek_sa_data_client_handle dc, uint64_t request_id, unsigned char buffer[], uint32_t buffer_length, uint32_t *bytes_written)

Callback from the data client to the TEK requesting another chunk to write to the data client.

Parameters

dc	The data client handle.
request_id	The request id of the block transfer.
buffer	The buffer to write the chunk of the file. The TEK must copy the data into the buffer provided by the data client.
buffer_length	The length of the buffer in the data client.
bytes_written	The number of bytes written in the buffer by the TEK.
result	Signals valid next chunk, end-of-file, abort or error.

Returns: Success or failure code.

Definition at line 1790 of file south_api.h.

◆ block_write_result

TEK_SA_RESULT(* tek_sa_transformation_engine::block_write_result) (tek_sa_data_client_handle dc, uint64_t request_id, TEK_SA_RESULT result)

Callback from the data client to the TEK with the final result of the block transfer.

Parameters

dc	The data client handle.
request_id	The request id of the block transfer.
result	The final result.

Definition at line 1804 of file south_api.h.

The documentation for this struct was generated from the following file:

include/south_api.h

Data Fields

Detailed Description

Field Documentation

◆ register_field

◆ register_method

◆ register_event

◆ register_alarm

◆ register_enum_type

◆ register_struct_type

◆ post_event

◆ set_alarm

◆ reset_alarm

◆ log

◆ get_global_event

◆ update_capabilities

◆ read_progress

◆ read_result

◆ notify_change

◆ write_result

◆ call_method_result

◆ block_read_data

◆ block_write_data

◆ block_write_result