• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * coap_net.h -- CoAP context interface
3  *
4  * Copyright (C) 2010-2023 Olaf Bergmann <bergmann@tzi.org>
5  *
6  * SPDX-License-Identifier: BSD-2-Clause
7  *
8  * This file is part of the CoAP library libcoap. Please see README for terms
9  * of use.
10  */
11 
12 /**
13  * @file coap_net.h
14  * @brief CoAP context interface
15  */
16 
17 #ifndef COAP_NET_H_
18 #define COAP_NET_H_
19 
20 #include <stdlib.h>
21 #include <string.h>
22 #ifndef _WIN32
23 #include <sys/select.h>
24 #include <sys/time.h>
25 #endif
26 #include <time.h>
27 
28 #ifdef WITH_LWIP
29 #include <lwip/ip_addr.h>
30 #endif
31 
32 #include "coap_io.h"
33 #include "coap_dtls.h"
34 #include "coap_event.h"
35 #include "coap_pdu.h"
36 #include "coap_session.h"
37 #include "coap_debug.h"
38 
39 /**
40  * @ingroup application_api
41  * @defgroup context Context Handling
42  * API for handling PDUs using CoAP Contexts
43  * @{
44  */
45 
46 typedef enum coap_response_t {
47   COAP_RESPONSE_FAIL, /**< Response not liked - send CoAP RST packet */
48   COAP_RESPONSE_OK    /**< Response is fine */
49 } coap_response_t;
50 
51 /**
52  * Response handler that is used as callback in coap_context_t.
53  *
54  * @param session CoAP session.
55  * @param sent The PDU that was transmitted.
56  * @param received The PDU that was received.
57  * @param mid CoAP transaction ID.
58 
59  * @return @c COAP_RESPONSE_OK if successful, else @c COAP_RESPONSE_FAIL which
60  *         triggers sending a RST packet.
61  */
62 typedef coap_response_t (*coap_response_handler_t)(coap_session_t *session,
63                                                    const coap_pdu_t *sent,
64                                                    const coap_pdu_t *received,
65                                                    const coap_mid_t mid);
66 
67 /**
68  * Negative Acknowedge handler that is used as callback in coap_context_t.
69  *
70  * @param session CoAP session.
71  * @param sent The PDU that was transmitted.
72  * @param reason The reason for the NACK.
73  * @param mid CoAP message ID.
74  */
75 typedef void (*coap_nack_handler_t)(coap_session_t *session,
76                                     const coap_pdu_t *sent,
77                                     const coap_nack_reason_t reason,
78                                     const coap_mid_t mid);
79 
80 /**
81  * Received Ping handler that is used as callback in coap_context_t.
82  *
83  * @param session CoAP session.
84  * @param received The PDU that was received.
85  * @param mid CoAP message ID.
86  */
87 typedef void (*coap_ping_handler_t)(coap_session_t *session,
88                                     const coap_pdu_t *received,
89                                     const coap_mid_t mid);
90 
91 /**
92  * Received Pong handler that is used as callback in coap_context_t.
93  *
94  * @param session CoAP session.
95  * @param received The PDU that was received.
96  * @param mid CoAP message ID.
97  */
98 typedef void (*coap_pong_handler_t)(coap_session_t *session,
99                                     const coap_pdu_t *received,
100                                     const coap_mid_t mid);
101 
102 /**
103  * Registers a new message handler that is called whenever a response is
104  * received.
105  *
106  * @param context The context to register the handler for.
107  * @param handler The response handler to register.
108  */
109 void coap_register_response_handler(coap_context_t *context,
110                                     coap_response_handler_t handler);
111 
112 /**
113  * Registers a new message handler that is called whenever a confirmable
114  * message (request or response) is dropped after all retries have been
115  * exhausted, or a rst message was received, or a network or TLS level
116  * event was received that indicates delivering the message is not possible.
117  *
118  * @param context The context to register the handler for.
119  * @param handler The nack handler to register.
120  */
121 void coap_register_nack_handler(coap_context_t *context,
122                                 coap_nack_handler_t handler);
123 
124 /**
125  * Registers a new message handler that is called whenever a CoAP Ping
126  * message is received.
127  *
128  * @param context The context to register the handler for.
129  * @param handler The ping handler to register.
130  */
131 void coap_register_ping_handler(coap_context_t *context,
132                                 coap_ping_handler_t handler);
133 
134 /**
135  * Registers a new message handler that is called whenever a CoAP Pong
136  * message is received.
137  *
138  * @param context The context to register the handler for.
139  * @param handler The pong handler to register.
140  */
141 void coap_register_pong_handler(coap_context_t *context,
142                                 coap_pong_handler_t handler);
143 
144 /**
145  * Registers the option type @p type with the given context object @p ctx.
146  *
147  * @param ctx  The context to use.
148  * @param type The option type to register.
149  */
150 void coap_register_option(coap_context_t *ctx, uint16_t type);
151 
152 /**
153  * Creates a new coap_context_t object that will hold the CoAP stack status.
154  */
155 coap_context_t *coap_new_context(const coap_address_t *listen_addr);
156 
157 /**
158  * Set the context's default PSK hint and/or key for a server.
159  *
160  * @deprecated Use coap_context_set_psk2() instead.
161  *
162  * @param context The current coap_context_t object.
163  * @param hint    The default PSK server hint sent to a client. If NULL, PSK
164  *                authentication is disabled. Empty string is a valid hint.
165  * @param key     The default PSK key. If NULL, PSK authentication will fail.
166  * @param key_len The default PSK key's length. If @p 0, PSK authentication will
167  *                fail.
168  *
169  * @return @c 1 if successful, else @c 0.
170  */
171 int coap_context_set_psk(coap_context_t *context, const char *hint,
172                          const uint8_t *key, size_t key_len);
173 
174 /**
175  * Set the context's default PSK hint and/or key for a server.
176  *
177  * @param context    The current coap_context_t object.
178  * @param setup_data If NULL, PSK authentication will fail. PSK
179  *                   information required.
180  *
181  * @return @c 1 if successful, else @c 0.
182  */
183 int coap_context_set_psk2(coap_context_t *context,
184                           coap_dtls_spsk_t *setup_data);
185 
186 /**
187  * Set the context's default PKI information for a server.
188  *
189  * @param context        The current coap_context_t object.
190  * @param setup_data     If NULL, PKI authentication will fail. Certificate
191  *                       information required.
192  *
193  * @return @c 1 if successful, else @c 0.
194  */
195 int coap_context_set_pki(coap_context_t *context,
196                          const coap_dtls_pki_t *setup_data);
197 
198 /**
199  * Set the context's default Root CA information for a client or server.
200  *
201  * @param context        The current coap_context_t object.
202  * @param ca_file        If not NULL, is the full path name of a PEM encoded
203  *                       file containing all the Root CAs to be used.
204  * @param ca_dir         If not NULL, points to a directory containing PEM
205  *                       encoded files containing all the Root CAs to be used.
206  *
207  * @return @c 1 if successful, else @c 0.
208  */
209 int coap_context_set_pki_root_cas(coap_context_t *context,
210                                   const char *ca_file,
211                                   const char *ca_dir);
212 
213 /**
214  * Set the context keepalive timer for sessions.
215  * A keepalive message will be sent after if a session has been inactive,
216  * i.e. no packet sent or received, for the given number of seconds.
217  * For unreliable protocols, a CoAP Empty message will be sent. If a
218  * CoAP RST is not received, the CoAP Empty messages will get resent based
219  * on the Confirmable retry parameters until there is a failure timeout,
220  * at which point the session will be considered as disconnected.
221  * For reliable protocols, a CoAP PING message will be sent. If a CoAP PONG
222  * has not been received before the next PING is due to be sent, the session
223  * will be considered as disconnected.
224  *
225  * @param context        The coap_context_t object.
226  * @param seconds        Number of seconds for the inactivity timer, or zero
227  *                       to disable CoAP-level keepalive messages.
228  */
229 void coap_context_set_keepalive(coap_context_t *context, unsigned int seconds);
230 
231 /**
232  * Set the maximum token size (RFC8974).
233  *
234  * @param context        The coap_context_t object.
235  * @param max_token_size The maximum token size.  A value between 8 and 65804
236  *                       inclusive.
237  */
238 void coap_context_set_max_token_size(coap_context_t *context,
239                                      size_t max_token_size);
240 
241 /**
242  * Get the libcoap internal file descriptor for using in an application's
243  * select() or returned as an event in an application's epoll_wait() call.
244  *
245  * @param context        The coap_context_t object.
246  *
247  * @return The libcoap file descriptor or @c -1 if epoll is not available.
248  */
249 int coap_context_get_coap_fd(const coap_context_t *context);
250 
251 /**
252  * Get listening endpoints
253  *
254  * @param context The coap_context_t object.
255  *
256  * @return listening endpoint list.
257  */
258 coap_endpoint_t *coap_context_get_endpoint(const coap_context_t *context);
259 
260 /**
261  * Set the maximum idle sessions count. The number of server sessions that
262  * are currently not in use. If this number is exceeded, the least recently
263  * used server session is completely removed.
264  * 0 (the default) means that the number is not monitored.
265  *
266  * @param context           The coap_context_t object.
267  * @param max_idle_sessions The maximum idle session count.
268  */
269 void coap_context_set_max_idle_sessions(coap_context_t *context,
270                                         unsigned int max_idle_sessions);
271 
272 /**
273  * Get the maximum idle sessions count.
274  *
275  * @param context The coap_context_t object.
276  *
277  * @return The count of max idle sessions.
278  */
279 unsigned int coap_context_get_max_idle_sessions(const coap_context_t *context);
280 
281 /**
282  * Set the session timeout value. The number of seconds of inactivity after
283  * which an unused server session will be closed.
284  * 0 means use default (300 secs).
285  *
286  * @param context         The coap_context_t object.
287  * @param session_timeout The session timeout value.
288  */
289 void coap_context_set_session_timeout(coap_context_t *context,
290                                       unsigned int session_timeout);
291 
292 /**
293  * Get the session timeout value
294  *
295  * @param context The coap_context_t object.
296  *
297  * @return The session timeout value.
298  */
299 unsigned int coap_context_get_session_timeout(const coap_context_t *context);
300 
301 /**
302  * Set the CSM timeout value. The number of seconds to wait for a (TCP) CSM
303  * negotiation response from the peer.
304  * 0 (the default) means use wait forever.
305  *
306  * @param context    The coap_context_t object.
307  * @param csm_tmeout The CSM timeout value.
308  */
309 void coap_context_set_csm_timeout(coap_context_t *context,
310                                   unsigned int csm_tmeout);
311 
312 /**
313  * Get the CSM timeout value
314  *
315  * @param context The coap_context_t object.
316  *
317  * @return The CSM timeout value.
318  */
319 unsigned int coap_context_get_csm_timeout(const coap_context_t *context);
320 
321 /**
322  * Set the CSM max session size value. The largest PDU that can be received.
323  *
324  * @param context    The coap_context_t object.
325  * @param csm_max_message_size The CSM max message size value.
326  */
327 void coap_context_set_csm_max_message_size(coap_context_t *context,
328                                            uint32_t csm_max_message_size);
329 
330 /**
331  * Get the CSM max session size  value
332  *
333  * @param context The coap_context_t object.
334  *
335  * @return The CSM max session size  value.
336  */
337 uint32_t coap_context_get_csm_max_message_size(const coap_context_t *context);
338 
339 /**
340  * Set the maximum number of sessions in (D)TLS handshake value. If this number
341  * is exceeded, the least recently used server session in handshake is
342  * completely removed.
343  * 0 (the default) means that the number is not monitored.
344  *
345  * @param context         The coap_context_t object.
346  * @param max_handshake_sessions The maximum number of sessions in handshake.
347  */
348 void coap_context_set_max_handshake_sessions(coap_context_t *context,
349                                              unsigned int max_handshake_sessions);
350 
351 /**
352  * Get the session timeout value
353  *
354  * @param context The coap_context_t object.
355  *
356  * @return The maximim number of sessions in (D)TLS handshake value.
357  */
358 unsigned int coap_context_get_max_handshake_sessions(const coap_context_t *context);
359 
360 /**
361  * Returns a new message id and updates @p session->tx_mid accordingly. The
362  * message id is returned in network byte order to make it easier to read in
363  * tracing tools.
364  *
365  * @param session The current coap_session_t object.
366  *
367  * @return        Incremented message id in network byte order.
368  */
369 uint16_t coap_new_message_id(coap_session_t *session);
370 
371 /**
372  * CoAP stack context must be released with coap_free_context(). This function
373  * clears all entries from the receive queue and send queue and deletes the
374  * resources that have been registered with @p context, and frees the attached
375  * endpoints.
376  *
377  * @param context The current coap_context_t object to free off.
378  */
379 void coap_free_context(coap_context_t *context);
380 
381 /**
382  * Stores @p data with the given CoAP context. This function
383  * overwrites any value that has previously been stored with @p
384  * context.
385  *
386  * @param context The CoAP context.
387  * @param data The data to store with wih the context. Note that this data
388  *             must be valid during the lifetime of @p context.
389  */
390 void coap_set_app_data(coap_context_t *context, void *data);
391 
392 /**
393  * Returns any application-specific data that has been stored with @p
394  * context using the function coap_set_app_data(). This function will
395  * return @c NULL if no data has been stored.
396  *
397  * @param context The CoAP context.
398  *
399  * @return The data previously stored or @c NULL if not data stored.
400  */
401 void *coap_get_app_data(const coap_context_t *context);
402 
403 /**
404  * Creates a new ACK PDU with specified error @p code. The options specified by
405  * the filter expression @p opts will be copied from the original request
406  * contained in @p request. Unless @c SHORT_ERROR_RESPONSE was defined at build
407  * time, the textual reason phrase for @p code will be added as payload, with
408  * Content-Type @c 0.
409  * This function returns a pointer to the new response message, or @c NULL on
410  * error. The storage allocated for the new message must be released with
411  * coap_free().
412  *
413  * @param request Specification of the received (confirmable) request.
414  * @param code    The error code to set.
415  * @param opts    An option filter that specifies which options to copy from
416  *                the original request in @p node.
417  *
418  * @return        A pointer to the new message or @c NULL on error.
419  */
420 coap_pdu_t *coap_new_error_response(const coap_pdu_t *request,
421                                     coap_pdu_code_t code,
422                                     coap_opt_filter_t *opts);
423 
424 /**
425  * Sends an error response with code @p code for request @p request to @p dst.
426  * @p opts will be passed to coap_new_error_response() to copy marked options
427  * from the request. This function returns the message id if the message was
428  * sent, or @c COAP_INVALID_MID otherwise.
429  *
430  * @param session         The CoAP session.
431  * @param request         The original request to respond to.
432  * @param code            The response code.
433  * @param opts            A filter that specifies the options to copy from the
434  *                        @p request.
435  *
436  * @return                The message id if the message was sent, or @c
437  *                        COAP_INVALID_MID otherwise.
438  */
439 coap_mid_t coap_send_error(coap_session_t *session,
440                            const coap_pdu_t *request,
441                            coap_pdu_code_t code,
442                            coap_opt_filter_t *opts);
443 
444 /**
445  * Helper function to create and send a message with @p type (usually ACK or
446  * RST). This function returns @c COAP_INVALID_MID when the message was not
447  * sent, a valid transaction id otherwise.
448  *
449  * @param session         The CoAP session.
450  * @param request         The request that should be responded to.
451  * @param type            Which type to set.
452  * @return                message id on success or @c COAP_INVALID_MID
453  *                        otherwise.
454  */
455 coap_mid_t coap_send_message_type(coap_session_t *session, const coap_pdu_t *request,
456                                   coap_pdu_type_t type);
457 
458 /**
459  * Sends an ACK message with code @c 0 for the specified @p request to @p dst.
460  * This function returns the corresponding message id if the message was
461  * sent or @c COAP_INVALID_MID on error.
462  *
463  * @param session         The CoAP session.
464  * @param request         The request to be acknowledged.
465  *
466  * @return                The message id if ACK was sent or @c
467  *                        COAP_INVALID_MID on error.
468  */
469 coap_mid_t coap_send_ack(coap_session_t *session, const coap_pdu_t *request);
470 
471 /**
472  * Sends an RST message with code @c 0 for the specified @p request to @p dst.
473  * This function returns the corresponding message id if the message was
474  * sent or @c COAP_INVALID_MID on error.
475  *
476  * @param session         The CoAP session.
477  * @param request         The request to be reset.
478  *
479  * @return                The message id if RST was sent or @c
480  *                        COAP_INVALID_MID on error.
481  */
482 COAP_STATIC_INLINE coap_mid_t
coap_send_rst(coap_session_t * session,const coap_pdu_t * request)483 coap_send_rst(coap_session_t *session, const coap_pdu_t *request) {
484   return coap_send_message_type(session, request, COAP_MESSAGE_RST);
485 }
486 
487 /**
488 * Sends a CoAP message to given peer. The memory that is
489 * allocated for the pdu will be released by coap_send().
490 * The caller must not use or delete the pdu after calling coap_send().
491 *
492 * @param session         The CoAP session.
493 * @param pdu             The CoAP PDU to send.
494 *
495 * @return                The message id of the sent message or @c
496 *                        COAP_INVALID_MID on error.
497 */
498 coap_mid_t coap_send(coap_session_t *session, coap_pdu_t *pdu);
499 
500 #define coap_send_large(session, pdu) coap_send(session, pdu)
501 
502 /**
503  * Invokes the event handler of @p context for the given @p event and
504  * @p data.
505  *
506  * @param context The CoAP context whose event handler is to be called.
507  * @param event   The event to deliver.
508  * @param session The session related to @p event.
509  * @return The result from the associated event handler or 0 if none was
510  * registered.
511  */
512 int coap_handle_event(coap_context_t *context,
513                       coap_event_t event,
514                       coap_session_t *session);
515 /**
516  * Returns 1 if there are no messages to send or to dispatch in the context's
517  * queues.
518  *
519  * @param context The CoAP context to check.
520  *
521  * @return @c 0 if there are still pending transmits else @c 1 if nothing
522  *         queued for transmission.  Note that @c 0 does not mean there has
523  *         been a response to a transmitted request.
524  */
525 int coap_can_exit(coap_context_t *context);
526 
527 /**
528  * Returns the current value of an internal tick counter. The counter counts \c
529  * COAP_TICKS_PER_SECOND ticks every second.
530  */
531 void coap_ticks(coap_tick_t *);
532 
533 /**
534  * Function interface for joining a multicast group for listening for the
535  * currently defined endpoints that are UDP.
536  *
537  * @param ctx       The current context.
538  * @param groupname The name of the group that is to be joined for listening.
539  * @param ifname    Network interface to join the group on, or NULL if first
540  *                  appropriate interface is to be chosen by the O/S.
541  *
542  * @return       0 on success, -1 on error
543  */
544 int coap_join_mcast_group_intf(coap_context_t *ctx, const char *groupname,
545                                const char *ifname);
546 
547 #define coap_join_mcast_group(ctx, groupname) \
548   (coap_join_mcast_group_intf(ctx, groupname, NULL))
549 
550 /**
551  * Function interface for defining the hop count (ttl) for sending
552  * multicast traffic
553  *
554  * @param session The current session.
555  * @param hops    The number of hops (ttl) to use before the multicast
556  *                packet expires.
557  *
558  * @return       1 on success, 0 on error
559  */
560 int coap_mcast_set_hops(coap_session_t *session, size_t hops);
561 
562 /**
563  * Function interface to enable processing mcast requests on a per resource
564  * basis.  This then enables a set of configuration flags set up when
565  * configuring the resources (coap_resource_init()).
566  *
567  * @param context The current context.
568  */
569 void coap_mcast_per_resource(coap_context_t *context);
570 
571 /**@}*/
572 
573 /**
574  * @ingroup application_api
575  * @defgroup app_io Application I/O Handling
576  * API for Application Input / Output checking
577  * @{
578  */
579 
580 #define COAP_IO_WAIT    0
581 #define COAP_IO_NO_WAIT ((uint32_t)-1)
582 
583 /**
584  * The main I/O processing function.  All pending network I/O is completed,
585  * and then optionally waits for the next input packet.
586  *
587  * This internally calls coap_io_prepare_io(), then select() for the appropriate
588  * sockets, updates COAP_SOCKET_CAN_xxx where appropriate and then calls
589  * coap_io_do_io() before returning with the time spent in the function.
590  *
591  * Alternatively, if libcoap is compiled with epoll support, this internally
592  * calls coap_io_prepare_epoll(), then epoll_wait() for waiting for any file
593  * descriptors that have (internally) been set up with epoll_ctl() and
594  * finally coap_io_do_epoll() before returning with the time spent in the
595  * function.
596  *
597  * @param ctx The CoAP context
598  * @param timeout_ms Minimum number of milliseconds to wait for new packets
599  *                   before returning after doing any processing.
600  *                   If COAP_IO_WAIT, the call will block until the next
601  *                   internal action (e.g. packet retransmit) if any, or block
602  *                   until the next packet is received whichever is the sooner
603  *                   and do the necessary processing.
604  *                   If COAP_IO_NO_WAIT, the function will return immediately
605  *                   after processing without waiting for any new input
606  *                   packets to arrive.
607  *
608  * @return Number of milliseconds spent in function or @c -1 if there was
609  *         an error
610  */
611 int coap_io_process(coap_context_t *ctx, uint32_t timeout_ms);
612 
613 /**
614  * The main message processing loop with additional fds for internal select.
615  *
616  * @param ctx The CoAP context
617  * @param timeout_ms Minimum number of milliseconds to wait for new packets
618  *                   before returning after doing any processing.
619  *                   If COAP_IO_WAIT, the call will block until the next
620  *                   internal action (e.g. packet retransmit) if any, or block
621  *                   until the next packet is received whichever is the sooner
622  *                   and do the necessary processing.
623  *                   If COAP_IO_NO_WAIT, the function will return immediately
624  *                   after processing without waiting for any new input
625  *                   packets to arrive.
626  * @param nfds      The maximum FD set in readfds, writefds or exceptfds
627  *                  plus one,
628  * @param readfds   Read FDs to additionally check for in internal select()
629  *                  or NULL if not required.
630  * @param writefds  Write FDs to additionally check for in internal select()
631  *                  or NULL if not required.
632  * @param exceptfds Except FDs to additionally check for in internal select()
633  *                  or NULL if not required.
634  *
635  *
636  * @return Number of milliseconds spent in coap_io_process_with_fds, or @c -1
637  *         if there was an error.  If defined, readfds, writefds, exceptfds
638  *         are updated as returned by the internal select() call.
639  */
640 int coap_io_process_with_fds(coap_context_t *ctx, uint32_t timeout_ms,
641                              int nfds, fd_set *readfds, fd_set *writefds,
642                              fd_set *exceptfds);
643 
644 /**
645  * Check to see if there is any i/o pending for the @p context.
646  *
647  * This includes Observe active (client) and partial large block transfers.
648  *
649  * coap_io_process() is called internally to try to send outstanding
650  * data as well as process any packets just received.
651  *
652  * @param context The CoAP context.
653  *
654  * @return @c 1 I/O still pending, @c 0 no I/O pending.
655  */
656 int coap_io_pending(coap_context_t *context);
657 
658 /**@}*/
659 
660 /**
661  * @ingroup internal_api
662  * @defgroup app_io_internal Application I/O Handling
663  * Internal API for Application Input / Output checking
664  * @{
665  */
666 
667 /**
668 * Iterates through all the coap_socket_t structures embedded in endpoints or
669 * sessions associated with the @p ctx to determine which are wanting any
670 * read, write, accept or connect I/O (COAP_SOCKET_WANT_xxx is set). If set,
671 * the coap_socket_t is added to the @p sockets.
672 *
673 * Any now timed out delayed packet is transmitted, along with any packets
674 * associated with requested observable response.
675 *
676 * In addition, it returns when the next expected I/O is expected to take place
677 * (e.g. a packet retransmit).
678 *
679 * Prior to calling coap_io_do_io(), the @p sockets must be tested to see
680 * if any of the COAP_SOCKET_WANT_xxx have the appropriate information and if
681 * so, COAP_SOCKET_CAN_xxx is set. This typically will be done after using a
682 * select() call.
683 *
684 * Note: If epoll support is compiled into libcoap, coap_io_prepare_epoll() must
685 * be used instead of coap_io_prepare_io().
686 *
687 * Internal function.
688 *
689 * @param ctx The CoAP context
690 * @param sockets Array of socket descriptors, filled on output
691 * @param max_sockets Size of socket array.
692 * @param num_sockets Pointer to the number of valid entries in the socket
693 *                    arrays on output.
694 * @param now Current time.
695 *
696 * @return timeout Maxmimum number of milliseconds that can be used by a
697 *                 select() to wait for network events or 0 if wait should be
698 *                 forever.
699 */
700 unsigned int coap_io_prepare_io(coap_context_t *ctx,
701                                 coap_socket_t *sockets[],
702                                 unsigned int max_sockets,
703                                 unsigned int *num_sockets,
704                                 coap_tick_t now
705                                );
706 
707 /**
708  * Processes any outstanding read, write, accept or connect I/O as indicated
709  * in the coap_socket_t structures (COAP_SOCKET_CAN_xxx set) embedded in
710  * endpoints or sessions associated with @p ctx.
711  *
712  * Note: If epoll support is compiled into libcoap, coap_io_do_epoll() must
713  * be used instead of coap_io_do_io().
714  *
715  * Internal function.
716  *
717  * @param ctx The CoAP context
718  * @param now Current time
719  */
720 void coap_io_do_io(coap_context_t *ctx, coap_tick_t now);
721 
722 /**
723  * Any now timed out delayed packet is transmitted, along with any packets
724  * associated with requested observable response.
725  *
726  * In addition, it returns when the next expected I/O is expected to take place
727  * (e.g. a packet retransmit).
728  *
729  * Note: If epoll support is compiled into libcoap, coap_io_prepare_epoll() must
730  * be used instead of coap_io_prepare_io().
731  *
732  * Internal function.
733  *
734  * @param ctx The CoAP context
735  * @param now Current time.
736  *
737  * @return timeout Maxmimum number of milliseconds that can be used by a
738  *                 epoll_wait() to wait for network events or 0 if wait should be
739  *                 forever.
740  */
741 unsigned int coap_io_prepare_epoll(coap_context_t *ctx, coap_tick_t now);
742 
743 struct epoll_event;
744 
745 /**
746  * Process all the epoll events
747  *
748  * Note: If epoll support is compiled into libcoap, coap_io_do_epoll() must
749  * be used instead of coap_io_do_io().
750  *
751  * Internal function
752  *
753  * @param ctx    The current CoAP context.
754  * @param events The list of events returned from an epoll_wait() call.
755  * @param nevents The number of events.
756  *
757  */
758 void coap_io_do_epoll(coap_context_t *ctx, struct epoll_event *events,
759                       size_t nevents);
760 
761 /**@}*/
762 
763 /**
764  * @ingroup application_api
765  * @defgroup lwip LwIP specific API
766  * API for LwIP interface
767  * @{
768  */
769 
770 /**
771  * Dump the current state of the LwIP memory pools.
772  *
773  * Requires both MEMP_STATS and LWIP_STATS_DISPLAY to be defined as 1
774  * in lwipopts.h
775  *
776  * @param log_level The logging level to use.
777  *
778  */
779 void coap_lwip_dump_memory_pools(coap_log_t log_level);
780 
781 /**
782  * LwIP callback handler that can be used to wait / timeout for the
783  * next input packet.
784  *
785  * @param arg The argument passed to the coap_lwip_set_input_wait_handler()
786  *            function.
787  * @param milli_secs Suggested number of milli secs to wait before returning
788  *                   if no input.
789  *
790  * @return @c 1 if packet received, @c 0 for timeout, else @c -1 on error.
791  */
792 typedef int (*coap_lwip_input_wait_handler_t)(void *arg, uint32_t milli_secs);
793 
794 /**
795  * Set up a wait / timeout callback handler for use when
796  * the application calls coap_io_process().
797  *
798  * @param context   The coap context to associate this handler with.
799  * @param handler   The handler to call while waiting for input.
800  * @param input_arg The argument to pass into handler().
801  *
802  */
803 void coap_lwip_set_input_wait_handler(coap_context_t *context,
804                                       coap_lwip_input_wait_handler_t handler,
805                                       void *input_arg);
806 
807 /**@}*/
808 
809 /**
810  * @deprecated Use coap_io_process() instead.
811  *
812  * This function just calls coap_io_process().
813  *
814  * @param ctx The CoAP context
815  * @param timeout_ms Minimum number of milliseconds to wait for new packets
816  *                   before returning after doing any processing.
817  *                   If COAP_IO_WAIT, the call will block until the next
818  *                   internal action (e.g. packet retransmit) if any, or block
819  *                   until the next packet is received whichever is the sooner
820  *                   and do the necessary processing.
821  *                   If COAP_IO_NO_WAIT, the function will return immediately
822  *                   after processing without waiting for any new input
823  *                   packets to arrive.
824  *
825  * @return Number of milliseconds spent in function or @c -1 if there was
826  *         an error
827  */
828 COAP_STATIC_INLINE COAP_DEPRECATED int
coap_run_once(coap_context_t * ctx,uint32_t timeout_ms)829 coap_run_once(coap_context_t *ctx, uint32_t timeout_ms) {
830   return coap_io_process(ctx, timeout_ms);
831 }
832 
833 /**
834 * @deprecated Use coap_io_prepare_io() instead.
835 *
836 * This function just calls coap_io_prepare_io().
837 *
838 * Internal function.
839 *
840 * @param ctx The CoAP context
841 * @param sockets Array of socket descriptors, filled on output
842 * @param max_sockets Size of socket array.
843 * @param num_sockets Pointer to the number of valid entries in the socket
844 *                    arrays on output.
845 * @param now Current time.
846 *
847 * @return timeout Maxmimum number of milliseconds that can be used by a
848 *                 select() to wait for network events or 0 if wait should be
849 *                 forever.
850 */
851 COAP_STATIC_INLINE COAP_DEPRECATED unsigned int
coap_write(coap_context_t * ctx,coap_socket_t * sockets[],unsigned int max_sockets,unsigned int * num_sockets,coap_tick_t now)852 coap_write(coap_context_t *ctx,
853            coap_socket_t *sockets[],
854            unsigned int max_sockets,
855            unsigned int *num_sockets,
856            coap_tick_t now
857           ) {
858   return coap_io_prepare_io(ctx, sockets, max_sockets, num_sockets, now);
859 }
860 
861 /**
862  * @deprecated Use coap_io_do_io() instead.
863  *
864  * This function just calls coap_io_do_io().
865  *
866  * Internal function.
867  *
868  * @param ctx The CoAP context
869  * @param now Current time
870  */
871 COAP_STATIC_INLINE COAP_DEPRECATED void
coap_read(coap_context_t * ctx,coap_tick_t now)872 coap_read(coap_context_t *ctx, coap_tick_t now
873          ) {
874   coap_io_do_io(ctx, now);
875 }
876 
877 /* Old definitions which may be hanging around in old code - be helpful! */
878 #define COAP_RUN_NONBLOCK COAP_RUN_NONBLOCK_deprecated_use_COAP_IO_NO_WAIT
879 #define COAP_RUN_BLOCK COAP_RUN_BLOCK_deprecated_use_COAP_IO_WAIT
880 
881 #endif /* COAP_NET_H_ */
882