add helper functions to support external event loops, see obgm#1554

include/coap3/coap_net.h

@@ -833,6 +833,39 @@ struct epoll_event;
 COAP_API void coap_io_do_epoll(coap_context_t *ctx, struct epoll_event *events,
                                size_t nevents);
 
+/**
+ * Get the libcoap internal file descriptor for a socket. This can be used to
+ * integrate libcoap in an external event loop instead of using one of its
+ * builtin event loops.
+ *
+ * @param socket The CoAP socket
+ *
+ * @return The libcoap file descriptor or @c COAP_INVALID_SOCKET if the platform
+ *         is not using file descriptors.
+ */
+COAP_API coap_fd_t coap_socket_get_fd(coap_socket_t *socket);
+
+/**
+ * Get the libcoap internal flags for a socket. This can be used to
+ * integrate libcoap in an external event loop instead of using one of its
+ * builtin event loops.
+ *
+ * @param socket The CoAP socket
+ *
+ * @return the OR-ed COAP_SOCKET* flags for this socket
+ */
+COAP_API coap_socket_flags_t coap_socket_get_flags(coap_socket_t *socket);
+
+/**
+ * Set the libcoap internal flags for a socket. This can be used to
+ * integrate libcoap in an external event loop instead of using one of its
+ * builtin event loops.
+ *
+ * @param socket The CoAP socket
+ * @param flags The new flags for this socket
+ */
+COAP_API void coap_socket_set_flags(coap_socket_t *socket, coap_socket_flags_t flags);
+
 /**@}*/
 
 #if defined(WITH_LWIP) || defined(WITH_LWIP_MAN_CHECK) || defined(__DOXYGEN__)

libcoap-3.map

@@ -297,6 +297,9 @@ global:
   coap_set_show_pdu_output;
   coap_show_pdu;
   coap_show_tls_version;
+  coap_socket_get_fd;
+  coap_socket_get_flags;
+  coap_socket_set_flags;
   coap_socket_strerror;
   coap_split_path;
   coap_split_proxy_uri;

libcoap-3.sym

@@ -295,6 +295,9 @@ coap_set_prng
 coap_set_show_pdu_output
 coap_show_pdu
 coap_show_tls_version
+coap_socket_get_fd
+coap_socket_get_flags
+coap_socket_set_flags
 coap_socket_strerror
 coap_split_path
 coap_split_proxy_uri

man/Makefile.am

@@ -136,6 +136,9 @@ install-man: install-man3 install-man5 install-man7
 	@echo ".so man3/coap_deprecated.3" > coap_write.3
 	@echo ".so man3/coap_io.3" > coap_io_pending.3
 	@echo ".so man3/coap_io.3" > coap_can_exit.3
+	@echo ".so man3/coap_io.3" > coap_socket_get_fd.3
+	@echo ".so man3/coap_io.3" > coap_socket_get_flags.3
+	@echo ".so man3/coap_io.3" > coap_socket_set_flags.3
 	@echo ".so man3/coap_locking.3" > coap_lock_callback_ret_release.3
 	@echo ".so man3/coap_locking.3" > coap_lock_invert.3
 	@echo ".so man3/coap_logging.3" > coap_log_info.3

man/coap_io.txt.in

@@ -19,7 +19,10 @@ coap_io_do_io,
 coap_io_prepare_epoll,
 coap_io_do_epoll,
 coap_io_pending,
-coap_can_exit
+coap_can_exit,
+coap_socket_get_fd,
+coap_socket_get_flags,
+coap_socket_set_flags
 - Work with CoAP I/O to do the packet send and receives
 
 SYNOPSIS
@@ -50,6 +53,12 @@ size_t _nevents_)*;
 
 *int coap_can_exit(coap_context_t *_context_)*;
 
+*coap_fd_t coap_socket_get_fd(coap_socket_t *socket);*
+
+*coap_socket_flags_t coap_socket_get_flags(coap_socket_t *socket);*
+
+*void coap_socket_set_flags(coap_socket_t *socket, coap_socket_flags_t flags);*
+
 For specific (D)TLS library support, link with
 *-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*,
 *-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls*,
@@ -202,6 +211,22 @@ PDUs to transmit associated with _context_ and returns 1 if there is nothing
 outstanding else 0. This function does not check that all requests transmitted
 have been responded to.
 
+*Function: coap_socket_get_fd()*
+
+The *coap_socket_get_fd*() function obtains the file descriptor from the given
+socket. The file descriptor can be used to integrate libcoap in an external
+event loop instead of using one of its builtin event loops.
+
+*Function: coap_socket_get_flags()*
+
+The *coap_socket_get_flags*() function obtains the event flags from the
+given socket.
+
+*Function: coap_socket_set_flags()*
+
+The *coap_socket_set_flags*() function sets the event flags for the
+given socket.
+
 RETURN VALUES
 -------------
 *coap_io_process*() and *coap_io_process_with_fds*() return the time, in
@@ -219,6 +244,11 @@ milli-seconds that need to be waited before the function should next be called.
 *coap_can_exit*() returns 1 if there is nothing outstanding to transmit else
 returns 0.
 
+*coap_socket_get_fd*() returns the file descriptor or COAP_INVALID_SOCKET if
+the platform does not use file descriptors.
+
+*coap_socket_get_flags*() returns the OR-ed COAP_SOCKET* flags for this socket.
+
 EXAMPLES
 --------
 *Method One - use coap_io_process()*

man/examples-code-check.c

@@ -121,6 +121,8 @@ const char *pointer_list[] = {
 
 /* xxx function */
 const char *number_list[] = {
+  "coap_fd_t ",
+  "coap_socket_flags_t ",
   "coap_log_t ",
   "coap_pdu_type_t ",
   "coap_mid_t ",

src/coap_io.c

@@ -1902,4 +1902,24 @@ coap_socket_strerror(void) {
 }
 #endif /* _WIN32 */
 
+COAP_API coap_fd_t
+coap_socket_get_fd(coap_socket_t *socket) {
+#if !defined(WITH_LWIP) && !defined(WITH_CONTIKI)
+  return socket->fd;
+#else
+  (void)(socket);
+  return COAP_INVALID_SOCKET;
+#endif
+}
+
+COAP_API coap_socket_flags_t
+coap_socket_get_flags(coap_socket_t *socket) {
+  return socket->flags;
+}
+
+COAP_API void
+coap_socket_set_flags(coap_socket_t *socket, coap_socket_flags_t flags) {
+  socket->flags = flags;
+}
+
 #undef SIN6