.TH LC_CHANNEL_DETECT_GAPS 3 2022-10-29 "LIBRECAST" "Librecast Programmer's Manual"
.SH NAME
lc_channel_detect_gaps, lc_channel_check_seqno \- check for missing incoming messages
and send NACK messages if required
.SH LIBRARY
Librecast library
.RI ( liblibrecast ", " \-llibrecast )
.SH SYNOPSIS
.nf
.B #include <librecast/net.h>
.PP
.BI "int lc_channel_detect_gaps(lc_channel_t *chan);"
.BI "int lc_channel_check_seqno(lc_channel_t *chan, lc_seq_t seq);"
.fi
.PP
Compile and link with \fI\-llibrecast\fP.
.SH DESCRIPTION
.BR 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
.BR lc_msg_recv ()
or
.BR lc_socket_listen ()
which decode the incoming messages and extract the sequence numbers, and will
then automatically detect gaps.
.PP
.BR 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
.BR lc_msg_recv ()
or
.BR 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
.BR lc_channel_detect_gaps ()
before using
.BR 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
.BR lc_channel_detect_gaps ()
during initialisation, but then can just unconditionally call
.BR lc_channel_check_seqno ()
after decoding each incoming message.
.SH RETURN VALUE
.BR lc_channel_detect_gaps ()
returns 0 on success, and -1 to indicate an error, setting the global variable
.I errno
to an appropriate code, most likely
.BR ENOMEM
to indicate that there was insufficient memory to set up the required data structures.
.PP
.BR 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
.I errno
to an appropriate code.
.SH ERRORS
.BR lc_channel_detect_gaps ()
can fail with any of the errors the
.BR malloc ()
library function can produce, as well as any errors produces by the
.BR lc_channel_sidehash ()
or
.BR lc_socket_new ()
functions.
.PP
.BR lc_channel_check_seqno ()
can fail with any of the errors the
.BR lc_socket_send ()
function can produce.
.SH EXAMPLE
.SS Program source
\&
.EX
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);
.EE
.SH SEE ALSO
.BR lc_channel_nack_handler (3),
.BR lc_channel_free (3),
.BR lc_msg_recv (3),
.BR lc_socket_listen (3),
.BR lc_socket_send (3)