The interface of one instance of a data client. More...

#include <south_api.h>

Data Fields
Lifecycle functions
TEK_SA_RESULT(*	register_features )(tek_sa_data_client_handle dc)
	Register all known features of the data client. More...

TEK_SA_RESULT(*	connect )(tek_sa_data_client_handle dc)
	Connect the data client to the data source. More...

void(*	free )(tek_sa_data_client_handle dc)
	Frees the data client and releases all its resources. More...

Data client functions
TEK_SA_RESULT(*	read_fields )(tek_sa_data_client_handle dc, uint64_t request_id, const tek_sa_field_handle items_to_read[], uint32_t number_of_items, bool do_not_block)
	Function to read one or more fields from the data client. The call may be executed in a synchronous or asynchronous manner (See parameter `do_not_block`). More...

TEK_SA_RESULT(*	write_fields )(tek_sa_data_client_handle dc, uint64_t request_id, const struct tek_sa_field_write_request items_to_write[], uint32_t number_of_items, bool do_not_block)
	Function to write values to data client fields. More...

TEK_SA_RESULT(*	block_read )(const tek_sa_data_client_handle dc, uint64_t request_id, const char filepath, uint64_t offset, int64_t length, bool do_not_block, int64_t filesize)
	Starts a block transfer from the client to the TEK. More...

TEK_SA_RESULT(*	block_write )(const tek_sa_data_client_handle dc, uint64_t request_id, const char *filepath, uint64_t offset, int64_t length, bool do_not_block)
	Start a block transfer from the TEK to the data client. More...

TEK_SA_RESULT(*	subscribe )(tek_sa_data_client_handle dc, const tek_sa_field_handle items_to_subscribe[], uint32_t number_of_items)
	Subscribe to changes of one ore more data client fields. More...

TEK_SA_RESULT(*	unsubscribe )(tek_sa_data_client_handle dc, const tek_sa_field_handle items_to_unsubscribe[], uint32_t number_of_items)
	Unsubscribe to changes of one ore more data client fields. More...

TEK_SA_RESULT(*	invoke )(const tek_sa_data_client_handle dc, const tek_sa_method_handle method, uint64_t request_id, const tek_sa_field_value parameters[], const uint32_t number_of_parameters)
	Invoke a method on the data client. More...

TEK_SA_RESULT(*	acknowledge_alarm )(tek_sa_data_client_handle dc, const tek_sa_alarm_handle alarm)
	Acknowledge an alarm in the data client. More...

Data fields
tek_sa_data_client_handle	handle
	The handle that is passed as first parameter in all functions of this interface. More...

Detailed Description

The interface of one instance of a data client.

Definition at line 1057 of file south_api.h.

Field Documentation

◆ register_features

TEK_SA_RESULT(* tek_sa_data_client::register_features) (tek_sa_data_client_handle dc)

Register all known features of the data client.

Parameters

dc	data client handle features are registered for

This method is called from the TEK after the data client was created and before is will be connected. See also Initialization of a data client plugin

A data client implementation should evaluate the configuration (passed to tek_sa_data_client_plugin::data_client_new) and register all known types fields, events, methods and alarms.

A connection to the controller must not be established.

Definition at line 1075 of file south_api.h.

◆ connect

TEK_SA_RESULT(* tek_sa_data_client::connect) (tek_sa_data_client_handle dc)

Connect the data client to the data source.

This method is called from the TEK after the data client has registered ist features. See also Initialization of a data client plugin.

A data client implementation should connect to the data source and register additional features and capabilities.

If the data client can not connect to the data source it should keep trying to connect after the method call completed but it should not block.

Definition at line 1089 of file south_api.h.

◆ free

void(* tek_sa_data_client::free) (tek_sa_data_client_handle dc)

Frees the data client and releases all its resources.

Should be called by the TEK.

Definition at line 1096 of file south_api.h.

◆ read_fields

TEK_SA_RESULT(* tek_sa_data_client::read_fields) (tek_sa_data_client_handle dc, uint64_t request_id, const tek_sa_field_handle items_to_read[], uint32_t number_of_items, bool do_not_block)

Function to read one or more fields from the data client. The call may be executed in a synchronous or asynchronous manner (See parameter do_not_block).

The values of the requested fields are sent by calling the tek_sa_transformation_engine::read_result callback function. The data client must preserve the order of the fields in the results that are provided in tek_sa_transformation_engine::read_result callback.

If the time needed to retrive the values is larger then half the global timeout value a data client must call the vde_sa_tek_ap::read_progress callback function.

Parameters

dc	The handle of the data client as returned from tek_sa_data_client_plugin::data_client_new.
request_id	A unique request identifier which is created by the TEK and must be passed to call to tek_sa_transformation_engine::read_result and tek_sa_transformation_engine::read_progress.
items_to_read	An array of field handles which describes the values the data client should read. See also function tek_sa_transformation_engine::register_field.
number_of_items	The number of handles in the parameter `items_to_read`.
do_not_block	A boolean flag that, when set to true, tells the data client that it should return immediately and return the read field values later in another thread.

Returns: TEK_SA_ERR_SUCCESS when the call succeeded.; TEK_SA_ERR_NON_BLOCKING_IMPOSSIBLE if do_not_block is set to true and the called data client is not able to do nonblocking calls. The TEK will retry with do_not_block set to false; TEK_SA_ERR_OUT_OF_MEMORY when the data client can not allocate the data structures and resources to read the fields.; any other error which applies to the read function

Todo:: [B, TEAM] define error values of read function

Attention: It is mandatory that the data client does not block when called with parameter do_not_block set to true.

Usage of the Parameter do_not_block

Possible call sequences

Definition at line 1194 of file south_api.h.

◆ write_fields

TEK_SA_RESULT(* tek_sa_data_client::write_fields) (tek_sa_data_client_handle dc, uint64_t request_id, const struct tek_sa_field_write_request items_to_write[], uint32_t number_of_items, bool do_not_block)

Function to write values to data client fields.

Parameters

dc	The handle of the data client as returned from tek_sa_data_client_plugin::data_client_new.
request_id	A unique request identifier which is created by the TEK and must be passed to call to tek_sa_transformation_engine::write_result.
items_to_write	An array of field handles and their values which describes the values the data client should write.
number_of_items	The number of handles in the parameter `items_to_write`.
do_not_block	A boolean flag that, when set to true, tells the data client that it should return immediately and write the values in the background. See also Usage in `read_fields`

Todo:: [B, TEAM] should the data client call a progress function if the operation needs more time?

Definition at line 1218 of file south_api.h.

◆ block_read

TEK_SA_RESULT(* tek_sa_data_client::block_read) (const tek_sa_data_client_handle dc, uint64_t request_id, const char *filepath, uint64_t offset, int64_t length, bool do_not_block, int64_t *filesize)

Starts a block transfer from the client to the TEK.

For example, read a file from the device.

Parameters

dc	The data client handle
request_id	The request id for the TEK API callbacks
filepath	The file or address of the block to be read. The format is data client specific. The pointer must be in utf-8.
offset	The offset in the data
length	A specific length, or -1 for the whole data
do_not_block	See Usage in `read_fields`
filesize	The file size will be written by the data client, or -1 if not known at the call

Returns: An information about the success or failure of the operation.

The data is not yet passed to this method directly but sent from the data client in chunks to the tek_sa_transformation_engine::block_read_data callback.

Definition at line 1245 of file south_api.h.

◆ block_write

TEK_SA_RESULT(* tek_sa_data_client::block_write) (const tek_sa_data_client_handle dc, uint64_t request_id, const char *filepath, uint64_t offset, int64_t length, bool do_not_block)

Start a block transfer from the TEK to the data client.

Parameters

dc	The handle of the data client as returned from tek_sa_data_client_plugin::data_client_new.
request_id	A unique request identifier which is created by the TEK and must be passed to call to tek_sa_transformation_engine::block_write_result and tek_sa_transformation_engine::block_write_data.
offset	The offset in the data
length	A specific length, or -1 for the whole data
do_not_block	See Usage in `read_fields`

Returns: An information about the success or failure of the operation.

The data is not yet passed to this method directly but requested from the data client in chunks from the tek_sa_transformation_engine::block_write_data callback.

Definition at line 1272 of file south_api.h.

◆ subscribe

TEK_SA_RESULT(* tek_sa_data_client::subscribe) (tek_sa_data_client_handle dc, const tek_sa_field_handle items_to_subscribe[], uint32_t number_of_items)

Subscribe to changes of one ore more data client fields.

Parameters

dc	The handle of the data client as returned from tek_sa_data_client_plugin::data_client_new.
items_to_subscribe	The fields for which change events will be received.
number_of_items	The number of elements in the `items_to_subscribe` parameter.

Todo:: [D, TEAM] add sampling rate parameter

The subscription mechanism is very easy compared to that of the OPC UA specification. The TEK can subscribe to each field only once and all changes are signaled by a call to the tek_sa_data_transformation_engine::notify_change callback.

Definition at line 1296 of file south_api.h.

◆ unsubscribe

TEK_SA_RESULT(* tek_sa_data_client::unsubscribe) (tek_sa_data_client_handle dc, const tek_sa_field_handle items_to_unsubscribe[], uint32_t number_of_items)

Unsubscribe to changes of one ore more data client fields.

Parameters

dc	The handle of the data client as returned from tek_sa_data_client_plugin::data_client_new.
items_to_unsubscribe	The fields for which no more change events will be received.
number_of_items	The number of elements in the `items_to_unsubscribe` parameter.

Definition at line 1310 of file south_api.h.

◆ invoke

TEK_SA_RESULT(* tek_sa_data_client::invoke) (const tek_sa_data_client_handle dc, const tek_sa_method_handle method, uint64_t request_id, const tek_sa_field_value parameters[], const uint32_t number_of_parameters)

Invoke a method on the data client.

Providing this function ins optional

Parameters

dc	The handle of the data client as returned from tek_sa_data_client_plugin::data_client_new.
method	The method handle which is returned from the tek_sa_data_transformation_engine::register_method method.
request_id	A unique request identifier which is created by the TEK and must be passed to call to tek_sa_transformation_engine::block_write_result and tek_sa_transformation_engine::block_write_data.
parameters	The parameters of the method. Number and type must match the method registration.
number_of_parameters	The number of parameters in the `parameters` array.

The outcome of the message call is returned in the tek_sa_transformation_engine::call_method_result callback.

Definition at line 1337 of file south_api.h.

◆ acknowledge_alarm

TEK_SA_RESULT(* tek_sa_data_client::acknowledge_alarm) (tek_sa_data_client_handle dc, const tek_sa_alarm_handle alarm)

Acknowledge an alarm in the data client.

Parameters

dc	The handle of the data client as returned from tek_sa_data_client_plugin::data_client_new.
alarm	An alarm handle which is returned from the method tek_sa_transformation_engine::register_alarm.

Called by TEK to signal triggered alarm has acknowledged by TEK consumer. The alarm may or may not be raised before with a call to tek_sa_transformation_engine::set_alarm. When the alarm condition is not true anymore, then the data client implementation has to reset the alarm and call tek_sa_transformation_engine::reset_alarm

Definition at line 1358 of file south_api.h.

◆ handle

tek_sa_data_client_handle tek_sa_data_client::handle

The handle that is passed as first parameter in all functions of this interface.

Definition at line 1369 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_features

◆ connect

◆ free

◆ read_fields

◆ write_fields

◆ block_read

◆ block_write

◆ subscribe

◆ unsubscribe

◆ invoke

◆ acknowledge_alarm

◆ handle