va_datalink.h🔗

#include <va_datalink.h>

Defines

VA_REGISTER_DATALINK_DRIVER(IDENTIFIER)🔗

Creates a function that registers the shared library as a data link driver with the given IDENTIFIER, which must be unique within the enclosing component.

IDENTIFIER should follow class name conventions: start with a capital letter and capitalize each word. For example, “AcmePlcDriver”.

Typedefs

typedef void (*va_datalink_callback)(void*)🔗: Function signature for the call-back function that will be called when the value of a variable in a slave device is set by a master device.

Enums

enum va_datalink_dev_flag🔗

Data link device driver capability flags.

A bit mask of these flags is returned as the “flags” configuration variable of a device.

Values:

enumerator va_datalink_dev_master🔗

The device driver works as a master device.

It writes and reads data from a slave device using a communication bus. A master driver may also be able to receive change notification signals if the slave device and the underlying protocol supports them.

enumerator va_datalink_dev_slave🔗

The device driver works as a slave device.

A slave device listens to a communication bus and either returns the values of local variables or assigns their values based on the incoming requests.

enumerator va_datalink_dev_fixed_vars🔗

Set if the driver implementation has a fixed set of variables and cannot create new ones.

In this case va_datalink_var_create never makes changes to the actual device but merely returns a reference to an existing variable and fails if the named variable does not exist.

enum va_datalink_batch_action🔗

Ways of finishing a batch write.

Values:

enumerator va_datalink_batch_commit🔗: Write the values of all changed variables at once.

enumerator va_datalink_batch_rollback🔗: Restore all variables to their original values.

Functions

void *va_datalink_dev_list(void)🔗

Returns a list of data link devices that are detected by this driver.

Use the returned handle as a parameter to va_datalink_handle_next to loop through available devices.

Return: A handle to a list of devices.
Note: This is an optional function.

void *va_datalink_dev_create(const va_string *device_address)🔗

Creates a connection to the device identified by an implementation-specific device address.

Return

A handle to a device or NULL if the call fails. In a typical implementation, the handle is a pointer to a heap-allocated structure that stores the state of a device.

Parameters

device_address: An implementation-specific way of identifying a data link device. Can be e.g. a network URI. The device address can contain encoded parameters, but devices may also support setting configuration parameters via va_datalink_config_get and va_datalink_var_write.

int32_t va_datalink_dev_open(void *dev_handle)🔗

Opens a connection to a data link device.

The function fails if connection cannot be established within the time-out set by the “timeout” configuration variable.

Return: Zero on success and non-zero on failure.

int32_t va_datalink_dev_close(void *dev_handle)🔗

Closes connection to a data link device.

After closing the connection, the device can be configured and opened again.

Return: Zero on success and non-zero on failure.

void *va_datalink_config_list(void *dev_handle)🔗

Returns a list of configuration values supported by the given device.

Return: A list handle on success, NULL on failure.

void *va_datalink_config_get(void *dev_handle, const va_string *name)🔗

Returns a variable handle to the configuration variable with the specified name in the device identified by the given dev_handle.

The returned handle needs to be destroyed with va_datalink_handle_destroy() when no longer used.

Return

A variable handle on success, NULL on failure.

Parameters

dev_handle: A device handle.
name: The name of the configuration variable.

int32_t va_datalink_var_meta_set(void *handle, int32_t type, const va_string *name, ...)🔗

Sets a variable meta value.

Note that in most cases the variable meta values are not writable, in which case this method returns failure.

Return

Zero on success and non-zero on failure.

Parameters

handle: A variable handle.
type: The data type of the value to set, one of va_type_id.
name: The name of the meta value.
...: Type-dependent parameters.

int32_t va_datalink_var_meta_get(void *handle, int32_t type, const va_string *name, ...)🔗

Reads a variable meta value.

void* pVar = va_datalink_var_create(dev, va_string_id, "string_var");
int32_t iType;
va_datalink_meta_get(pVar, int32_t_id, "type", &iType);

Parameters

handle: A variable handle.
type: The expected data type of the meta value to retrieve, one of va_type_id.
name: The name of the meta value.
...: Type-dependent parameters.

int32_t va_datalink_handle_destroy(void *handle)🔗

Destroys a handle.

Subsequent operations on the handle result in undefined behavior. The memory allocated by handle will be freed even if the handle can not be finalized cleanly.

If the handle represents a list, the implementation can decide whether the handles in the list are destroyed or not. It must guarantee that the handles in a list are valid at least until the list is passed to this function.

Return

Zero on success and non-zero on failure.

Parameters

handle: A device, variable or list handle. It is safe to destroy a NULL handle.

void *va_datalink_handle_next(void *list_handle)🔗

Returns the next handle in a handle list.

// Print the addresses of all detected devices.
char bfr[128];
void* lst = va_datalink_dev_list();
void* dev;
while ((dev = va_datalink_handle_next(lst)))
  {
    va_datalink_config_get(dev, va_string_id, "address", bfr, 128);
    printf("%s\n", bfr);
  }
va_datalink_handle_destroy(lst);

Return

The next handle in list or NULL if there are no more handles. The returned handles are valid until the returned list is destroyed using va_datalink_handle_destroy.

Parameters

list_handle: A list handle returned by va_datalink_dev_list or va_datalink_var_list.

void *va_datalink_var_list(void *dev_handle)🔗

Returns a list of variables known to the given device.

This function fails if called on a device that hasn’t been opened.

Return: A handle to a list of variables.
Note: This is an optional function.

void *va_datalink_var_create(void *dev_handle, int32_t type, const va_string *var_name)🔗

Creates a variable.

Depending on the driver implementation, creating a variable may or may not actually create a new variable on the device. For example, an SQL database driver may be able to create new columns in a database table. Slave devices usually allocate local storage for the variable, but may also provide a fixed set of variables. If the variable set is fixed, the driver should return va_datalink_dev_fixed_vars in its flags (see va_datalink_config_get).

Return

A handle to a variable or NULL if the function failed. As the handle, a typical implementation would use a pointer to a heap-allocated structure that contains dev_handle, the type of the variable and possibly local storage for the value of the variable.

Parameters

dev_handle: A device handle returned by va_datalink_dev_create.
type: The type of the variable, one of va_type_id.
var_name: An implementation-specific character string that identifies the variable. The variable name can be e.g. a PLC tag name or a database column name.

int32_t va_datalink_var_callback_set(void *var_handle, va_datalink_callback callback, void *user_data)🔗

Assigns a call-back function to a local variable.

The call-back function will be invoked if the driver is in slave mode and a master device writes to the variable. Some drivers may also support assigning call-back functions to variables in master mode.

void dl_cb(void* var)
{
  int32_t value;
  va_datalink_var_read(var, int32_t_id, &value);
  printf("Received %d.\n", value);
}

void* dev = va_datalink_dev_create("demoslave", 1000);
void* var = va_datalink_var_create(dev, int32_t_id, "demovariable");
va_datalink_var_callback_set(var, &dl_cb, var);

Return

Zero on success and non-zero on failure.

Parameters

var_handle: A variable handle.
callback: A pointer to a call-back function to invoke when the value of the variable is set by an external source. The callback is invoked always when the value is set, even if the value does not change. Set the callback to NULL to remove it. The callback is invoked in the context of the thread that changed the value of the variable.
user_data: A pointer to be passed to the call-back function when invoked. A typical choice is to pass var_handle as the user data.

destroy any variable handle referring to the same variable var_handle refers to. Doing so will invoke undefined behavior.
throw exceptions.
wait for another thread that may access the same datalink device, as this may cause a deadlock for certain driver implementations.

Note: The call-back function MUST NOT

Attempting to lock mutexes in the call-back function is dangerous and discouraged. If a mutex is necessary, you need to make sure not to lock any mutex that may be locked simultaneously while accessing the same datalink variable. That may cause a “dual

mutex deadlock”: callback thread is keeping the variable mutex locked during the callback and other thread is keeping the mutex needed by the callback while trying to acquire the variable mutex.

Note: This function does not need to be implemented by master device drivers.

int32_t va_datalink_var_read(void *var_handle, int32_t type, ...)🔗

Reads the value of a variable.

In slave mode, returns the local value of the variable. In master mode, sends a read request to a slave device and returns the result.

int32_t i;
va_datalink_var_read(pVar, va_int32_id, &i);

Return

Zero on success and non-zero on failure.

Parameters

var_handle: A variable handle.
type: The excepted type, one of va_type_id. If the type of the variable is not compatible with type, the function fails.
...: Type-dependent parameters.

int32_t va_datalink_var_write(void *var_handle, int32_t type, ...)🔗

Writes the value of a variable.

In slave mode, assigns the value to a local variable without calling any call-back functions. In master mode, sends a write request to a slave device.

void* pVar = va_datalink_var_create(dev, va_string_id, "string_var");
int32_t iSuccess = va_datalink_var_write(pVar, va_string_id, "string_value");

Return

Zero on success and non-zero on failure.

Parameters

var_handle: A variable handle.
type: The excepted type, one of va_type_id. If the type of the variable is not compatible with type, the function fails.
...: Type-dependent parameters.

int32_t va_datalink_batch_start(void *dev_handle)🔗

Starts a batch of variable writes.

If batch changes are supported, the driver caches variable writes until va_datalink_batch_finish is called and then sets all variables at once. On devices that support batch processing, this ensures that no incomplete state is observable while setting multiple variables.

A typical example is an SQL database driver that inserts a row of related values to a table. Setting one entry at a time would be really slow and even impossible in some cases.

Note

This is an optional function.

Parameters

dev_handle: A handle to an open device.

int32_t va_datalink_batch_finish(void *dev_handle, va_datalink_batch_action action)🔗

Finishes a batch of variable writes.

Note

This is an optional function.

Parameters

dev_handle: A handle to an open device.
action: The way the batch is finished.

va_string *va_datalink_error(void *dev_handle)🔗

Returns the last error message.

Return

A pointer to a va_string or NULL if there is no error. It is the caller’s responsibility to deallocate the string with va_string_free.

Parameters

dev_handle: A handle to an open device.