NAME

       lc_channel_detect_gaps,  lc_channel_check_seqno  - check for missing incoming messages and
       send NACK messages if required

SYNOPSIS

       #include <librecast/net.h>

       int lc_channel_detect_gaps(lc_channel_t *chan);
       int lc_channel_check_seqno(lc_channel_t *chan, lc_seq_t seq);

       Compile and link with -llibrecast.

DESCRIPTION

       lc_channel_detect_gaps() arranges for a channel  to  check  message  sequence  numbers  of
       recently  received  messages  and  to  send  NACK  messages if it detects gaps. These NACK
       messages will cause the sender to resend the missing messages, which will then  arrive  as
       normal.    The   application   needs   to   receive   messages   using   lc_msg_recv()  or
       lc_socket_listen() which decode the incoming messages and extract  the  sequence  numbers,
       and will then automatically detect gaps.

       lc_channel_check_seqno()  compares  the  sequence  number  passed  to it with the sequence
       numbers of recent messages and sends NACKs if any are deemed missing: it is  necessary  to
       call  this  if  an  application  uses  its own message format, and receives messages using
       functions other than lc_msg_recv() or lc_socket_listen() because the library will not have
       the  information  necessary to extract sequence numbers from messages; however the library
       will still take care of gap detection and NACK messages. The second argument must  be  the
       sequence  number  from  the message as decoded by the application. It is necessary to call
       lc_channel_detect_gaps() before using lc_channel_check_seqno() otherwise the function will
       not do anything. This could be useful for example if gap detection and NACKs are optional,
       and   the   application   will   conditionally   call   lc_channel_detect_gaps()    during
       initialisation,  but  then  can  just  unconditionally call lc_channel_check_seqno() after
       decoding each incoming message.

RETURN VALUE

       lc_channel_detect_gaps() returns 0 on success, and -1 to indicate an  error,  setting  the
       global  variable  errno  to an appropriate code, most likely ENOMEM to indicate that there
       was insufficient memory to set up the required data structures.

       lc_channel_detect_gaps() returns 0 if the message is new, 1 if  it  is  a  duplicate  (the
       sequence  number  has  already  been seen) and -1 to indicate an error transmitting a NACK
       message, setting errno to an appropriate code.

ERRORS

       lc_channel_detect_gaps() can fail with any of the errors the malloc() library function can
       produce,  as  well  as any errors produces by the lc_channel_sidehash() or lc_socket_new()
       functions.

       lc_channel_check_seqno() can fail with any of the errors the lc_socket_send() function can
       produce.

EXAMPLE

   Program source

       lc_ctx_t *lctx;
       lc_channel_t *chan;
       lctx = lc_ctx_new();
       chan = lc_channel_new(lctx, "channel name");
       if (lc_channel_detect_gaps(chan) == -1) {
            /* handle this error */
       }

       /* your program goes here, likely calling lc_msg_recv(chan, ...) or lc_socket_listen(...)  */

       lc_channel_free(chan);
       lc_ctx_free(lctx);

SEE ALSO

       lc_channel_nack_handler(3),   lc_channel_free(3),   lc_msg_recv(3),   lc_socket_listen(3),
       lc_socket_send(3)