Rename [gs]et_timeout_[begin|end] to [gs]et_[response|byte]_timeout

The following functions have been renamed: - modbus_get_timeout_begin -> modbus_get_response_timeout - modbus_set_timeout_begin -> modbus_set_response_timeout - modbus_get_timeout_end -> modbus_get_byte_timeout - modbus_set_timeout_end -> modbus_set_byte_timeout The meaning of these timeout intervals is now clearer. The documentation has been updated.

Rename [gs]et_timeout_[begin|end] to [gs]et_[response|byte]_timeout
The following functions have been renamed: - modbus_get_timeout_begin -> modbus_get_response_timeout - modbus_set_timeout_begin -> modbus_set_response_timeout - modbus_get_timeout_end -> modbus_get_byte_timeout - modbus_set_timeout_end -> modbus_set_byte_timeout The meaning of these timeout intervals is now clearer. The documentation has been updated.
Stéphane Raimbault
1 parent 1faf5c3a
Showing 9 changed files with 92 additions and 93 deletions
doc/Makefile.am
doc/modbus_get_timeout_end.txt → doc/modbus_get_byte_timeout.txt
doc/modbus_get_timeout_begin.txt → doc/modbus_get_response_timeout.txt
doc/modbus_set_timeout_end.txt → doc/modbus_set_byte_timeout.txt
doc/modbus_set_timeout_begin.txt → doc/modbus_set_response_timeout.txt
src/modbus-private.h
src/modbus.c
src/modbus.h
tests/unit-test-client.c
@@ -5,8 +5,8 @@ MAN3 = \
         modbus_free.3 \
         modbus_get_header_length.3 \
         modbus_get_socket.3 \
-        modbus_get_timeout_begin.3 \
-        modbus_get_timeout_end.3 \
+        modbus_get_response_timeout.3 \
+        modbus_get_byte_timeout.3 \
         modbus_new_rtu.3 \
         modbus_new_tcp_pi.3 \
         modbus_new_tcp.3 \
@@ -21,8 +21,8 @@ MAN3 = \
         modbus_set_error_recovery.3 \
         modbus_set_slave.3 \
         modbus_set_socket.3 \
-        modbus_set_timeout_begin.3 \
-        modbus_set_timeout_end.3 \
+        modbus_set_response_timeout.3 \
+        modbus_set_byte_timeout.3 \
         modbus_strerror.3 \
         modbus_write_bits.3 \
         modbus_write_bit.3 \
-modbus_get_timeout_end(3)
-===========================
+modbus_get_byte_timeout(3)
+==========================
  
  
 NAME
 ----
-modbus_get_timeout_end - get timeout of end of message
+modbus_get_byte_timeout - get timeout between bytes
  
  
 SYNOPSIS
 --------
-*void modbus_get_timeout_end(*modbus_t 'ctx', struct timeval *'timeout');*
+*void modbus_get_byte_timeout(*modbus_t 'ctx', struct timeval *'timeout');*
  
  
 DESCRIPTION
 -----------
-The _modbus_get_timeout_end()_ function shall store the current timeout between
-the begin and the end of message in the 'timeout' argument.
+The _modbus_get_byte_timeout()_ function shall store the timeout interval
+between two consecutive bytes of the same message in the 'timeout' argument.
  
  
 RETURN VALUE
@@ -27,18 +27,18 @@ EXAMPLE
 -------
 [source,c]
 -------------------
-struct timeval timeout_end;
+struct timeval byte_timeout;
  
 /* Save original timeout */
-modbus_get_timeout_end(ctx, &timeout_end);
+modbus_get_byte_timeout(ctx, &byte_timeout);
 -------------------
  
  
 SEE ALSO
 --------
-linkmb:modbus_get_timeout_begin[3]
-linkmb:modbus_set_timeout_begin[3]
-linkmb:modbus_set_timeout_end[3]
+linkmb:modbus_get_response_timeout[3]
+linkmb:modbus_set_response_timeout[3]
+linkmb:modbus_set_byte_timeout[3]
  
  
 AUTHORS
-modbus_get_timeout_begin(3)
-===========================
+modbus_get_response_timeout(3)
+==============================
  
  
 NAME
 ----
-modbus_get_timeout_begin - get timeout of begin of message
+modbus_get_response_timeout - get timeout for response
  
  
 SYNOPSIS
 --------
-*void modbus_get_timeout_begin(*modbus_t 'ctx', struct timeval *'timeout');*
+*void modbus_get_response_timeout(*modbus_t 'ctx', struct timeval *'timeout');*
  
  
 DESCRIPTION
 -----------
-The _modbus_get_timeout_begin()_ function shall store the current timeout of
-begin of message in the 'timeout' argument.
+The _modbus_get_response_timeout()_ function shall store the timeout interval
+used to wait for a response in the 'timeout' argument.
  
  
 RETURN VALUE
@@ -27,24 +27,24 @@ EXAMPLE
 -------
 [source,c]
 -------------------
-struct timeval timeout_begin_old;
-struct timeval timeout_begin_new;
+struct timeval old_response_timeout;
+struct timeval response_timeout;
  
 /* Save original timeout */
-modbus_get_timeout_begin(ctx, &timeout_begin_old);
+modbus_get_response_timeout(ctx, &old_response_timeout);
  
 /* Define a new and too short timeout! */
-timeout_begin_new.tv_sec = 0;
-timeout_begin_new.tv_usec = 0;
-modbus_set_timeout_begin(ctx, &timeout_begin_new);
+response_timeout.tv_sec = 0;
+response_timeout.tv_usec = 0;
+modbus_set_response_timeout(ctx, &response_timeout);
 -------------------
  
  
 SEE ALSO
 --------
-linkmb:modbus_set_timeout_begin[3]
-linkmb:modbus_get_timeout_end[3]
-linkmb:modbus_set_timeout_end[3]
+linkmb:modbus_set_response_timeout[3]
+linkmb:modbus_get_byte_timeout[3]
+linkmb:modbus_set_byte_timeout[3]
  
  
 AUTHORS
-modbus_set_timeout_end(3)
-===========================
+modbus_set_byte_timeout(3)
+==========================
  
  
 NAME
 ----
-modbus_set_timeout_end - set timeout of end of message
+modbus_set_byte_timeout - set timeout between bytes
  
  
 SYNOPSIS
 --------
-*void modbus_set_timeout_end(*modbus_t 'ctx', struct timeval *'timeout');*
+*void modbus_set_byte_timeout(*modbus_t 'ctx', struct timeval *'timeout');*
  
  
 DESCRIPTION
 -----------
-The _modbus_set_timeout_end()_ function shall set the timeout of end of
-message. If the delay between the begin and the end of message is longer than
+The _modbus_set_byte_timeout()_ function shall set the timeout interval between
+two consecutive bytes of the same message. If the delay between is longer than
 the given timeout, an error will be raised.
  
  
@@ -26,9 +26,9 @@ There is no return values.
  
 SEE ALSO
 --------
-linkmb:modbus_get_timeout_begin[3]
-linkmb:modbus_set_timeout_begin[3]
-linkmb:modbus_get_timeout_end[3]
+linkmb:modbus_get_byte_timeout[3]
+linkmb:modbus_get_response_timeout[3]
+linkmb:modbus_set_response_timeout[3]
  
  
 AUTHORS
-modbus_set_timeout_begin(3)
-===========================
+modbus_set_response_timeout(3)
+==============================
  
  
 NAME
 ----
-modbus_set_timeout_begin - set timeout of begin of message
+modbus_set_response_timeout - set timeout for response
  
  
 SYNOPSIS
 --------
-*void modbus_set_timeout_begin(*modbus_t 'ctx', struct timeval *'timeout');*
+*void modbus_set_response_timeout(*modbus_t 'ctx', struct timeval *'timeout');*
  
  
 DESCRIPTION
 -----------
-The _modbus_set_timeout_begin()_ function shall set the timeout of begin of
-message. If the waiting before receiving a message is longer than the given
-timeout, an error will be raised.
+The _modbus_set_response_timeout()_ function shall set the timeout interval used
+to wait for a response. If the waiting before receiving the response is longer than
+the given timeout, an error will be raised.
  
  
 RETURN VALUE
@@ -28,24 +28,24 @@ EXAMPLE
 -------
 [source,c]
 -------------------
-struct timeval timeout_begin_old;
-struct timeval timeout_begin_new;
+struct timeval old_response_timeout;
+struct timeval response_timeout;
  
 /* Save original timeout */
-modbus_get_timeout_begin(ctx, &timeout_begin_old);
+modbus_get_response_timeout(ctx, &old_response_timeout);
  
 /* Define a new and too short timeout! */
-timeout_begin_new.tv_sec = 0;
-timeout_begin_new.tv_usec = 0;
-modbus_set_timeout_begin(ctx, &timeout_begin_new);
+response_timeout.tv_sec = 0;
+response_timeout.tv_usec = 0;
+modbus_set_response_timeout(ctx, &response_timeout);
 -------------------
  
  
 SEE ALSO
 --------
-linkmb:modbus_get_timeout_begin[3]
-linkmb:modbus_get_timeout_end[3]
-linkmb:modbus_set_timeout_end[3]
+linkmb:modbus_get_response_timeout[3]
+linkmb:modbus_get_byte_timeout[3]
+linkmb:modbus_set_byte_timeout[3]
  
  
 AUTHORS
@@ -45,9 +45,9 @@ MODBUS_BEGIN_DECLS
  
 #define _MODBUS_EXCEPTION_RSP_LENGTH  5
  
-/* Time out between messages in microsecond */
-#define _TIME_OUT_BEGIN_OF_MESSAGE    500000
-#define _TIME_OUT_END_OF_MESSAGE      500000
+/* Timeouts in microsecond (0.5 s) */
+#define _RESPONSE_TIMEOUT    500000
+#define _BYTE_TIMEOUT        500000
  
 /* Function codes */
 #define _FC_READ_COILS                0x01
@@ -104,8 +104,8 @@ struct _modbus {
     int s;
     int debug;
     int error_recovery;
-    struct timeval timeout_begin;
-    struct timeval timeout_end;
+    struct timeval response_timeout;
+    struct timeval byte_timeout;
     const modbus_backend_t *backend;
     void *backend_data;
 };
@@ -331,8 +331,8 @@ static int receive_msg(modbus_t *ctx, uint8_t *msg, msg_type_t msg_type)
         tv.tv_sec = 60;
         tv.tv_usec = 0;
     } else {
-        tv.tv_sec = ctx->timeout_begin.tv_sec;
-        tv.tv_usec = ctx->timeout_begin.tv_usec;
+        tv.tv_sec = ctx->response_timeout.tv_sec;
+        tv.tv_usec = ctx->response_timeout.tv_usec;
     }
  
     while (length_to_read != 0) {
@@ -398,10 +398,11 @@ static int receive_msg(modbus_t *ctx, uint8_t *msg, msg_type_t msg_type)
         }
  
         if (length_to_read > 0) {
-            /* If no character at the buffer wait
-               TIME_OUT_END_OF_MESSAGE before raising an error. */
-            tv.tv_sec = ctx->timeout_end.tv_sec;
-            tv.tv_usec = ctx->timeout_end.tv_usec;
+            /* If there is no character in the buffer, the allowed timeout
+               interval between two consecutive bytes is defined by
+               byte_timeout */
+            tv.tv_sec = ctx->byte_timeout.tv_sec;
+            tv.tv_usec = ctx->byte_timeout.tv_usec;
         }
     }
  
@@ -1311,11 +1312,11 @@ void _modbus_init_common(modbus_t *ctx)
     ctx->debug = FALSE;
     ctx->error_recovery = FALSE;
  
-    ctx->timeout_begin.tv_sec = 0;
-    ctx->timeout_begin.tv_usec = _TIME_OUT_BEGIN_OF_MESSAGE;
+    ctx->response_timeout.tv_sec = 0;
+    ctx->response_timeout.tv_usec = _RESPONSE_TIMEOUT;
  
-    ctx->timeout_end.tv_sec = 0;
-    ctx->timeout_end.tv_usec = _TIME_OUT_END_OF_MESSAGE;
+    ctx->byte_timeout.tv_sec = 0;
+    ctx->byte_timeout.tv_usec = _BYTE_TIMEOUT;
 }
  
 /* Define the slave number */
@@ -1346,28 +1347,26 @@ int modbus_get_socket(modbus_t *ctx)
     return ctx->s;
 }
  
-/* Get the timeout of begin of message */
-void modbus_get_timeout_begin(modbus_t *ctx, struct timeval *timeout)
+/* Get the timeout interval used to wait for a response */
+void modbus_get_response_timeout(modbus_t *ctx, struct timeval *timeout)
 {
-    *timeout = ctx->timeout_begin;
+    *timeout = ctx->response_timeout;
 }
  
-/* Set timeout when waiting the beginning of a message */
-void modbus_set_timeout_begin(modbus_t *ctx, const struct timeval *timeout)
+void modbus_set_response_timeout(modbus_t *ctx, const struct timeval *timeout)
 {
-    ctx->timeout_begin = *timeout;
+    ctx->response_timeout = *timeout;
 }
  
-/* Get the timeout of end of message */
-void modbus_get_timeout_end(modbus_t *ctx, struct timeval *timeout)
+/* Get the timeout interval between two consecutive bytes of a message */
+void modbus_get_byte_timeout(modbus_t *ctx, struct timeval *timeout)
 {
-    *timeout = ctx->timeout_end;
+    *timeout = ctx->byte_timeout;
 }
  
-/* Set timeout when waiting the end of a message */
-void modbus_set_timeout_end(modbus_t *ctx, const struct timeval *timeout)
+void modbus_set_byte_timeout(modbus_t *ctx, const struct timeval *timeout)
 {
-    ctx->timeout_end = *timeout;
+    ctx->byte_timeout = *timeout;
 }
  
 int modbus_get_header_length(modbus_t *ctx)
@@ -139,11 +139,11 @@ int modbus_set_error_recovery(modbus_t *ctx, int enabled);
 void modbus_set_socket(modbus_t *ctx, int socket);
 int modbus_get_socket(modbus_t *ctx);
  
-void modbus_get_timeout_begin(modbus_t *ctx, struct timeval *timeout);
-void modbus_set_timeout_begin(modbus_t *ctx, const struct timeval *timeout);
+void modbus_get_response_timeout(modbus_t *ctx, struct timeval *timeout);
+void modbus_set_response_timeout(modbus_t *ctx, const struct timeval *timeout);
  
-void modbus_get_timeout_end(modbus_t *ctx, struct timeval *timeout);
-void modbus_set_timeout_end(modbus_t *ctx, const struct timeval *timeout);
+void modbus_get_byte_timeout(modbus_t *ctx, struct timeval *timeout);
+void modbus_set_byte_timeout(modbus_t *ctx, const struct timeval *timeout);
  
 int modbus_get_header_length(modbus_t *ctx);
  
@@ -42,8 +42,8 @@ int main(int argc, char *argv[])
     int nb_points;
     int rc;
     float real;
-    struct timeval timeout_begin_old;
-    struct timeval timeout_begin_new;
+    struct timeval old_response_timeout;
+    struct timeval response_timeout;
     int use_backend;
  
     if (argc > 1) {
@@ -549,12 +549,12 @@ int main(int argc, char *argv[])
     }
  
     /* Save original timeout */
-    modbus_get_timeout_begin(ctx, &timeout_begin_old);
+    modbus_get_response_timeout(ctx, &old_response_timeout);
  
     /* Define a new and too short timeout */
-    timeout_begin_new.tv_sec = 0;
-    timeout_begin_new.tv_usec = 0;
-    modbus_set_timeout_begin(ctx, &timeout_begin_new);
+    response_timeout.tv_sec = 0;
+    response_timeout.tv_usec = 0;
+    modbus_set_response_timeout(ctx, &response_timeout);
  
     rc = modbus_read_registers(ctx, UT_REGISTERS_ADDRESS,
                                UT_REGISTERS_NB, tab_rp_registers);
@@ -567,7 +567,7 @@ int main(int argc, char *argv[])
     }
  
     /* Restore original timeout */
-    modbus_set_timeout_begin(ctx, &timeout_begin_old);
+    modbus_set_response_timeout(ctx, &old_response_timeout);
  
     /* Wait for data before flushing */
     usleep(250000);