libcoap 4.3.5-develop-490e4e0
Loading...
Searching...
No Matches
coap_net.h
Go to the documentation of this file.
1/*
2 * coap_net.h -- CoAP context interface
3 *
4 * Copyright (C) 2010-2025 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
17#ifndef COAP_NET_H_
18#define COAP_NET_H_
19
20#include <stdlib.h>
21#include <string.h>
22
23#if !defined(WITH_LWIP) && !defined(WITH_CONTIKI) && !defined(RIOT_VERSION) && !defined(_WIN32)
24#include <sys/select.h>
25#endif /* ! WITH_LWIP && ! WITH_CONTIKI && ! RIOT_VERSION && ! _WIN32 */
26
27#ifdef WITH_LWIP
28#include <lwip/ip_addr.h>
29#endif
30
31#if defined(__ZEPHYR__) && !defined(__unix__) && !defined(__linux__)
32#include <zephyr/net/socket_select.h>
33#define fd_set zsock_fd_set
34#endif
35
36#include "coap_io.h"
37#include "coap_dtls.h"
38#include "coap_event.h"
39#include "coap_pdu.h"
40#include "coap_session.h"
41#include "coap_debug.h"
42
43#ifdef __cplusplus
44extern "C" {
45#endif
46
58
71 const coap_pdu_t *sent,
72 const coap_pdu_t *received,
73 const coap_mid_t mid);
74
83typedef void (*coap_nack_handler_t)(coap_session_t *session,
84 const coap_pdu_t *sent,
85 const coap_nack_reason_t reason,
86 const coap_mid_t mid);
87
95typedef void (*coap_ping_handler_t)(coap_session_t *session,
96 const coap_pdu_t *received,
97 const coap_mid_t mid);
98
106typedef void (*coap_pong_handler_t)(coap_session_t *session,
107 const coap_pdu_t *received,
108 const coap_mid_t mid);
109
118typedef coap_resource_t *(*coap_resource_dynamic_create_t)(coap_session_t *session,
119 const coap_pdu_t *request);
129
140 coap_nack_handler_t handler);
141
150 coap_ping_handler_t handler);
151
160 coap_pong_handler_t handler);
161
177 coap_resource_dynamic_create_t create_handler,
178 uint32_t dynamic_max);
179
192 coap_option_num_t number);
193
198
213COAP_API int coap_context_set_psk(coap_context_t *context, const char *hint,
214 const uint8_t *key, size_t key_len);
215
226 coap_dtls_spsk_t *setup_data);
227
238 const coap_dtls_pki_t *setup_data);
239
252 const char *ca_file,
253 const char *ca_dir);
254
263
280void coap_context_set_keepalive(coap_context_t *context, unsigned int seconds);
281
290int coap_context_set_cid_tuple_change(coap_context_t *context, uint8_t every);
291
300 size_t max_token_size);
301
310int coap_context_get_coap_fd(const coap_context_t *context);
311
322 unsigned int max_idle_sessions);
323
331unsigned int coap_context_get_max_idle_sessions(const coap_context_t *context);
332
342 unsigned int session_timeout);
343
361 unsigned int reconnect_time);
369unsigned int coap_context_get_session_timeout(const coap_context_t *context);
370
371/*
372 * Stop sending out observe subscriptons when calling coap_free_context().
373 *
374 * If this is not called, then 5.03 messages are sent out for every observe
375 * subscription when the context is freed off.
376 *
377 * @param context The coap_context_t object.
378 */
380
392 unsigned int csm_timeout);
393
404
415 unsigned int csm_timeout_ms);
416
424unsigned int coap_context_get_csm_timeout_ms(const coap_context_t *context);
425
433 uint32_t csm_max_message_size);
434
443
454 unsigned int max_handshake_sessions);
455
464
475
485
497COAP_DEPRECATED void coap_set_app_data(coap_context_t *context, void *data);
498
511
530 coap_pdu_code_t code,
531 coap_opt_filter_t *opts);
532
549 const coap_pdu_t *request,
550 coap_pdu_code_t code,
551 coap_opt_filter_t *opts);
552
565 coap_pdu_type_t type);
566
579
592
605
606#define coap_send_large(session, pdu) coap_send(session, pdu)
607
608/*
609 * Send a request PDU and wait for the response PDU.
610 *
611 * @param session The CoAP session.
612 * @param request_pdu The requesting PDU. If this PDU contains the Observe
613 * option, the unsolocited responses will get handled by the
614 * defined response handler. This PDU must be freed off by the
615 * caller after processing.
616 * @param response_pdu If there is a response, the response PDU is put here.
617 * This PDU must be freed off by the caller after processing.
618 * @param timeout_ms Positive maximum number of milliseconds to wait for response
619 * packet following the request. If there is a large block transfer
620 * this timeout is for between each request and response.
621 *
622 * @return 0 or +ve Time in function in ms after successful transfer (which can be
623 * bigger than timeout_ms).
624 * -1 Invalid timeout parameter
625 * -2 Failed to transmit PDU
626 * -3 Nack or Event handler invoked, cancelling request
627 * -4 coap_io_process returned error (fail to re-lock or select())
628 * -5 Response not received in the given time
629 * -6 Terminated by user
630 * -7 Client mode code not enabled
631 */
632COAP_API int coap_send_recv(coap_session_t *session, coap_pdu_t *request_pdu,
633 coap_pdu_t **response_pdu, uint32_t timeout_ms);
634
638void coap_send_recv_terminate(void);
639
651 coap_event_t event,
652 coap_session_t *session);
664
669void coap_ticks(coap_tick_t *);
670
682COAP_API int coap_join_mcast_group_intf(coap_context_t *ctx, const char *groupname,
683 const char *ifname);
684
685#define coap_join_mcast_group(ctx, groupname) \
686 (coap_join_mcast_group_intf(ctx, groupname, NULL))
687
699int coap_mcast_set_hops(coap_session_t *session, size_t hops);
700
709
720 void *data);
721
738COAP_API void *coap_context_set_app_data2(coap_context_t *context, void *data,
740
750void *coap_context_get_app_data(const coap_context_t *context);
751
761#define COAP_IO_WAIT 0
762#define COAP_IO_NO_WAIT ((uint32_t)-1)
763
792COAP_API int coap_io_process(coap_context_t *ctx, uint32_t timeout_ms);
793
794#if !defined(WITH_LWIP) && !defined(RIOT_VERSION) && !defined(WITH_CONTIKI)
822COAP_API int coap_io_process_with_fds(coap_context_t *ctx, uint32_t timeout_ms,
823 int nfds, fd_set *readfds, fd_set *writefds,
824 fd_set *exceptfds);
825#endif /* ! WITH_LWIP && ! RIOT_VERSION && ! WITH_CONTIKI */
826
840
875 coap_socket_t *sockets[],
876 unsigned int max_sockets,
877 unsigned int *num_sockets,
878 coap_tick_t now
879 );
880
895
916
917struct epoll_event;
918
932COAP_API void coap_io_do_epoll(coap_context_t *ctx, struct epoll_event *events,
933 size_t nevents);
934
943typedef void (*coap_io_process_thread_t)(void *arg);
944
969 coap_io_process_thread_t main_loop_code,
970 void *main_loop_code_arg, uint32_t timeout_ms,
971 uint32_t thread_count);
972
981
993 uint32_t thread_count);
994
1001
1013
1014/*
1015 * Get the current libcoap usage of file descriptors that are in a read or write pending state.
1016 *
1017 * @param context The current CoAP context.
1018 * @param read_fds Array to populate with file descriptors in the read pending state.
1019 * @param have_read_fds Updated wth the number of fds found in read pending state.
1020 * @param max_read_fds Maximum size of read_fds[] array.
1021 * @param write_fds Array to populate with file descriptors in the write pending state.
1022 * @param have_write_fds Updated wth the number of fds found in write pending state.
1023 * @param max_write_fds Maximum size of write_fds[] array.
1024 * @param rem_timeout_ms Remaining timeout time to next libcoap activity in milli-secs.
1025 *
1026 * @return @c 1 if successful, else @c 0 if error.
1027 */
1028COAP_API unsigned int coap_io_get_fds(coap_context_t *context, coap_fd_t read_fds[],
1029 unsigned int *have_read_fds,
1030 unsigned int max_read_fds,
1031 coap_fd_t write_fds[],
1032 unsigned int *have_write_fds,
1033 unsigned int max_write_fds,
1034 unsigned int *rem_timeout_ms);
1035
1046
1056
1059#if defined(WITH_LWIP) || defined(WITH_LWIP_MAN_CHECK) || defined(__DOXYGEN__)
1077
1089typedef int (*coap_lwip_input_wait_handler_t)(void *arg, uint32_t milli_secs);
1090
1102 void *input_arg);
1103
1105#endif /* WITH_LWIP || WITH_LWIP_MAN_CHECK || defined(__DOXYGEN__) */
1106
1126#define coap_run_once(ctx, timeout_ms) coap_io_process(ctx, timeout_ms)
1127
1146#define coap_write(ctx, sockets, max_sockets, num_sockets, now) \
1147 coap_io_prepare_io(ctx, sockets, max_sockets, num_sockets, now)
1148
1159#define coap_read(ctx, now) coap_io_do_io(ctx, now)
1160
1161/* Old definitions which may be hanging around in old code - be helpful! */
1162#define COAP_RUN_NONBLOCK COAP_RUN_NONBLOCK_deprecated_use_COAP_IO_NO_WAIT
1163#define COAP_RUN_BLOCK COAP_RUN_BLOCK_deprecated_use_COAP_IO_WAIT
1164
1165#ifdef __cplusplus
1166}
1167#endif
1168
1169#endif /* COAP_NET_H_ */
CoAP Logging support.
CoAP DTLS support.
Event handling.
Default network I/O functions.
uint16_t coap_socket_flags_t
Definition coap_io.h:57
coap_nack_reason_t
Definition coap_io.h:66
int coap_fd_t
Definition coap_io.h:51
#define COAP_API
uint16_t coap_option_num_t
Definition coap_option.h:24
Pre-defined constants that reflect defaults for CoAP.
Defines the application visible session information.
COAP_API int coap_io_process(coap_context_t *ctx, uint32_t timeout_ms)
The main I/O processing function.
COAP_API int coap_io_pending(coap_context_t *context)
Check to see if there is any i/o pending for the context.
Definition coap_io.c:749
int coap_io_process_configure_threads(coap_context_t *context, uint32_t thread_count)
Configure a defined number of threads to do the alternate coap_io_process() work with traffic load ba...
void coap_io_process_terminate_loop(void)
Terminate all the additional threads created by coap_io_process_loop() and break out of the main thre...
void coap_io_process_remove_threads(coap_context_t *context)
Release the coap_io_process() worker threads.
COAP_API int coap_io_process_loop(coap_context_t *context, coap_io_process_thread_t main_loop_code, void *main_loop_code_arg, uint32_t timeout_ms, uint32_t thread_count)
Do the coap_io_process() across thread_count threads.
COAP_API unsigned int coap_io_get_fds(coap_context_t *context, coap_fd_t read_fds[], unsigned int *have_read_fds, unsigned int max_read_fds, coap_fd_t write_fds[], unsigned int *have_write_fds, unsigned int max_write_fds, unsigned int *rem_timeout_ms)
Definition coap_io.c:612
COAP_API unsigned int coap_io_prepare_io(coap_context_t *ctx, coap_socket_t *sockets[], unsigned int max_sockets, unsigned int *num_sockets, coap_tick_t now)
Iterates through all the coap_socket_t structures embedded in endpoints or sessions associated with t...
Definition coap_io.c:270
COAP_API void coap_socket_set_flags(coap_socket_t *socket, coap_socket_flags_t flags)
Set the libcoap internal flags for a socket.
Definition coap_io.c:835
COAP_API unsigned int coap_io_prepare_epoll(coap_context_t *ctx, coap_tick_t now)
Any now timed out delayed packet is transmitted, along with any packets associated with requested obs...
Definition coap_io.c:209
COAP_API coap_fd_t coap_socket_get_fd(coap_socket_t *socket)
Get the libcoap internal file descriptor for a socket.
Definition coap_io.c:820
COAP_API int coap_io_process_with_fds(coap_context_t *ctx, uint32_t timeout_ms, int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds)
The main message processing loop with additional fds for internal select.
void(* coap_io_process_thread_t)(void *arg)
Main thread coap_io_process_loop activity.
Definition coap_net.h:943
COAP_API void coap_io_do_epoll(coap_context_t *ctx, struct epoll_event *events, size_t nevents)
Process all the epoll events.
Definition coap_net.c:2757
COAP_API void coap_io_do_io(coap_context_t *ctx, coap_tick_t now)
Processes any outstanding read, write, accept or connect I/O as indicated in the coap_socket_t struct...
Definition coap_net.c:2696
COAP_API coap_socket_flags_t coap_socket_get_flags(coap_socket_t *socket)
Get the libcoap internal flags for a socket.
Definition coap_io.c:830
uint64_t coap_tick_t
This data type represents internal timer ticks with COAP_TICKS_PER_SECOND resolution.
Definition coap_time.h:151
void coap_context_set_session_timeout(coap_context_t *context, unsigned int session_timeout)
Set the session timeout value.
Definition coap_net.c:558
unsigned int coap_context_get_max_handshake_sessions(const coap_context_t *context)
Get the session timeout value.
Definition coap_net.c:505
COAP_API int coap_join_mcast_group_intf(coap_context_t *ctx, const char *groupname, const char *ifname)
Function interface for joining a multicast group for listening for the currently defined endpoints th...
void(* coap_pong_handler_t)(coap_session_t *session, const coap_pdu_t *received, const coap_mid_t mid)
Received Pong handler that is used as callback in coap_context_t.
Definition coap_net.h:106
unsigned int coap_context_get_max_idle_sessions(const coap_context_t *context)
Get the maximum idle sessions count.
Definition coap_net.c:494
COAP_API int coap_send_recv(coap_session_t *session, coap_pdu_t *request_pdu, coap_pdu_t **response_pdu, uint32_t timeout_ms)
Definition coap_net.c:2105
coap_context_t * coap_new_context(const coap_address_t *listen_addr)
Creates a new coap_context_t object that will hold the CoAP stack status.
Definition coap_net.c:697
COAP_API coap_mid_t coap_send(coap_session_t *session, coap_pdu_t *pdu)
Sends a CoAP message to given peer.
Definition coap_net.c:1457
COAP_API int coap_context_set_pki(coap_context_t *context, const coap_dtls_pki_t *setup_data)
Set the context's default PKI information for a server.
void coap_mcast_per_resource(coap_context_t *context)
Function interface to enable processing mcast requests on a per resource basis.
coap_response_t(* coap_response_handler_t)(coap_session_t *session, const coap_pdu_t *sent, const coap_pdu_t *received, const coap_mid_t mid)
Response handler that is used as callback in coap_context_t.
Definition coap_net.h:70
COAP_API coap_mid_t coap_send_error(coap_session_t *session, const coap_pdu_t *request, coap_pdu_code_t code, coap_opt_filter_t *opts)
Sends an error response with code code for request request to dst.
Definition coap_net.c:1149
void coap_context_set_csm_max_message_size(coap_context_t *context, uint32_t csm_max_message_size)
Set the CSM max session size value.
Definition coap_net.c:540
COAP_DEPRECATED void coap_context_set_csm_timeout(coap_context_t *context, unsigned int csm_timeout)
Set the CSM timeout value.
Definition coap_net.c:512
void coap_send_recv_terminate(void)
Terminate any active coap_send_recv() sessions.
Definition coap_net.c:2100
coap_resource_t *(* coap_resource_dynamic_create_t)(coap_session_t *session, const coap_pdu_t *request)
Definition of resource dynamic creation handler function.
Definition coap_net.h:118
void coap_register_response_handler(coap_context_t *context, coap_response_handler_t handler)
Registers a new message handler that is called whenever a response is received.
Definition coap_net.c:5146
COAP_API void * coap_context_set_app_data2(coap_context_t *context, void *data, coap_app_data_free_callback_t callback)
Stores data with the given context, returning the previously stored value or NULL.
Definition coap_net.c:676
coap_pdu_t * coap_new_error_response(const coap_pdu_t *request, coap_pdu_code_t code, coap_opt_filter_t *opts)
Creates a new ACK PDU with specified error code.
Definition coap_net.c:3110
void coap_context_set_max_handshake_sessions(coap_context_t *context, unsigned int max_handshake_sessions)
Set the maximum number of sessions in (D)TLS handshake value.
Definition coap_net.c:499
int coap_context_get_coap_fd(const coap_context_t *context)
Get the libcoap internal file descriptor for using in an application's select() or returned as an eve...
Definition coap_net.c:589
void coap_register_dynamic_resource_handler(coap_context_t *context, coap_resource_dynamic_create_t create_handler, uint32_t dynamic_max)
Sets up a handler for calling when an unknown resource is requested.
Definition coap_net.c:5186
COAP_DEPRECATED void coap_set_app_data(coap_context_t *context, void *data)
Definition coap_net.c:789
int coap_mcast_set_hops(coap_session_t *session, size_t hops)
Function interface for defining the hop count (ttl) for sending multicast traffic.
coap_response_t
Definition coap_net.h:54
void(* coap_ping_handler_t)(coap_session_t *session, const coap_pdu_t *received, const coap_mid_t mid)
Received Ping handler that is used as callback in coap_context_t.
Definition coap_net.h:95
void coap_ticks(coap_tick_t *)
Returns the current value of an internal tick counter.
Definition coap_time.c:90
COAP_API void coap_free_context(coap_context_t *context)
CoAP stack context must be released with coap_free_context().
Definition coap_net.c:803
void(* coap_nack_handler_t)(coap_session_t *session, const coap_pdu_t *sent, const coap_nack_reason_t reason, const coap_mid_t mid)
Negative Acknowedge handler that is used as callback in coap_context_t.
Definition coap_net.h:83
void coap_context_set_shutdown_no_observe(coap_context_t *context)
Definition coap_net.c:580
void * coap_context_get_app_data(const coap_context_t *context)
Returns any application-specific data that has been stored with context using the function coap_conte...
Definition coap_net.c:670
COAP_API int coap_context_set_pki_root_cas(coap_context_t *context, const char *ca_file, const char *ca_dir)
Set the context's default Root CA information for a client or server.
Definition coap_net.c:423
COAP_DEPRECATED void coap_context_set_app_data(coap_context_t *context, void *data)
Stores data with the given context.
Definition coap_net.c:662
uint32_t coap_context_get_csm_max_message_size(const coap_context_t *context)
Get the CSM max session size value.
Definition coap_net.c:553
unsigned int coap_context_get_session_timeout(const coap_context_t *context)
Get the session timeout value.
Definition coap_net.c:575
COAP_API int coap_context_set_psk(coap_context_t *context, const char *hint, const uint8_t *key, size_t key_len)
Set the context's default PSK hint and/or key for a server.
COAP_API coap_mid_t coap_send_ack(coap_session_t *session, const coap_pdu_t *request)
Sends an ACK message with code 0 for the specified request to dst.
Definition coap_net.c:1072
unsigned int coap_context_get_csm_timeout_ms(const coap_context_t *context)
Get the CSM timeout value.
Definition coap_net.c:535
COAP_API uint16_t coap_new_message_id(coap_session_t *session)
Returns a new message id and updates session->tx_mid accordingly.
void coap_register_ping_handler(coap_context_t *context, coap_ping_handler_t handler)
Registers a new message handler that is called whenever a CoAP Ping message is received.
Definition coap_net.c:5174
COAP_API int coap_context_set_psk2(coap_context_t *context, coap_dtls_spsk_t *setup_data)
Set the context's default PSK hint and/or key for a server.
COAP_DEPRECATED void * coap_get_app_data(const coap_context_t *context)
Definition coap_net.c:797
int coap_context_set_cid_tuple_change(coap_context_t *context, uint8_t every)
Set the Connection ID client tuple frequency change for testing CIDs.
Definition coap_net.c:469
void coap_context_set_max_idle_sessions(coap_context_t *context, unsigned int max_idle_sessions)
Set the maximum idle sessions count.
Definition coap_net.c:488
COAP_API coap_mid_t coap_send_message_type(coap_session_t *session, const coap_pdu_t *request, coap_pdu_type_t type)
Helper function to create and send a message with type (usually ACK or RST).
Definition coap_net.c:1180
COAP_API coap_mid_t coap_send_rst(coap_session_t *session, const coap_pdu_t *request)
Sends an RST message with code 0 for the specified request to dst.
Definition coap_net.c:1057
void coap_context_set_keepalive(coap_context_t *context, unsigned int seconds)
Set the context keepalive timer for sessions.
Definition coap_net.c:464
COAP_API int coap_can_exit(coap_context_t *context)
Returns 1 if there are no messages to send or to dispatch in the context's queues.
Definition coap_net.c:4978
COAP_API void coap_register_option(coap_context_t *context, coap_option_num_t number)
Registers the option number number with the given context object context.
Definition coap_net.c:5195
COAP_DEPRECATED unsigned int coap_context_get_csm_timeout(const coap_context_t *context)
Get the CSM timeout value.
Definition coap_net.c:519
COAP_API int coap_context_load_pki_trust_store(coap_context_t *context)
Load the hosts's default trusted CAs for a client or server.
Definition coap_net.c:445
void coap_context_set_session_reconnect_time(coap_context_t *context, unsigned int reconnect_time)
Set the session reconnect delay time after a working client session has failed.
Definition coap_net.c:564
void coap_register_pong_handler(coap_context_t *context, coap_pong_handler_t handler)
Registers a new message handler that is called whenever a CoAP Pong message is received.
Definition coap_net.c:5180
void coap_context_set_max_token_size(coap_context_t *context, size_t max_token_size)
Set the maximum token size (RFC8974).
Definition coap_net.c:480
COAP_API int coap_handle_event(coap_context_t *context, coap_event_t event, coap_session_t *session)
Invokes the event handler of context for the given event and data.
Definition coap_net.c:4893
void coap_register_nack_handler(coap_context_t *context, coap_nack_handler_t handler)
Registers a new message handler that is called whenever a confirmable message (request or response) i...
Definition coap_net.c:5168
void coap_context_set_csm_timeout_ms(coap_context_t *context, unsigned int csm_timeout_ms)
Set the CSM timeout value.
Definition coap_net.c:525
@ COAP_RESPONSE_FAIL
Response not liked - send CoAP RST packet.
Definition coap_net.h:55
@ COAP_RESPONSE_OK
Response is fine.
Definition coap_net.h:56
coap_event_t
Scalar type to represent different events, e.g.
Definition coap_event.h:38
coap_log_t
Logging type.
Definition coap_debug.h:56
void coap_lwip_set_input_wait_handler(coap_context_t *context, coap_lwip_input_wait_handler_t handler, void *input_arg)
Set up a wait / timeout callback handler for use when the application calls coap_io_process().
int(* coap_lwip_input_wait_handler_t)(void *arg, uint32_t milli_secs)
LwIP callback handler that can be used to wait / timeout for the next input packet.
Definition coap_net.h:1089
void coap_lwip_dump_memory_pools(coap_log_t log_level)
Dump the current state of the LwIP memory pools.
int coap_mid_t
coap_mid_t is used to store the CoAP Message ID of a CoAP PDU.
Definition coap_pdu.h:268
coap_pdu_code_t
Set of codes available for a PDU.
Definition coap_pdu.h:331
coap_pdu_type_t
CoAP PDU message type definitions.
Definition coap_pdu.h:72
void(* coap_app_data_free_callback_t)(void *data)
Callback to free off the app data when the entry is being deleted / freed off.
#define COAP_DEPRECATED
Definition libcoap.h:66
Multi-purpose address abstraction.
The CoAP stack's global state is stored in a coap_context_t object.
The structure used for defining the PKI setup data to be used.
Definition coap_dtls.h:316
The structure used for defining the Server PSK setup data to be used.
Definition coap_dtls.h:505
structure for CoAP PDUs
Abstraction of resource that can be attached to coap_context_t.
Abstraction of virtual session that can be attached to coap_context_t (client) or coap_endpoint_t (se...