UNICENS supports to access multiple instances within one process space. One UNICENS API instance is dedicated to one INIC the associated network. Hence, it is possible to deal with multiple networks within one process space. The maximum number of UNICENS API instances must be configured in ucs_cfg.h
.
The following definition configures UNICENS to be used with 2 INICs.
Accordingly UNICENS can provide 2 API instances that can be retrieved by calling Ucs_CreateInstance(). The retrieved instance remains valid until the process ends. There is no need to return or re-create an already retrieved instance. The following code shows how to retrieve one API instance.
The application has to prepare a configuration structure in order to initialize UNICENS. Therefore, it has to provide a Ucs_InitData_t variable. It is recommended to set the variable to default values by calling Ucs_SetDefaultConfig(). After that the application shall set specific attributes of the variable. The function Ucs_SetDefaultConfig() can be called at any time and is not bound up with a certain API instance.
After the function returns, the application has to setup the configuration settings. The following section shows an example configuration.
By assigning init_data.user_ptr and init_data.lld.lld_user_ptr the application is able assign references of own objects to a certain UNICENS API instance. E.g., when driving 2 API instances the application can assign 2 different LLD objects. When UNICENS invokes LLD callback functions then one argument will provide the assigned lld_user_ptr. The application can simply forward the call to the actual LLD object.
The callback general.error_fptr()
is called if a general error occurs. The callback must adhere to function signature Ucs_ErrorCb_t. If a general error occurs the application must trigger a re-initialization of UNICENS. A simple example implementation is shown below.
general.error_fptr()
!The UNICENS timer management requires a timer tick in milliseconds that is gathered via the callback general.get_tick_count_fptr()
. The callback must adhere to function signature Ucs_GetTickCountCb_t. An example implementation for a Windows platform is shown below.
The function Ucs_Init() must be called by the application to initialize one UNICENS API instance. library. The first argument is the reference to the API instance. The second argument is the reference to the initialization structure. The third argument is optional and can provide the reference to a result callback function. It is highly recommended to use the result callback to be able to handle possible errors during the initialization.