|
Lucon SDK 1.0.7
|
The SDK is shipped as a shared library. All declarations are available from a single header file:
Link your program against the lucon.dll. It contains statically linked dependencies as listed in dependencies.
The API consists of following main abstractions:
The abstractions of the API are provided by means of handles which are returned by factory functions. After their last usage, all handles must be released with the function LUCON_FreeHandle
The API design destinguishes two kinds of function signatures regarding the indication of success:
The result status of the most recent API call for each thread is internally saved in thread-local storage (except for calls to LUCON_GetLastApiResult).
After failed API calls a descriptive error message can be retreived by calling LUCON_GetLastApiResult
Functions which are copying output strings into user-provided buffers will return LUCON_ERR_BUFFER_TOO_SMALL if the value exceeds the provided buffersize. Users are encouraged to retry the call with a larger string buffer, e.g. doubling the size after each call.
For each phsyical Lucon one single Connection shall be created, otherwise messages from the device to the controller may be lost.
The library internally serializes shared accesses to the connection, for example when using multiple Channels on different threads. For this reason concurrent access to one Lucon from multiple threads is allowed.
The mutation of Lucon parameters is always transient, if not stated differently: The device holds the active parameters in volatile memory. At the restart of a device, its presisted settings are restored. To persist the current set of parameters, users must explicitly call the respective method. See LUCON_DeviceSavePermanently and LUCON_ChannelSavePermanently.
The API provides two distinct interfaces to control connectivity:
Users can choose either one of them according to their needs but should not mix their usage.
As noted in the respective documentation, the difference is that LUCON_DeviceConnect involves a handshake with the hardware to check responsiveness, while LUCON_ConnectionClose only cares about initialization of the host resources.
In both cases users may check and monitor the responsivens of the device using the LUCON_DeviceSetConnectedChangedCallback, and LUCON_DeviceIsConnected. The event callback is internally uses a periodic beacon, if no traffic is generated by users. Its handshake will also be visible, if users monitor the communication with LUCON_ConnectionSetReadCallback and LUCON_ConnectionSetWriteCallback events.
With LUCON_ConnectionSetHintCallback users can register to receive hint messages from the device: Lucon2 controllers will send such messages to the host to keep him informed for example about errors during operation. This includes errors during autonomous input-triggered operation of the controller. This feature might help you for example to keep track of hardware failures.