Rodbus-FFI  0.1.1
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  Callbacks
 
struct  Sizes
 
struct  RuntimeConfig
 Optional non-default configuration of the Tokio runtime. More...
 
struct  Bit
 
struct  Register
 
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 BitIterator BitIterator
 
typedef struct Handler Handler
 
typedef struct RegisterIterator RegisterIterator
 
typedef struct ServerHandle ServerHandle
 
typedef struct Updater Updater
 
typedef struct Session Session
 Struct that bundles together the types needed to make requests on a channel. More...
 
typedef bool(* WriteSingleCallback_bool) (bool, uint16_t, void *)
 
typedef bool(* WriteSingleCallback_u16) (uint16_t, uint16_t, void *)
 
typedef bool(* WriteMultipleCallback_bool) (const bool *, uint16_t, uint16_t, void *)
 
typedef bool(* WriteMultipleCallback_u16) (const uint16_t *, uint16_t, uint16_t, void *)
 
typedef struct Callbacks Callbacks
 
typedef struct Sizes Sizes
 
typedef struct RuntimeConfig RuntimeConfig
 Optional non-default configuration of the Tokio runtime. More...
 
typedef struct Bit Bit
 
typedef struct Register Register
 
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_IO_ERROR, STATUS_BAD_FRAMING,
  STATUS_EXCEPTION, STATUS_INTERNAL_ERROR
}
 

Functions

Updateracquire_updater (Handler *handler)
 
Session build_session (Runtime *runtime, Channel *channel, uint8_t unit_id, uint32_t timeout_ms)
 Convenience function to build a session struct. More...
 
Callbacks create_callbacks (WriteSingleCallback_bool write_single_coil_cb, WriteSingleCallback_u16 write_single_register_cb, WriteMultipleCallback_bool write_multiple_coils, WriteMultipleCallback_u16 write_multiple_registers)
 
Handlercreate_handler (Runtime *runtime, Sizes sizes, Callbacks callbacks, void *user_data)
 
ServerHandlecreate_server (Runtime *runtime, const char *address, uint8_t unit_id, Handler *handler)
 
Sizes create_sizes (uint16_t num_coils, uint16_t num_discrete_inputs, uint16_t num_holding_registers, uint16_t num_input_registers)
 
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_handler (Handler *handler)
 
void destroy_runtime (Runtime *runtime)
 Destroy a previously created runtime instance. More...
 
void destroy_server (ServerHandle *handle)
 
bool get_next_bit (BitIterator *iterator, Bit *value)
 retrieve the next bit and/or index from iterator More...
 
bool get_next_register (RegisterIterator *iterator, Register *value)
 retrieve the next register value and/or index from iterator 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, BitIterator *, 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, BitIterator *, 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, RegisterIterator *, 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, RegisterIterator *, void *), void *user_data)
 perform a non-blocking operation to read input registers More...
 
void release_updater (Updater *updater)
 
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...
 
bool update_coil (Updater *updater, bool value, uint16_t index)
 
void update_handler (Handler *handler, void *user_data, void(*callback)(Updater *, void *))
 
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

Maximum count allowed in a read coils/discrete inputs request

◆ MAX_READ_REGISTERS_COUNT

#define MAX_READ_REGISTERS_COUNT   125

Maximum count allowed in a read holding/input registers request

◆ MAX_WRITE_COILS_COUNT

#define MAX_WRITE_COILS_COUNT   1968

Maximum count allowed in a write multiple coils request

◆ MAX_WRITE_REGISTERS_COUNT

#define MAX_WRITE_REGISTERS_COUNT   123

Maximum count allowed in a write multiple registers request

Typedef Documentation

◆ Bit

typedef struct Bit Bit

◆ BitIterator

typedef struct BitIterator BitIterator

◆ Callbacks

typedef struct Callbacks Callbacks

◆ Exception

typedef uint8_t Exception

◆ Handler

typedef struct Handler Handler

◆ Level

typedef uint8_t Level

◆ Register

typedef struct Register Register

◆ RegisterIterator

◆ 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.

◆ ServerHandle

typedef struct ServerHandle ServerHandle

◆ Session

typedef struct Session Session

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

◆ Sizes

typedef struct Sizes Sizes

◆ Status

typedef uint8_t Status

◆ Updater

typedef struct Updater Updater

◆ WriteMultipleCallback_bool

typedef bool(* WriteMultipleCallback_bool) (const bool *, uint16_t, uint16_t, void *)

◆ WriteMultipleCallback_u16

typedef bool(* WriteMultipleCallback_u16) (const uint16_t *, uint16_t, uint16_t, void *)

◆ WriteSingleCallback_bool

typedef bool(* WriteSingleCallback_bool) (bool, uint16_t, void *)

◆ WriteSingleCallback_u16

typedef bool(* WriteSingleCallback_u16) (uint16_t, uint16_t, void *)

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_IO_ERROR 

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

◆ acquire_updater()

Updater* acquire_updater ( Handler handler)

◆ 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_callbacks()

Callbacks create_callbacks ( WriteSingleCallback_bool  write_single_coil_cb,
WriteSingleCallback_u16  write_single_register_cb,
WriteMultipleCallback_bool  write_multiple_coils,
WriteMultipleCallback_u16  write_multiple_registers 
)

◆ create_handler()

Handler* create_handler ( Runtime runtime,
Sizes  sizes,
Callbacks  callbacks,
void *  user_data 
)

◆ create_server()

ServerHandle* create_server ( Runtime runtime,
const char *  address,
uint8_t  unit_id,
Handler handler 
)

◆ create_sizes()

Sizes create_sizes ( uint16_t  num_coils,
uint16_t  num_discrete_inputs,
uint16_t  num_holding_registers,
uint16_t  num_input_registers 
)

◆ 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_handler()

void destroy_handler ( Handler handler)

◆ 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

◆ destroy_server()

void destroy_server ( ServerHandle handle)

◆ get_next_bit()

bool get_next_bit ( BitIterator iterator,
Bit value 
)

retrieve the next bit and/or index from iterator

Parameters
pointerto the iterator
pointerto the value to write (output param)
pointerto the value to write (output param)
Returns
true if the iterator is non-null and it contained another value

◆ get_next_register()

bool get_next_register ( RegisterIterator iterator,
Register value 
)

retrieve the next register value and/or index from iterator

Parameters
pointerto the iterator
pointerto the value to write (output param)
pointerto the value to write (output param)
Returns
true if the iterator is non-null and it contained another value

◆ 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, BitIterator *, 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, BitIterator *, 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, RegisterIterator *, 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, RegisterIterator *, 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

◆ release_updater()

void release_updater ( Updater updater)

◆ 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

◆ update_coil()

bool update_coil ( Updater updater,
bool  value,
uint16_t  index 
)

◆ update_handler()

void update_handler ( Handler handler,
void *  user_data,
void(*)(Updater *, void *)  callback 
)

◆ 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