docs/modbus_tcp_pi_listen.md

   1 # modbus_tcp_pi_listen
   2
   3 ## Name
   4
   5 modbus_tcp_pi_listen - create and listen a TCP PI Modbus socket (IPv6)
   6
   7 ## Synopsis
   8
   9 ```c
  10 int modbus_tcp_pi_listen(modbus_t *ctx, int nb_connection);
  11 ```
  12
  13 ## Description
  14
  15 The *modbus_tcp_pi_listen()* function shall create a socket and listen to
  16 maximum `nb_connection` incoming connections on the specified nodes.  The
  17 context *ctx* must be allocated and initialized with [modbus_new_tcp_pi](modbus_new_tcp_pi.md)
  18 before to set the node to listen, if node is set to NULL or '0.0.0.0', any addresses will be
  19 listen.
  20
  21 ## Return value
  22
  23 The function shall return a new socket if successful. Otherwise it shall return
  24 -1 and set errno.
  25
  26 ## Example
  27
  28 For detailed examples, see source files in tests directory:
  29
  30 - unit-test-server.c, simple but handle only one connection
  31
  32 ```c
  33 ...
  34
  35 ctx = modbus_new_tcp_pi("::0", "502");
  36 s = modbus_tcp_pi_listen(ctx, 1);
  37 modbus_tcp_pi_accept(ctx, &s);
  38
  39 for (;;) {
  40     rc = modbus_receive(ctx, query);
  41     modbus_replay(ctx, query, rc, mb_mapping);
  42 }
  43 ...
  44
  45 modbus_close(s);
  46 modbus_free(ctx);
  47 ```
  48
  49 - bandwidth-server-many-up.c, handles several connections at once
  50
  51 ## See also
  52
  53 - [modbus_new_tcp_pi](modbus_new_tcp_pi.md)
  54 - [modbus_tcp_pi_accept](modbus_tcp_pi_accept.md)
  55 - [modbus_tcp_listen](modbus_tcp_listen.md)