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 uint16_t coap_get_message_id(coap_session_t *session);
371
372 /**
373 * CoAP stack context must be released with coap_free_context(). This function
374 * clears all entries from the receive queue and send queue and deletes the
375 * resources that have been registered with @p context, and frees the attached
376 * endpoints.
377 *
378 * @param context The current coap_context_t object to free off.
379 */
380 void coap_free_context(coap_context_t *context);
381
382 /**
383 * Stores @p data with the given CoAP context. This function
384 * overwrites any value that has previously been stored with @p
385 * context.
386 *
387 * @param context The CoAP context.
388 * @param data The data to store with wih the context. Note that this data
389 * must be valid during the lifetime of @p context.
390 */
391 void coap_set_app_data(coap_context_t *context, void *data);
392
393 /**
394 * Returns any application-specific data that has been stored with @p
395 * context using the function coap_set_app_data(). This function will
396 * return @c NULL if no data has been stored.
397 *
398 * @param context The CoAP context.
399 *
400 * @return The data previously stored or @c NULL if not data stored.
401 */
402 void *coap_get_app_data(const coap_context_t *context);
403
404 /**
405 * Creates a new ACK PDU with specified error @p code. The options specified by
406 * the filter expression @p opts will be copied from the original request
407 * contained in @p request. Unless @c SHORT_ERROR_RESPONSE was defined at build
408 * time, the textual reason phrase for @p code will be added as payload, with
409 * Content-Type @c 0.
410 * This function returns a pointer to the new response message, or @c NULL on
411 * error. The storage allocated for the new message must be released with
412 * coap_free().
413 *
414 * @param request Specification of the received (confirmable) request.
415 * @param code The error code to set.
416 * @param opts An option filter that specifies which options to copy from
417 * the original request in @p node.
418 *
419 * @return A pointer to the new message or @c NULL on error.
420 */
421 coap_pdu_t *coap_new_error_response(const coap_pdu_t *request,
422 coap_pdu_code_t code,
423 coap_opt_filter_t *opts);
424
425 /**
426 * Sends an error response with code @p code for request @p request to @p dst.
427 * @p opts will be passed to coap_new_error_response() to copy marked options
428 * from the request. This function returns the message id if the message was
429 * sent, or @c COAP_INVALID_MID otherwise.
430 *
431 * @param session The CoAP session.
432 * @param request The original request to respond to.
433 * @param code The response code.
434 * @param opts A filter that specifies the options to copy from the
435 * @p request.
436 *
437 * @return The message id if the message was sent, or @c
438 * COAP_INVALID_MID otherwise.
439 */
440 coap_mid_t coap_send_error(coap_session_t *session,
441 const coap_pdu_t *request,
442 coap_pdu_code_t code,
443 coap_opt_filter_t *opts);
444
445 /**
446 * Helper function to create and send a message with @p type (usually ACK or
447 * RST). This function returns @c COAP_INVALID_MID when the message was not
448 * sent, a valid transaction id otherwise.
449 *
450 * @param session The CoAP session.
451 * @param request The request that should be responded to.
452 * @param type Which type to set.
453 * @return message id on success or @c COAP_INVALID_MID
454 * otherwise.
455 */
456 coap_mid_t coap_send_message_type(coap_session_t *session, const coap_pdu_t *request,
457 coap_pdu_type_t type);
458
459 /**
460 * Sends an ACK message with code @c 0 for the specified @p request to @p dst.
461 * This function returns the corresponding message id if the message was
462 * sent or @c COAP_INVALID_MID on error.
463 *
464 * @param session The CoAP session.
465 * @param request The request to be acknowledged.
466 *
467 * @return The message id if ACK was sent or @c
468 * COAP_INVALID_MID on error.
469 */
470 coap_mid_t coap_send_ack(coap_session_t *session, const coap_pdu_t *request);
471
472 /**
473 * Sends an RST message with code @c 0 for the specified @p request to @p dst.
474 * This function returns the corresponding message id if the message was
475 * sent or @c COAP_INVALID_MID on error.
476 *
477 * @param session The CoAP session.
478 * @param request The request to be reset.
479 *
480 * @return The message id if RST was sent or @c
481 * COAP_INVALID_MID on error.
482 */
483 COAP_STATIC_INLINE coap_mid_t
coap_send_rst(coap_session_t * session,const coap_pdu_t * request)484 coap_send_rst(coap_session_t *session, const coap_pdu_t *request) {
485 return coap_send_message_type(session, request, COAP_MESSAGE_RST);
486 }
487
488 /**
489 * Sends a CoAP message to given peer. The memory that is
490 * allocated for the pdu will be released by coap_send().
491 * The caller must not use or delete the pdu after calling coap_send().
492 *
493 * @param session The CoAP session.
494 * @param pdu The CoAP PDU to send.
495 *
496 * @return The message id of the sent message or @c
497 * COAP_INVALID_MID on error.
498 */
499 coap_mid_t coap_send(coap_session_t *session, coap_pdu_t *pdu);
500
501 #define coap_send_large(session, pdu) coap_send(session, pdu)
502
503 /**
504 * Invokes the event handler of @p context for the given @p event and
505 * @p data.
506 *
507 * @param context The CoAP context whose event handler is to be called.
508 * @param event The event to deliver.
509 * @param session The session related to @p event.
510 * @return The result from the associated event handler or 0 if none was
511 * registered.
512 */
513 int coap_handle_event(coap_context_t *context,
514 coap_event_t event,
515 coap_session_t *session);
516 /**
517 * Returns 1 if there are no messages to send or to dispatch in the context's
518 * queues.
519 *
520 * @param context The CoAP context to check.
521 *
522 * @return @c 0 if there are still pending transmits else @c 1 if nothing
523 * queued for transmission. Note that @c 0 does not mean there has
524 * been a response to a transmitted request.
525 */
526 int coap_can_exit(coap_context_t *context);
527
528 /**
529 * Returns the current value of an internal tick counter. The counter counts \c
530 * COAP_TICKS_PER_SECOND ticks every second.
531 */
532 void coap_ticks(coap_tick_t *);
533
534 /**
535 * Function interface for joining a multicast group for listening for the
536 * currently defined endpoints that are UDP.
537 *
538 * @param ctx The current context.
539 * @param groupname The name of the group that is to be joined for listening.
540 * @param ifname Network interface to join the group on, or NULL if first
541 * appropriate interface is to be chosen by the O/S.
542 *
543 * @return 0 on success, -1 on error
544 */
545 int coap_join_mcast_group_intf(coap_context_t *ctx, const char *groupname,
546 const char *ifname);
547
548 #define coap_join_mcast_group(ctx, groupname) \
549 (coap_join_mcast_group_intf(ctx, groupname, NULL))
550
551 /**
552 * Function interface for defining the hop count (ttl) for sending
553 * multicast traffic
554 *
555 * @param session The current session.
556 * @param hops The number of hops (ttl) to use before the multicast
557 * packet expires.
558 *
559 * @return 1 on success, 0 on error
560 */
561 int coap_mcast_set_hops(coap_session_t *session, size_t hops);
562
563 /**
564 * Function interface to enable processing mcast requests on a per resource
565 * basis. This then enables a set of configuration flags set up when
566 * configuring the resources (coap_resource_init()).
567 *
568 * @param context The current context.
569 */
570 void coap_mcast_per_resource(coap_context_t *context);
571
572 /**@}*/
573
574 /**
575 * @ingroup application_api
576 * @defgroup app_io Application I/O Handling
577 * API for Application Input / Output checking
578 * @{
579 */
580
581 #define COAP_IO_WAIT 0
582 #define COAP_IO_NO_WAIT ((uint32_t)-1)
583
584 /**
585 * The main I/O processing function. All pending network I/O is completed,
586 * and then optionally waits for the next input packet.
587 *
588 * This internally calls coap_io_prepare_io(), then select() for the appropriate
589 * sockets, updates COAP_SOCKET_CAN_xxx where appropriate and then calls
590 * coap_io_do_io() before returning with the time spent in the function.
591 *
592 * Alternatively, if libcoap is compiled with epoll support, this internally
593 * calls coap_io_prepare_epoll(), then epoll_wait() for waiting for any file
594 * descriptors that have (internally) been set up with epoll_ctl() and
595 * finally coap_io_do_epoll() before returning with the time spent in the
596 * function.
597 *
598 * @param ctx The CoAP context
599 * @param timeout_ms Minimum number of milliseconds to wait for new packets
600 * before returning after doing any processing.
601 * If COAP_IO_WAIT, the call will block until the next
602 * internal action (e.g. packet retransmit) if any, or block
603 * until the next packet is received whichever is the sooner
604 * and do the necessary processing.
605 * If COAP_IO_NO_WAIT, the function will return immediately
606 * after processing without waiting for any new input
607 * packets to arrive.
608 *
609 * @return Number of milliseconds spent in function or @c -1 if there was
610 * an error
611 */
612 int coap_io_process(coap_context_t *ctx, uint32_t timeout_ms);
613
614 /**
615 * The main message processing loop with additional fds for internal select.
616 *
617 * @param ctx The CoAP context
618 * @param timeout_ms Minimum number of milliseconds to wait for new packets
619 * before returning after doing any processing.
620 * If COAP_IO_WAIT, the call will block until the next
621 * internal action (e.g. packet retransmit) if any, or block
622 * until the next packet is received whichever is the sooner
623 * and do the necessary processing.
624 * If COAP_IO_NO_WAIT, the function will return immediately
625 * after processing without waiting for any new input
626 * packets to arrive.
627 * @param nfds The maximum FD set in readfds, writefds or exceptfds
628 * plus one,
629 * @param readfds Read FDs to additionally check for in internal select()
630 * or NULL if not required.
631 * @param writefds Write FDs to additionally check for in internal select()
632 * or NULL if not required.
633 * @param exceptfds Except FDs to additionally check for in internal select()
634 * or NULL if not required.
635 *
636 *
637 * @return Number of milliseconds spent in coap_io_process_with_fds, or @c -1
638 * if there was an error. If defined, readfds, writefds, exceptfds
639 * are updated as returned by the internal select() call.
640 */
641 int coap_io_process_with_fds(coap_context_t *ctx, uint32_t timeout_ms,
642 int nfds, fd_set *readfds, fd_set *writefds,
643 fd_set *exceptfds);
644
645 /**
646 * Check to see if there is any i/o pending for the @p context.
647 *
648 * This includes Observe active (client) and partial large block transfers.
649 *
650 * coap_io_process() is called internally to try to send outstanding
651 * data as well as process any packets just received.
652 *
653 * @param context The CoAP context.
654 *
655 * @return @c 1 I/O still pending, @c 0 no I/O pending.
656 */
657 int coap_io_pending(coap_context_t *context);
658
659 /**@}*/
660
661 /**
662 * @ingroup internal_api
663 * @defgroup app_io_internal Application I/O Handling
664 * Internal API for Application Input / Output checking
665 * @{
666 */
667
668 /**
669 * Iterates through all the coap_socket_t structures embedded in endpoints or
670 * sessions associated with the @p ctx to determine which are wanting any
671 * read, write, accept or connect I/O (COAP_SOCKET_WANT_xxx is set). If set,
672 * the coap_socket_t is added to the @p sockets.
673 *
674 * Any now timed out delayed packet is transmitted, along with any packets
675 * associated with requested observable response.
676 *
677 * In addition, it returns when the next expected I/O is expected to take place
678 * (e.g. a packet retransmit).
679 *
680 * Prior to calling coap_io_do_io(), the @p sockets must be tested to see
681 * if any of the COAP_SOCKET_WANT_xxx have the appropriate information and if
682 * so, COAP_SOCKET_CAN_xxx is set. This typically will be done after using a
683 * select() call.
684 *
685 * Note: If epoll support is compiled into libcoap, coap_io_prepare_epoll() must
686 * be used instead of coap_io_prepare_io().
687 *
688 * Internal function.
689 *
690 * @param ctx The CoAP context
691 * @param sockets Array of socket descriptors, filled on output
692 * @param max_sockets Size of socket array.
693 * @param num_sockets Pointer to the number of valid entries in the socket
694 * arrays on output.
695 * @param now Current time.
696 *
697 * @return timeout Maxmimum number of milliseconds that can be used by a
698 * select() to wait for network events or 0 if wait should be
699 * forever.
700 */
701 unsigned int coap_io_prepare_io(coap_context_t *ctx,
702 coap_socket_t *sockets[],
703 unsigned int max_sockets,
704 unsigned int *num_sockets,
705 coap_tick_t now
706 );
707
708 /**
709 * Processes any outstanding read, write, accept or connect I/O as indicated
710 * in the coap_socket_t structures (COAP_SOCKET_CAN_xxx set) embedded in
711 * endpoints or sessions associated with @p ctx.
712 *
713 * Note: If epoll support is compiled into libcoap, coap_io_do_epoll() must
714 * be used instead of coap_io_do_io().
715 *
716 * Internal function.
717 *
718 * @param ctx The CoAP context
719 * @param now Current time
720 */
721 void coap_io_do_io(coap_context_t *ctx, coap_tick_t now);
722
723 /**
724 * Any now timed out delayed packet is transmitted, along with any packets
725 * associated with requested observable response.
726 *
727 * In addition, it returns when the next expected I/O is expected to take place
728 * (e.g. a packet retransmit).
729 *
730 * Note: If epoll support is compiled into libcoap, coap_io_prepare_epoll() must
731 * be used instead of coap_io_prepare_io().
732 *
733 * Internal function.
734 *
735 * @param ctx The CoAP context
736 * @param now Current time.
737 *
738 * @return timeout Maxmimum number of milliseconds that can be used by a
739 * epoll_wait() to wait for network events or 0 if wait should be
740 * forever.
741 */
742 unsigned int coap_io_prepare_epoll(coap_context_t *ctx, coap_tick_t now);
743
744 struct epoll_event;
745
746 /**
747 * Process all the epoll events
748 *
749 * Note: If epoll support is compiled into libcoap, coap_io_do_epoll() must
750 * be used instead of coap_io_do_io().
751 *
752 * Internal function
753 *
754 * @param ctx The current CoAP context.
755 * @param events The list of events returned from an epoll_wait() call.
756 * @param nevents The number of events.
757 *
758 */
759 void coap_io_do_epoll(coap_context_t *ctx, struct epoll_event *events,
760 size_t nevents);
761
762 /**@}*/
763
764 /**
765 * @ingroup application_api
766 * @defgroup lwip LwIP specific API
767 * API for LwIP interface
768 * @{
769 */
770
771 /**
772 * Dump the current state of the LwIP memory pools.
773 *
774 * Requires both MEMP_STATS and LWIP_STATS_DISPLAY to be defined as 1
775 * in lwipopts.h
776 *
777 * @param log_level The logging level to use.
778 *
779 */
780 void coap_lwip_dump_memory_pools(coap_log_t log_level);
781
782 /**
783 * LwIP callback handler that can be used to wait / timeout for the
784 * next input packet.
785 *
786 * @param arg The argument passed to the coap_lwip_set_input_wait_handler()
787 * function.
788 * @param milli_secs Suggested number of milli secs to wait before returning
789 * if no input.
790 *
791 * @return @c 1 if packet received, @c 0 for timeout, else @c -1 on error.
792 */
793 typedef int (*coap_lwip_input_wait_handler_t)(void *arg, uint32_t milli_secs);
794
795 /**
796 * Set up a wait / timeout callback handler for use when
797 * the application calls coap_io_process().
798 *
799 * @param context The coap context to associate this handler with.
800 * @param handler The handler to call while waiting for input.
801 * @param input_arg The argument to pass into handler().
802 *
803 */
804 void coap_lwip_set_input_wait_handler(coap_context_t *context,
805 coap_lwip_input_wait_handler_t handler,
806 void *input_arg);
807
808 /**@}*/
809
810 /**
811 * @deprecated Use coap_io_process() instead.
812 *
813 * This function just calls coap_io_process().
814 *
815 * @param ctx The CoAP context
816 * @param timeout_ms Minimum number of milliseconds to wait for new packets
817 * before returning after doing any processing.
818 * If COAP_IO_WAIT, the call will block until the next
819 * internal action (e.g. packet retransmit) if any, or block
820 * until the next packet is received whichever is the sooner
821 * and do the necessary processing.
822 * If COAP_IO_NO_WAIT, the function will return immediately
823 * after processing without waiting for any new input
824 * packets to arrive.
825 *
826 * @return Number of milliseconds spent in function or @c -1 if there was
827 * an error
828 */
829 COAP_STATIC_INLINE COAP_DEPRECATED int
coap_run_once(coap_context_t * ctx,uint32_t timeout_ms)830 coap_run_once(coap_context_t *ctx, uint32_t timeout_ms) {
831 return coap_io_process(ctx, timeout_ms);
832 }
833
834 /**
835 * @deprecated Use coap_io_prepare_io() instead.
836 *
837 * This function just calls coap_io_prepare_io().
838 *
839 * Internal function.
840 *
841 * @param ctx The CoAP context
842 * @param sockets Array of socket descriptors, filled on output
843 * @param max_sockets Size of socket array.
844 * @param num_sockets Pointer to the number of valid entries in the socket
845 * arrays on output.
846 * @param now Current time.
847 *
848 * @return timeout Maxmimum number of milliseconds that can be used by a
849 * select() to wait for network events or 0 if wait should be
850 * forever.
851 */
852 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)853 coap_write(coap_context_t *ctx,
854 coap_socket_t *sockets[],
855 unsigned int max_sockets,
856 unsigned int *num_sockets,
857 coap_tick_t now
858 ) {
859 return coap_io_prepare_io(ctx, sockets, max_sockets, num_sockets, now);
860 }
861
862 /**
863 * @deprecated Use coap_io_do_io() instead.
864 *
865 * This function just calls coap_io_do_io().
866 *
867 * Internal function.
868 *
869 * @param ctx The CoAP context
870 * @param now Current time
871 */
872 COAP_STATIC_INLINE COAP_DEPRECATED void
coap_read(coap_context_t * ctx,coap_tick_t now)873 coap_read(coap_context_t *ctx, coap_tick_t now
874 ) {
875 coap_io_do_io(ctx, now);
876 }
877
878 /* Old definitions which may be hanging around in old code - be helpful! */
879 #define COAP_RUN_NONBLOCK COAP_RUN_NONBLOCK_deprecated_use_COAP_IO_NO_WAIT
880 #define COAP_RUN_BLOCK COAP_RUN_BLOCK_deprecated_use_COAP_IO_WAIT
881
882 #endif /* COAP_NET_H_ */
883