API cleanup with modbus_receive and modbus_receive_from

Split the original modbus_receive function in two functions to avoid the strange -1 value to ignore the sockfd argument.

API cleanup with modbus_receive and modbus_receive_from
Split the original modbus_receive function in two functions to avoid the strange -1 value to ignore the sockfd argument.
Stéphane Raimbault
1 parent eeb6cd81
Showing 10 changed files with 108 additions and 16 deletions
NEWS
doc/Makefile.am
doc/modbus_receive.txt
doc/modbus_receive_from.txt
src/modbus.c
src/modbus.h
tests/bandwidth-server-many-up.c
tests/bandwidth-server-one.c
tests/random-test-server.c
tests/unit-test-server.c
@@ -10,7 +10,9 @@ libmodbus 2.9.4 (2011-05-XX)
   Raimbault
 - New functions to send and receive raw requests
 - Fix flush function of TCP backend on Windows
-
+- API changes for server/slave:
+    * modbus_receive has been renamed modbus_receive_from
+    * modbus_receive has been added to use the socket of the context.
  
 libmodbus 2.9.3 (2011-01-14)
 ============================
@@ -13,6 +13,8 @@ MAN3 = \
         modbus_read_input_bits.3 \
         modbus_read_input_registers.3 \
         modbus_read_registers.3 \
+        modbus_receive.3 \
+        modbus_receive_from.3 \
         modbus_receive_confirmation.3 \
         modbus_send_raw_request.3 \
         modbus_set_debug.3 \
+modbus_receive(3)
+=================
+
+
+NAME
+----
+modbus_receive - receive a indication request
+
+
+SYNOPSIS
+--------
+*int modbus_receive(*modbus_t 'ctx', uint8_t *'req');*
+
+
+DESCRIPTION
+-----------
+The _modbus_receive()_ function shall receive an indication request from the
+socket of the context 'ctx'. This function is used by Modbus slave/server to
+receive and analyze indication request sent by the masters/clients.
+
+If you need to use another socket than the one defined in the context 'ctx', see
+the function linkmb:modbus_receive_from[3].
+
+
+RETURN VALUE
+------------
+The _modbus_receive()_ function shall store the indication request in 'req' and
+return the request length if sucessful. Otherwise it shall return -1 and set
+errno.
+
+
+SEE ALSO
+--------
+linkmb:modbus_receive_from[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>
+modbus_receive_from(3)
+======================
+
+
+NAME
+----
+modbus_receive_from - receive a indication request from a socket
+
+
+SYNOPSIS
+--------
+*int modbus_receive_from(*modbus_t 'ctx', int sockfd, uint8_t *'req');*
+
+
+DESCRIPTION
+-----------
+The _modbus_receive_from()_ function shall receive an indication request from
+the socket/file descriptor given in argument 'sockfd. This function is used by
+Modbus slave/server to receive and analyze indication request sent by the
+masters/clients.
+
+
+RETURN VALUE
+------------
+The _modbus_receive_from()_ function shall store the indication request in 'req'
+and return the request length if sucessful. Otherwise it shall return -1 and set
+errno.
+
+
+SEE ALSO
+--------
+linkmb:modbus_receive[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>
@@ -413,19 +413,27 @@ static int receive_msg(modbus_t *ctx, uint8_t *msg, msg_type_t msg_type)
     return ctx->backend->check_integrity(ctx, msg, msg_length);
 }
  
-/* Receive the request from a modbus master, requires the socket file descriptor
-   etablished with the master device in argument or -1 to use the internal one
-   of modbus_t.
+/* Receive the request from a modbus master */
+int modbus_receive(modbus_t *ctx, uint8_t *req)
+{
+    return receive_msg(ctx, req, MSG_INDICATION);
+}
  
-   The function shall return the request received and its byte length if
-   successul. Otherwise, it shall return -1 and errno is set. */
-int modbus_receive(modbus_t *ctx, int sockfd, uint8_t *req)
+/* Requires a socket file descriptor with a connection etablished in
+   argument */
+int modbus_receive_from(modbus_t *ctx, int sockfd, uint8_t *req)
 {
-    if (sockfd != -1) {
-        ctx->s = sockfd;
-    }
+    int rc;
+    const int s_old = ctx->s;
  
-    return receive_msg(ctx, req, MSG_INDICATION);
+    ctx->s = sockfd;
+
+    rc = receive_msg(ctx, req, MSG_INDICATION);
+
+    /* Restore orignal socket */
+    ctx->s = s_old;
+
+    return rc;
 }
  
 /* Receives the confirmation.
@@ -175,7 +175,9 @@ void modbus_mapping_free(modbus_mapping_t *mb_mapping);
  
 int modbus_send_raw_request(modbus_t *ctx, uint8_t *raw_req, int raw_req_length);
  
-int modbus_receive(modbus_t *ctx, int sockfd, uint8_t *req);
+int modbus_receive(modbus_t *ctx, uint8_t *req);
+int modbus_receive_from(modbus_t *ctx, int sockfd, uint8_t *req);
+
 int modbus_receive_confirmation(modbus_t *ctx, uint8_t *rsp);
  
 int modbus_reply(modbus_t *ctx, const uint8_t *req,
@@ -118,7 +118,7 @@ int main(void)
                     /* An already connected master has sent a new query */
                     uint8_t query[MODBUS_TCP_MAX_ADU_LENGTH];
  
-                    rc = modbus_receive(ctx, master_socket, query);
+                    rc = modbus_receive_from(ctx, master_socket, query);
                     if (rc != -1) {
                         modbus_reply(ctx, query, rc, mb_mapping);
                     } else {
@@ -74,7 +74,7 @@ int main(int argc, char *argv[])
     for(;;) {
         uint8_t query[MODBUS_TCP_MAX_ADU_LENGTH];
  
-        rc = modbus_receive(ctx, -1, query);
+        rc = modbus_receive(ctx, query);
         if (rc >= 0) {
             modbus_reply(ctx, query, rc, mb_mapping);
         } else {
@@ -46,7 +46,7 @@ int main(void)
         uint8_t query[MODBUS_TCP_MAX_ADU_LENGTH];
         int rc;
  
-        rc = modbus_receive(ctx, -1, query);
+        rc = modbus_receive(ctx, query);
         if (rc != -1) {
             /* rc is the query size */
             modbus_reply(ctx, query, rc, mb_mapping);
@@ -115,7 +115,7 @@ int main(int argc, char*argv[])
     }
  
     for (;;) {
-        rc = modbus_receive(ctx, -1, query);
+        rc = modbus_receive(ctx, query);
         if (rc == -1) {
             /* Connection closed by the client or error */
             break;