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