Lucon SDK 1.0.7
Loading...
Searching...
No Matches
Functions related to a Lucon Connection.

Topics

 Factory functions
 Communication monitoring

Functions

LuconResult LUCON_ConnectionSetTimeouts (LuconHandle handle, uint32_t timeout)
 Set custom timeouts for awaiting answers from the device to sent commands. SetTimeouts works only while the connection is closed!
LuconResult LUCON_ConnectionSetHintCallback (LuconHandle handle, const LuconHintCallback callback)
 Set a function to be called, when a hint message is received from the Lucon device.
LuconResult LUCON_ConnectionOpen (LuconHandle handle)
 Open the connection to the device. Once opened, the connection listens for incoming messages and may be used for communication.
LuconResult LUCON_ConnectionClose (LuconHandle handle)
 Close a opened connection.
LuconResult LUCON_ConnectionIsOpened (LuconHandle handle, int32_t *isOpened)
 Checks whether the connection is opened and ready for communication.
LuconResult LUCON_ConnectionSendCommand (LuconHandle handle, const char *const cstring, const char *strbuf, size_t buf_len)
 Send the given string over the connection and checks for a device response.
LuconResult LUCON_ConnectionGetInfo (LuconHandle handle, const char *result, size_t buf_len)
 Write a zero-terminated C string with a description of a connection into the result buffer.

Detailed Description

Function Documentation

◆ LUCON_ConnectionClose()

LuconResult LUCON_ConnectionClose ( LuconHandle handle)
extern

Close a opened connection.

Parameters
handleA handle to a connection.
Returns

◆ LUCON_ConnectionGetInfo()

LuconResult LUCON_ConnectionGetInfo ( LuconHandle handle,
const char * result,
size_t buf_len )
extern

Write a zero-terminated C string with a description of a connection into the result buffer.

If the provided output buffer is smaller than the full description it will be filled with a truncated description and proper zero-termination.

Parameters
handleA handle to a connection.
resultoutput string buffer, receiving the description.
buf_lenthe usable length of result buffer.
Returns

◆ LUCON_ConnectionIsOpened()

LuconResult LUCON_ConnectionIsOpened ( LuconHandle handle,
int32_t * isOpened )
extern

Checks whether the connection is opened and ready for communication.

Remarks
This does not(!) check whether the device is responsive!
See also
LUCON_DeviceIsConnected
Parameters
handleA handle to a connection.
isOpenedA non-null pointer receiving the result.
Returns

◆ LUCON_ConnectionOpen()

LuconResult LUCON_ConnectionOpen ( LuconHandle handle)
extern

Open the connection to the device. Once opened, the connection listens for incoming messages and may be used for communication.

The function will always succeed, if the configuration of the connection is valid and the the resources are available. It does not(!) check, whether the device is actually responding.

Parameters
handleA handle to a connection
Returns

◆ LUCON_ConnectionSendCommand()

LuconResult LUCON_ConnectionSendCommand ( LuconHandle handle,
const char *const cstring,
const char * strbuf,
size_t buf_len )
extern

Send the given string over the connection and checks for a device response.

If not present, the protocols terminating character sequence is appended internally before sending. Users must take care of the protocol, e.g. include properly formatted module address. If the device reports any error, the command will be resent multiple times until the tiemout is hit or a success received. If the device does not report a success, an error LuconResult is received. See LUCON_GetLastApiResult

Parameters
handleA handle to a connection
cstringA zero-terminated ASCII string to be sent over the connection. Example: "S01V|15000"
strbufoutput string buffer, receiving the device response.
buf_lenthe usable length of result buffer.
Returns

◆ LUCON_ConnectionSetHintCallback()

LuconResult LUCON_ConnectionSetHintCallback ( LuconHandle handle,
const LuconHintCallback callback )
extern

Set a function to be called, when a hint message is received from the Lucon device.

Hint messages may be sent by a Lucon at any time, independent of any hots request. They may inform the host about errors on the device or contain information about its internal processing state. When such a hint is received by the connection, it will call the set callback function.

Remarks
The set function is called from the background thread which is listening for and processing incoming device messages. The callbacks execution will delay message processing and might cause timeouts.
Parameters
handleA handle to a connection
callbackA pointer to the callback function. Pass NULL to reset a previously set callback.
Returns

◆ LUCON_ConnectionSetTimeouts()

LuconResult LUCON_ConnectionSetTimeouts ( LuconHandle handle,
uint32_t timeout )
extern

Set custom timeouts for awaiting answers from the device to sent commands. SetTimeouts works only while the connection is closed!

The Lucon protocol specifies that a device will answer successful host commands with distinct responses. After sending a command to the device, the API will wait until it receives a response or times out.

Parameters
handleA handle to a connection
timeoutThe time limit in milliseconds to wait for device responses
Returns