Provided by: libcoap2_4.2.1-1_amd64 
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>