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.

NEWS

@@ -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)
 ============================

doc/Makefile.am

@@ -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 \

doc/modbus_receive.txt

@@ -0,0 +1,40 @@
+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>

doc/modbus_receive_from.txt

@@ -0,0 +1,38 @@
+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>

src/modbus.c

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

src/modbus.h

@@ -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,

tests/bandwidth-server-many-up.c

@@ -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 {

tests/bandwidth-server-one.c

@@ -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 {

tests/random-test-server.c

@@ -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);

tests/unit-test-server.c

@@ -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;