Rodbus-FFI  0.1.0
Idiomatic C API to the Rodbus crate via Rust FFI
Classes | Macros | Typedefs | Enumerations | Functions
rodbus.h File Reference
#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>
#include "prelude.h"

Go to the source code of this file.

Classes

struct  Session
 Struct that bundles together the types needed to make requests on a channel. More...
 
struct  RuntimeConfig
 Optional non-default configuration of the Tokio runtime. More...
 
struct  Result
 Type that describes the success or failure of an operation. More...
 

Macros

#define MAX_READ_COILS_COUNT   2000
 
#define MAX_READ_REGISTERS_COUNT   125
 
#define MAX_WRITE_COILS_COUNT   1968
 
#define MAX_WRITE_REGISTERS_COUNT   123
 

Typedefs

typedef uint8_t Exception
 
typedef uint8_t Level
 
typedef uint8_t Status
 
typedef struct Session Session
 Struct that bundles together the types needed to make requests on a channel. More...
 
typedef struct RuntimeConfig RuntimeConfig
 Optional non-default configuration of the Tokio runtime. More...
 
typedef struct Result Result
 Type that describes the success or failure of an operation. More...
 

Enumerations

enum  Exception {
  EXCEPTION_ILLEGAL_FUNCTION = 1, EXCEPTION_ILLEGAL_DATA_ADDRESS = 2, EXCEPTION_ILLEGAL_DATA_VALUE = 3, EXCEPTION_SERVER_DEVICE_FAILURE = 4,
  EXCEPTION_ACKNOWLEDGE = 5, EXCEPTION_SERVER_DEVICE_BUSY = 6, EXCEPTION_MEMORY_PARITY_ERROR = 8, EXCEPTION_GATEWAY_PATH_UNAVAILABLE = 10,
  EXCEPTION_GATEWAY_TARGET_DEVICE_FAILED_TO_RESPOND = 11
}
 
enum  Level {
  LEVEL_ERROR, LEVEL_WARN, LEVEL_INFO, LEVEL_DEBUG,
  LEVEL_TRACE
}
 
enum  Status {
  STATUS_OK, STATUS_SHUTDOWN, STATUS_NO_CONNECTION, STATUS_RESPONSE_TIMEOUT,
  STATUS_BAD_REQUEST, STATUS_BAD_RESPONSE, STATUS_IOERROR, STATUS_BAD_FRAMING,
  STATUS_EXCEPTION, STATUS_INTERNAL_ERROR
}
 

Functions

Session build_session (Runtime *runtime, Channel *channel, uint8_t unit_id, uint32_t timeout_ms)
 Convenience function to build a session struct. More...
 
Channelcreate_tcp_client (Runtime *runtime, const char *address, uint16_t max_queued_requests)
 Create an instance of a TCP client channel. More...
 
Runtimecreate_threaded_runtime (const RuntimeConfig *config)
 create an instance of the multi-threaded work-stealing Tokio runtime More...
 
void destroy_channel (Channel *channel)
 Destroy a previously created channel instance. More...
 
void destroy_runtime (Runtime *runtime)
 Destroy a previously created runtime instance. More...
 
Result read_coils (Session *session, uint16_t start, uint16_t count, bool *output)
 perform a blocking operation to read coils More...
 
void read_coils_cb (Session *session, uint16_t start, uint16_t count, void(*callback)(Result, const bool *, uint16_t, void *), void *user_data)
 perform a non-blocking operation to read coils More...
 
Result read_discrete_inputs (Session *session, uint16_t start, uint16_t count, bool *output)
 perform a blocking operation to read discrete inputs More...
 
void read_discrete_inputs_cb (Session *session, uint16_t start, uint16_t count, void(*callback)(Result, const bool *, uint16_t, void *), void *user_data)
 perform a non-blocking operation to read discrete inputs More...
 
Result read_holding_registers (Session *session, uint16_t start, uint16_t count, uint16_t *output)
 perform a blocking operation to read holding registers More...
 
void read_holding_registers_cb (Session *session, uint16_t start, uint16_t count, void(*callback)(Result, const uint16_t *, uint16_t, void *), void *user_data)
 perform a non-blocking operation to read holding registers More...
 
Result read_input_registers (Session *session, uint16_t start, uint16_t count, uint16_t *output)
 perform a blocking operation to read input registers More...
 
void read_input_registers_cb (Session *session, uint16_t start, uint16_t count, void(*callback)(Result, const uint16_t *, uint16_t, void *), void *user_data)
 perform a non-blocking operation to read input registers More...
 
bool set_log_callback (void(*callback)(Level level, const char *message))
 set the callback to invoke when an enabled level is logged More...
 
void set_max_level (Level level)
 set the maximum log level More...
 
Result write_multiple_coils (Session *session, uint16_t start, const bool *values, uint16_t count)
 perform a blocking operation to write multiple coils More...
 
void write_multiple_coils_cb (Session *session, uint16_t start, const bool *values, uint16_t count, void(*callback)(Result, void *), void *user_data)
 perform a non-blocking operation to write multiple coils More...
 
Result write_multiple_registers (Session *session, uint16_t start, const uint16_t *values, uint16_t count)
 perform a blocking operation to write multiple registers More...
 
void write_multiple_registers_cb (Session *session, uint16_t start, const uint16_t *values, uint16_t count, void(*callback)(Result, void *), void *user_data)
 perform a non-blocking operation to write multiple registers More...
 
Result write_single_coil (Session *session, uint16_t index, bool value)
 perform a blocking operation to write a single coil More...
 
void write_single_coil_cb (Session *session, uint16_t index, bool value, void(*callback)(Result, void *), void *user_data)
 perform a non-blocking operation to write a single coil More...
 
Result write_single_register (Session *session, uint16_t index, uint16_t value)
 perform a blocking operation to write a single register More...
 
void write_single_register_cb (Session *session, uint16_t index, uint16_t value, void(*callback)(Result, void *), void *user_data)
 perform a non-blocking operation to write a single register More...
 

Macro Definition Documentation

◆ MAX_READ_COILS_COUNT

#define MAX_READ_COILS_COUNT   2000

◆ MAX_READ_REGISTERS_COUNT

#define MAX_READ_REGISTERS_COUNT   125

◆ MAX_WRITE_COILS_COUNT

#define MAX_WRITE_COILS_COUNT   1968

◆ MAX_WRITE_REGISTERS_COUNT

#define MAX_WRITE_REGISTERS_COUNT   123

Typedef Documentation

◆ Exception

typedef uint8_t Exception

◆ Level

typedef uint8_t Level

◆ Result

typedef struct Result Result

Type that describes the success or failure of an operation.

◆ RuntimeConfig

typedef struct RuntimeConfig RuntimeConfig

Optional non-default configuration of the Tokio runtime.

◆ Session

typedef struct Session Session

Struct that bundles together the types needed to make requests on a channel.

◆ Status

typedef uint8_t Status

Enumeration Type Documentation

◆ Exception

enum Exception

Exception values from the Modbus specification

Enumerator
EXCEPTION_ILLEGAL_FUNCTION 

The function code received in the query is not an allowable action for the server

EXCEPTION_ILLEGAL_DATA_ADDRESS 

The data address received in the query is not an allowable address for the server

EXCEPTION_ILLEGAL_DATA_VALUE 

A value contained in the request is not an allowable value for server

EXCEPTION_SERVER_DEVICE_FAILURE 

An unrecoverable error occurred while the server was attempting to perform the requested action

EXCEPTION_ACKNOWLEDGE 

Specialized use in conjunction with programming commands The server has accepted the request and is processing it

EXCEPTION_SERVER_DEVICE_BUSY 

Specialized use in conjunction with programming commands The server is engaged in processing a long-duration program command, try again later

EXCEPTION_MEMORY_PARITY_ERROR 

Specialized use in conjunction with function codes 20 and 21 and reference type 6, to indicate that the extended file area failed to pass a consistency check. The server attempted to read a record file, but detected a parity error in the memory

EXCEPTION_GATEWAY_PATH_UNAVAILABLE 

Specialized use in conjunction with gateways, indicates that the gateway was unable to allocate an internal communication path from the input port to the output port for processing the request. Usually means that the gateway is mis-configured or overloaded

EXCEPTION_GATEWAY_TARGET_DEVICE_FAILED_TO_RESPOND 

Specialized use in conjunction with gateways, indicates that no response was obtained from the target device. Usually means that the device is not present on the network.

◆ Level

enum Level

Levels of logging

Enumerator
LEVEL_ERROR 
LEVEL_WARN 
LEVEL_INFO 
LEVEL_DEBUG 
LEVEL_TRACE 

◆ Status

enum Status

Status returned during synchronous and asynchronous API calls

Enumerator
STATUS_OK 

The operation was successful and any return value may be used

STATUS_SHUTDOWN 

The channel was shutdown before the operation could complete

STATUS_NO_CONNECTION 

No connection could be made to the server

STATUS_RESPONSE_TIMEOUT 

No valid response was received before the timeout

STATUS_BAD_REQUEST 

The request was invalid

STATUS_BAD_RESPONSE 

The response was improperly formatted

STATUS_IOERROR 

An I/O error occurred on the underlying stream while performing the request

STATUS_BAD_FRAMING 

A framing error was detected while performing the request

STATUS_EXCEPTION 

The server returned an exception code (see separate exception value)

STATUS_INTERNAL_ERROR 

An unspecified internal error occurred while performing the request

Function Documentation

◆ build_session()

Session build_session ( Runtime runtime,
Channel channel,
uint8_t  unit_id,
uint32_t  timeout_ms 
)

Convenience function to build a session struct.

This function does not allocate and is merely a helper function create the Session struct.

Parameters
runtimepointer to the Runtime that will be used to make requests on the channel
channelpointer to the Channel on which requests associated with the built Session will be made
unit_idModbus unit identifier of the server
timeout_mstimeout in milliseconds for any requests made via this session object
Returns
built Session struct ready for use with the Modbus request functions

◆ create_tcp_client()

Channel* create_tcp_client ( Runtime runtime,
const char *  address,
uint16_t  max_queued_requests 
)

Create an instance of a TCP client channel.

This function allocates an opaque struct which must be later destroyed using destroy_channel()

Parameters
runtimepointer to the Runtime that will be used to run the channel task
addressstring representation on an IPv4 or IPv6 address and port, e.g. "127.0.0.1:502"
max_queued_requestsMaximum number of queued requests that will be accepted before back-pressure (blocking) is applied
Returns
pointer to the channel or NULL if the address parameter cannot be parsed
Warning
destroying the underlying runtime does NOT automatically destroy a Channel on the runtime and destroy_channel() must always be used to free the memory

◆ create_threaded_runtime()

Runtime* create_threaded_runtime ( const RuntimeConfig config)

create an instance of the multi-threaded work-stealing Tokio runtime

This instance is typically created at the beginning of your program and destroyed using destroy_runtime() before your program exits.

Parameters
configOptional configuration of the runtime. If "config" is NULL, default settings are applied
Returns
An instance of the runtime or NULL if it cannot be created for some reason

◆ destroy_channel()

void destroy_channel ( Channel channel)

Destroy a previously created channel instance.

This operation stops channel task execution. Any pending asynchronous callbacks may not complete, and no further Modbus requests on this channel should be made after this call.

Parameters
channelChannel to stop and destroy
Note
This function checks for NULL and is a NOP in this case

◆ destroy_runtime()

void destroy_runtime ( Runtime runtime)

Destroy a previously created runtime instance.

This operation is typically performed just before program exit. It blocks until the runtime stops and all operations are canceled. Any pending asynchronous callbacks may not complete, and no further Modbus requests can be made after this call using this runtime and any channels or sessions created from it

Parameters
runtimeRuntime to stop and destroy
Note
This function checks for NULL and is a NOP in this case

◆ read_coils()

Result read_coils ( Session session,
uint16_t  start,
uint16_t  count,
bool *  output 
)

perform a blocking operation to read coils

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
startstarting address for the operation
countcount of items for the operation
outputbuffer that is written on success.
Returns
Result struct describing the success or failure of the operation
Note
This function is thread-safe
Warning
The output buffer must be at least as large as count, otherwise a buffer overrun will occur

◆ read_coils_cb()

void read_coils_cb ( Session session,
uint16_t  start,
uint16_t  count,
void(*)(Result, const bool *, uint16_t, void *)  callback,
void *  user_data 
)

perform a non-blocking operation to read coils

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
startstarting address for the operation
countcount of items for the operation
callbackcallback function to invoke when the operation completes
user_datapointer to optional user data providing context to the callback
Note
This function is thread-safe

◆ read_discrete_inputs()

Result read_discrete_inputs ( Session session,
uint16_t  start,
uint16_t  count,
bool *  output 
)

perform a blocking operation to read discrete inputs

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
startstarting address for the operation
countcount of items for the operation
outputbuffer that is written on success.
Returns
Result struct describing the success or failure of the operation
Note
This function is thread-safe
Warning
The output buffer must be at least as large as count, otherwise a buffer overrun will occur

◆ read_discrete_inputs_cb()

void read_discrete_inputs_cb ( Session session,
uint16_t  start,
uint16_t  count,
void(*)(Result, const bool *, uint16_t, void *)  callback,
void *  user_data 
)

perform a non-blocking operation to read discrete inputs

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
startstarting address for the operation
countcount of items for the operation
callbackcallback function to invoke when the operation completes
user_datapointer to optional user data providing context to the callback
Note
This function is thread-safe

◆ read_holding_registers()

Result read_holding_registers ( Session session,
uint16_t  start,
uint16_t  count,
uint16_t *  output 
)

perform a blocking operation to read holding registers

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
startstarting address for the operation
countcount of items for the operation
outputbuffer that is written on success.
Returns
Result struct describing the success or failure of the operation
Note
This function is thread-safe
Warning
The output buffer must be at least as large as count, otherwise a buffer overrun will occur

◆ read_holding_registers_cb()

void read_holding_registers_cb ( Session session,
uint16_t  start,
uint16_t  count,
void(*)(Result, const uint16_t *, uint16_t, void *)  callback,
void *  user_data 
)

perform a non-blocking operation to read holding registers

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
startstarting address for the operation
countcount of items for the operation
callbackcallback function to invoke when the operation completes
user_datapointer to optional user data providing context to the callback
Note
This function is thread-safe

◆ read_input_registers()

Result read_input_registers ( Session session,
uint16_t  start,
uint16_t  count,
uint16_t *  output 
)

perform a blocking operation to read input registers

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
startstarting address for the operation
countcount of items for the operation
outputbuffer that is written on success.
Returns
Result struct describing the success or failure of the operation
Note
This function is thread-safe
Warning
The output buffer must be at least as large as count, otherwise a buffer overrun will occur

◆ read_input_registers_cb()

void read_input_registers_cb ( Session session,
uint16_t  start,
uint16_t  count,
void(*)(Result, const uint16_t *, uint16_t, void *)  callback,
void *  user_data 
)

perform a non-blocking operation to read input registers

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
startstarting address for the operation
countcount of items for the operation
callbackcallback function to invoke when the operation completes
user_datapointer to optional user data providing context to the callback
Note
This function is thread-safe

◆ set_log_callback()

bool set_log_callback ( void(*)(Level level, const char *message)  callback)

set the callback to invoke when an enabled level is logged

Parameters
callbackCallback function to invoke
Returns
true if the callback was successfully set
Warning
this call will only succeed the first time it is made!

◆ set_max_level()

void set_max_level ( Level  level)

set the maximum log level

Parameters
levelmaximum level at which messages will be logged

◆ write_multiple_coils()

Result write_multiple_coils ( Session session,
uint16_t  start,
const bool *  values,
uint16_t  count 
)

perform a blocking operation to write multiple coils

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
startstarting address of the values
valuesarray of values to write
countof values to write
Returns
Result struct describing the success or failure of the operation
Note
This function is thread-safe
Warning
The "values" array must contain at least "count" items or the function will read past the end of the buffer

◆ write_multiple_coils_cb()

void write_multiple_coils_cb ( Session session,
uint16_t  start,
const bool *  values,
uint16_t  count,
void(*)(Result, void *)  callback,
void *  user_data 
)

perform a non-blocking operation to write multiple coils

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
startstarting address of the values
valuesarray of values to write
countcount of values to write
callbackcallback function to invoke when the operation completes
user_datapointer to optional user data data providing context to the callback
Note
This function is thread-safe
Warning
"values" must contain at least "count" items or the function will read past the end of the buffer

◆ write_multiple_registers()

Result write_multiple_registers ( Session session,
uint16_t  start,
const uint16_t *  values,
uint16_t  count 
)

perform a blocking operation to write multiple registers

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
startstarting address of the values
valuesarray of values to write
countof values to write
Returns
Result struct describing the success or failure of the operation
Note
This function is thread-safe
Warning
The "values" array must contain at least "count" items or the function will read past the end of the buffer

◆ write_multiple_registers_cb()

void write_multiple_registers_cb ( Session session,
uint16_t  start,
const uint16_t *  values,
uint16_t  count,
void(*)(Result, void *)  callback,
void *  user_data 
)

perform a non-blocking operation to write multiple registers

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
startstarting address of the values
valuesarray of values to write
countcount of values to write
callbackcallback function to invoke when the operation completes
user_datapointer to optional user data data providing context to the callback
Note
This function is thread-safe
Warning
"values" must contain at least "count" items or the function will read past the end of the buffer

◆ write_single_coil()

Result write_single_coil ( Session session,
uint16_t  index,
bool  value 
)

perform a blocking operation to write a single coil

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
indexaddress of the value
valuevalue to write
Returns
Result struct describing the success or failure of the operation
Note
This function is thread-safe

◆ write_single_coil_cb()

void write_single_coil_cb ( Session session,
uint16_t  index,
bool  value,
void(*)(Result, void *)  callback,
void *  user_data 
)

perform a non-blocking operation to write a single coil

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
indexaddress of the value
valuevalue to write
callbackcallback function to invoke when the operation completes
user_datapointer to optional user data data providing context to the callback
Note
This function is thread-safe

◆ write_single_register()

Result write_single_register ( Session session,
uint16_t  index,
uint16_t  value 
)

perform a blocking operation to write a single register

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
indexaddress of the value
valuevalue to write
Returns
Result struct describing the success or failure of the operation
Note
This function is thread-safe

◆ write_single_register_cb()

void write_single_register_cb ( Session session,
uint16_t  index,
uint16_t  value,
void(*)(Result, void *)  callback,
void *  user_data 
)

perform a non-blocking operation to write a single register

Parameters
sessionpointer to the Session struct that provides the runtime, channel, etc
indexaddress of the value
valuevalue to write
callbackcallback function to invoke when the operation completes
user_datapointer to optional user data data providing context to the callback
Note
This function is thread-safe