diff --git a/docs/index.md b/docs/index.md index 9601cc826..a63859edb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -205,6 +205,11 @@ Information about header: - [modbus_get_header_length](modbus_get_header_length) +Set or get the client data:: + +- [modbus_set_client_context](modbus_set_client_context) +- [modbus_get_client_context](modbus_get_client_context) + ## Data handling Macros for data manipulation: diff --git a/docs/modbus_get_client_context.md b/docs/modbus_get_client_context.md new file mode 100644 index 000000000..4eff139a3 --- /dev/null +++ b/docs/modbus_get_client_context.md @@ -0,0 +1,38 @@ +# modbus_get_client_context + + +## Name + +`modbus_get_client_context` - returns the client context value from the libmodbus +context + + +## Synopsis + +```c +const void *modbus_get_client_context(modbus_t *'ctx'); +``` + +## Description + +The `modbus_get_client_context()` function shall return the client context value +from the `libmodbus` context. + +Do not be confused by the overloaded use of “client” and “context” in these +functions. Here, “client” refers to the code that makes use of `libmodbus`, +“client context” is the data set and get by the client code, and “libmodbus context” +is the `modbus_t*` context pointer. + +## Return Value + +The function shall return the client context or NULL. + + +## Errors + +This function does not return an error. + + +## See also + +- [`modbus_set_client_context()`](modbus_set_client_context) diff --git a/docs/modbus_set_client_context.md b/docs/modbus_set_client_context.md new file mode 100644 index 000000000..36aff1d80 --- /dev/null +++ b/docs/modbus_set_client_context.md @@ -0,0 +1,61 @@ +# modbus_set_client_context + + +## Name + +`modbus_set_client_context` - set context information (usually a pointer) for use +by the client + + +## Synopsis + +```c +int modbus_set_client_context(modbus_t *ctx, void *cctx) +``` + + +## Description + +The `modbus_set_client_context()` function can be used to set arbitrary client +context information. The actual value is not used by libmodbus, but instead +is available to client callback functions via `modbus_get_client_context()`. + +Do not be confused by the overloaded use of “client” and “context” in these +functions. Here, “client” refers to the code that makes use of libmodbus and +“client context” is the data used by the client code. + +## Return Value + +The function shall return 0 if successful. Otherwise it shall return -1 and set +errno to one of the values defined below. + + +## Errors + +- *EINVAL*, The libmodbus context is NULL. + + +## Example + +```cpp +modbus_t *ctx; +uint16_t tab_reg[10]; +struct ClientContext { + int clientData1; + int clientData2; +}; +ClientContext *cctx = new ClientContext(); + +ctx = modbus_new_rtu("/dev/ttyS0", 115200, 'N', 8, 1); +modbus_set_slave(ctx, 1); +modbus_rtu_set_serial_mode(ctx, MODBUS_RTU_RS485); +modbus_set_client_context(ctx, cctx); + +ClientContext *myCCTX = reinterpret_cast(modbus_get_client_context(ctx)); + +modbus_free(ctx); +``` + +## See also + +[`modbus_get_client_context()`](modbus_get_client_context) diff --git a/src/modbus-private.h b/src/modbus-private.h index df2ca6d92..0ed28a77e 100644 --- a/src/modbus-private.h +++ b/src/modbus-private.h @@ -101,6 +101,7 @@ struct _modbus { struct timeval indication_timeout; const modbus_backend_t *backend; void *backend_data; + const void *client_context; }; void _modbus_init_common(modbus_t *ctx); diff --git a/src/modbus.c b/src/modbus.c index 0dbf82b7e..c86496275 100644 --- a/src/modbus.c +++ b/src/modbus.c @@ -1826,6 +1826,24 @@ int modbus_set_debug(modbus_t *ctx, int flag) return 0; } +int modbus_set_client_context(modbus_t *ctx, const void *cctx) +{ + if (ctx == NULL) { + errno = EINVAL; + return -1; + } + + ctx->client_context = cctx; + + return 0; +} + +const void *modbus_get_client_context(modbus_t *ctx) +{ + return ctx->client_context; +} + + /* Allocates 4 arrays to store bits, input bits, registers and inputs registers. The pointers are stored in modbus_mapping structure. diff --git a/src/modbus.h b/src/modbus.h index 70a6c22a8..8676a30d9 100644 --- a/src/modbus.h +++ b/src/modbus.h @@ -238,6 +238,9 @@ MODBUS_API int modbus_reply(modbus_t *ctx, const uint8_t *req, MODBUS_API int modbus_reply_exception(modbus_t *ctx, const uint8_t *req, unsigned int exception_code); +MODBUS_API int modbus_set_client_context(modbus_t *ctx, const void *cctx); +MODBUS_API const void* modbus_get_client_context(modbus_t *ctx); + /** * UTILS FUNCTIONS **/