Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
COAP_IO(3)			libcoap	Manual			    COAP_IO(3)

NAME
       coap_io,	coap_run_once, coap_context_get_coap_fd	- Work with CoAP I/O
       to do the packet	send and receives

SYNOPSIS
       #include	<coap2/coap.h>

       int coap_run_once(coap_context_t	*context, unsigned int timeout_ms);

       int coap_context_get_coap_fd(coap_context_t *context);

       Link with -lcoap-2, -lcoap-2-gnutls, -lcoap-2-openssl or
       -lcoap-2-tinydtls depending on your (D)TLS library type.

DESCRIPTION
       After setting up	all the	contexts, resources, endpoints sessions	etc.,
       the underlying CoAP and (D)TLS need to send (and	possible re-send)
       created packets as well as receive packets for processing.

       The coap_run_once() function will process any outstanding packets to
       send for	the specified context and wait for processing any input
       packets for up to timeout_ms milli-seconds before returning. Once any
       outstanding input packets have been processed, the function will
       return. There are 2 special case	timeout_ms values.

	   #define COAP_RUN_BLOCK    0
	   #define COAP_RUN_NONBLOCK 1

       If timeout_ms is	set to COAP_RUN_BLOCK, then coap_run_once() will wait
       indefinitely for	the first new input packet to come in. If timeout_ms
       is set to COAP_RUN_NONBLOCK, then there is no wait if there are no more
       input packets.

       There are two methods of	how to call coap_run_once().

	1. Have	coap_run_once()	called from within a while() loop. Under idle
	   conditions (no input	traffic) coap_run_once() will then get called
	   every timeout_ms, but more frequently if there is input traffic.

	2. Wait	on the file descriptor returned	by coap_context_get_coap_fd()
	   using select() or an	event returned by epoll_wait().	If read	is
	   available on	the file descriptor, call coap_run_once() with
	   timeout_ms set to COAP_RUN_NONBLOCK.	See EXAMPLES below.

	   Note
	   This	method is only available for environments that support epoll
	   (mostly Linux) as libcoap will then be using	epoll internally to
	   process all the file	descriptors of the different sessions.

       The coap_context_get_coap_fd() function obtains from the	specified
       context a single	file descriptor	that can be monitored by a select() or
       as an event returned from a epoll_wait()	call. This file	descriptor
       will get	updated	with information (read,	write etc. available) whenever
       any of the internal to libcoap file descriptors (sockets) change	state.

RETURN VALUES
       coap_run_once() returns the time, in milli-seconds, that	was spent in
       the function. If	-1 is returned,	there was an unexpected	error.

       coap_context_get_coap_fd() returns a non-negative number	as the file
       descriptor to monitor, or -1 if epoll is	not supported by the host
       environment.

EXAMPLES
       Method One

	   #include <coap2/coap.h>

	   int main(int	argc, char *argv[]){

	     coap_context_t *ctx = NULL;
	     unsigned wait_ms;

	     /*	Create the libcoap context */
	     ctx = coap_new_context(NULL);
	     if	(!ctx) {
	       exit(1);
	     }

	     /*	Other Set up Code */

	     wait_ms = COAP_RESOURCE_CHECK_TIME	* 1000;

	     while (1) {
	       int result = coap_run_once(ctx, wait_ms);
	       if (result < 0) {
		 /* There is an	internal issue */
		 break;
	       }
	       /* Do any other housekeeping */
	     }
	     coap_free_context(ctx);

	     /*	Do any other cleanup */

	     exit(0);

	   }

       Method Two - select

	   #include <coap2/coap.h>

	   #include <errno.h>

	   int main(int	argc, char *argv[]){

	     coap_context_t *ctx = NULL;
	     int coap_fd;
	     fd_set m_readfds;
	     int nfds;

	     /*	Create the libcoap context */
	     ctx = coap_new_context(NULL);
	     if	(!ctx) {
	       exit(1);
	     }
	     coap_fd = coap_context_get_coap_fd(ctx);
	     if	(coap_fd == -1)	{
	       exit(1);
	     }
	     FD_ZERO(&m_readfds);
	     FD_SET(coap_fd, &m_readfds);
	     nfds = coap_fd + 1;

	     /*	Other Set up Code */

	     while (1) {
	       fd_set readfds =	m_readfds;
	       int result;
	       /* Wait until any i/o takes place */
	       result =	select (nfds, &readfds,	NULL, NULL, NULL);
	       if (result == -1) {
		 if (errno != EAGAIN) {
		   coap_log(LOG_DEBUG, "select:	%s (%d)\n", coap_socket_strerror(), errno);
		   break;
		 }
	       }
	       if (result > 0) {
		 if (FD_ISSET(coap_fd, &readfds)) {
		   result = coap_run_once(ctx, COAP_RUN_NONBLOCK);
		   if (result <	0) {
		     /*	There is an internal issue */
		     break;
		   }
		 }
	       }
	       /* Do any other housekeeping */
	     }
	     coap_free_context(ctx);

	     /*	Do any other cleanup */

	     exit(0);

	   }

       Method Two - epoll

	   #include <coap2/coap.h>

	   #include <sys/epoll.h>

	   #include <errno.h>

	   #define MAX_EVENTS 10

	   int main(int	argc, char *argv[]){

	     coap_context_t *ctx = NULL;
	     int coap_fd;
	     int epoll_fd;
	     struct epoll_event	ev;
	     struct epoll_event	events[MAX_EVENTS];
	     int nevents;
	     int i;

	     /*	Create the libcoap context */
	     ctx = coap_new_context(NULL);
	     if	(!ctx) {
	       exit(1);
	     }
	     coap_fd = coap_context_get_coap_fd(ctx);
	     if	(coap_fd == -1)	{
	       exit(1);
	     }
	     epoll_fd =	epoll_create1(0);
	     if	(epoll_fd == -1) {
	       exit(2);
	     }
	     ev.events = EPOLLIN;
	     ev.data.fd	= coap_fd;
	     if	(epoll_ctl(epoll_fd, EPOLL_CTL_ADD, coap_fd, &ev) == -1) {
	       exit(3);
	     }

	     /*	Other Set up Code */

	     while (1) {
	       int result;
	       /* Wait until any i/o takes place */
	       nevents = epoll_wait(epoll_fd, events, MAX_EVENTS, -1);
	       if (nevents == -1) {
		 if (errno != EAGAIN) {
		   coap_log(LOG_DEBUG, "epoll_wait: %s (%d)\n",	coap_socket_strerror(),	errno);
		   break;
		 }
	       }
	       for (i =	0; i < nevents;	i++) {
		 if (events[i].data.fd == coap_fd) {
		   result = coap_run_once(ctx, COAP_RUN_NONBLOCK);
		   if (result <	0) {
		     /*	There is an internal issue */
		     break;
		   }
		 }
		 else {
		   /* Process other events */
		 }
	       }
	       /* Do any other housekeeping */
	     }

	     if	(epoll_ctl(epoll_fd, EPOLL_CTL_DEL, coap_fd, &ev) == -1) {
	       coap_log(LOG_DEBUG, "epoll_ctl: %s (%d)\n", coap_socket_strerror(), errno);
	     }
	     coap_free_context(ctx);

	     /*	Do any other cleanup */

	     exit(0);

	   }

SEE ALSO
       coap_context(3)

FURTHER	INFORMATION
       See "RFC7252: The Constrained Application Protocol (CoAP)" for further
       information.

BUGS
       Please report bugs on the mailing list for libcoap:
       libcoap-developers@lists.sourceforge.net

AUTHORS
       The libcoap project <libcoap-developers@lists.sourceforge.net>

coap_io	4.2.1			  03/01/2021			    COAP_IO(3)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | EXAMPLES | SEE ALSO | FURTHER INFORMATION | BUGS | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=coap_io&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help