libcoap  4.3.0rc1
net.h
Go to the documentation of this file.
1 /*
2  * net.h -- CoAP network interface
3  *
4  * Copyright (C) 2010-2021 Olaf Bergmann <bergmann@tzi.org>
5  *
6  * This file is part of the CoAP library libcoap. Please see README for terms
7  * of use.
8  */
9 
10 #ifndef COAP_NET_H_
11 #define COAP_NET_H_
12 
13 #include <stdlib.h>
14 #include <string.h>
15 #ifndef _WIN32
16 #include <sys/time.h>
17 #endif
18 #include <time.h>
19 
20 #ifdef WITH_LWIP
21 #include <lwip/ip_addr.h>
22 #endif
23 
24 #include "coap_io.h"
25 #include "coap_dtls.h"
26 #include "coap_event.h"
27 #include "coap_time.h"
28 #include "option.h"
29 #include "pdu.h"
30 #include "coap_prng.h"
31 #include "coap_session.h"
32 #include "resource.h"
33 
37 typedef struct coap_queue_t {
38  struct coap_queue_t *next;
40  unsigned char retransmit_cnt;
42  unsigned int timeout;
47 
56 int coap_insert_node(coap_queue_t **queue, coap_queue_t *node);
57 
66 
74 void coap_delete_all(coap_queue_t *queue);
75 
82 
83 typedef enum coap_response_t {
87 
101  coap_session_t *session,
102  coap_pdu_t *sent,
103  coap_pdu_t *received,
104  const coap_mid_t id);
105 
115 typedef void (*coap_nack_handler_t)(struct coap_context_t *context,
116  coap_session_t *session,
117  coap_pdu_t *sent,
118  coap_nack_reason_t reason,
119  const coap_mid_t id);
120 
129 typedef void (*coap_ping_handler_t)(struct coap_context_t *context,
130  coap_session_t *session,
131  coap_pdu_t *received,
132  const coap_mid_t id);
133 
142 typedef void (*coap_pong_handler_t)(struct coap_context_t *context,
143  coap_session_t *session,
144  coap_pdu_t *received,
145  const coap_mid_t id);
146 
162 #ifndef WITHOUT_ASYNC
166 #endif /* WITHOUT_ASYNC */
167 
176 #ifdef WITH_CONTIKI
177  struct uip_udp_conn *conn;
178  struct etimer retransmit_timer;
179  struct etimer notify_timer;
180 #endif /* WITH_CONTIKI */
181 
182 #ifdef WITH_LWIP
183  uint8_t timer_configured;
186 #endif /* WITH_LWIP */
187 
192 
198 
199  ssize_t (*network_send)(coap_socket_t *sock, const coap_session_t *session, const uint8_t *data, size_t datalen);
200 
201  ssize_t (*network_read)(coap_socket_t *sock, struct coap_packet_t *packet);
202 
203  size_t(*get_client_psk)(const coap_session_t *session, const uint8_t *hint, size_t hint_len, uint8_t *identity, size_t *identity_len, size_t max_identity_len, uint8_t *psk, size_t max_psk_len);
204  size_t(*get_server_psk)(const coap_session_t *session, const uint8_t *identity, size_t identity_len, uint8_t *psk, size_t max_psk_len);
205  size_t(*get_server_hint)(const coap_session_t *session, uint8_t *hint, size_t max_hint_len);
206 
208 
211  unsigned int session_timeout;
212  unsigned int max_idle_sessions;
213  unsigned int max_handshake_sessions;
214  unsigned int ping_timeout;
215  unsigned int csm_timeout;
216  uint8_t observe_pending;
217  uint8_t block_mode;
218  uint64_t etag;
223  void *app;
224 #ifdef COAP_EPOLL_SUPPORT
225  int epfd;
226  int eptimerfd;
227  coap_tick_t next_timeout;
228 #endif /* COAP_EPOLL_SUPPORT */
229 };
230 
240  coap_response_handler_t handler) {
241  context->response_handler = handler;
242 }
243 
255  coap_nack_handler_t handler) {
256  context->nack_handler = handler;
257 }
258 
268  coap_ping_handler_t handler) {
269  context->ping_handler = handler;
270 }
271 
281  coap_pong_handler_t handler) {
282  context->pong_handler = handler;
283 }
284 
292 coap_register_option(coap_context_t *ctx, uint16_t type) {
294 }
295 
301 unsigned int coap_adjust_basetime(coap_context_t *ctx, coap_tick_t now);
302 
307 
312 
316 coap_context_t *coap_new_context(const coap_address_t *listen_addr);
317 
330 int coap_context_set_psk( coap_context_t *context, const char *hint,
331  const uint8_t *key, size_t key_len );
332 
343  coap_dtls_spsk_t *setup_data);
344 
354 int
356  const coap_dtls_pki_t *setup_data);
357 
369 int
371  const char *ca_file,
372  const char *ca_dir);
373 
390 void coap_context_set_keepalive(coap_context_t *context, unsigned int seconds);
391 
401 
411 COAP_STATIC_INLINE uint16_t
413  return ++session->tx_mid;
414 }
415 
424 void coap_free_context(coap_context_t *context);
425 
435 void coap_set_app_data(coap_context_t *context, void *data);
436 
446 void *coap_get_app_data(const coap_context_t *context);
447 
466  unsigned char code,
467  coap_opt_filter_t *opts);
468 
485  coap_pdu_t *request,
486  unsigned char code,
487  coap_opt_filter_t *opts);
488 
501 coap_send_message_type(coap_session_t *session, coap_pdu_t *request, unsigned char type);
502 
515 
529  return coap_send_message_type(session, request, COAP_MESSAGE_RST);
530 }
531 
544 
561 
572 
586 int coap_handle_dgram(coap_context_t *ctx, coap_session_t *session, uint8_t *data, size_t data_len);
587 
598 int coap_handle_event(coap_context_t *context,
599  coap_event_t event,
600  coap_session_t *session);
618  coap_session_t *session,
619  coap_mid_t id,
620  coap_queue_t **node);
621 
623 coap_wait_ack( coap_context_t *context, coap_session_t *session,
624  coap_queue_t *node);
625 
636  coap_session_t *session,
637  const uint8_t *token,
638  size_t token_length);
639 
647 void
649  coap_session_t *session,
650  coap_nack_reason_t reason);
651 
655 void coap_dispatch(coap_context_t *context, coap_session_t *session,
656  coap_pdu_t *pdu);
657 
661 int coap_can_exit(coap_context_t *context);
662 
668 
701  coap_pdu_t *pdu,
702  coap_opt_filter_t unknown);
703 
716  coap_session_t *session,
717  coap_pdu_t *request);
718 
732 unsigned int coap_calc_timeout(coap_session_t *session, unsigned char r);
733 
745 int
746 coap_join_mcast_group_intf(coap_context_t *ctx, const char *groupname,
747  const char *ifname);
748 
749 #define coap_join_mcast_group(ctx, groupname) \
750  (coap_join_mcast_group_intf(ctx, groupname, NULL))
751 
758 #define COAP_IO_WAIT 0
759 #define COAP_IO_NO_WAIT ((uint32_t)-1)
760 
789 int coap_io_process(coap_context_t *ctx, uint32_t timeout_ms);
790 
791 #ifndef RIOT_VERSION
819 int coap_io_process_with_fds(coap_context_t *ctx, uint32_t timeout_ms,
820  int nfds, fd_set *readfds, fd_set *writefds,
821  fd_set *exceptfds);
822 #endif /* !RIOT_VERSION */
823 
865 unsigned int
867  coap_socket_t *sockets[],
868  unsigned int max_sockets,
869  unsigned int *num_sockets,
870  coap_tick_t now
871 );
872 
887 
907 unsigned int
909 
910 struct epoll_event;
911 
925 void coap_io_do_epoll(coap_context_t *ctx, struct epoll_event* events,
926  size_t nevents);
927 
950 coap_run_once(coap_context_t *ctx, uint32_t timeout_ms)
951 {
952  return coap_io_process(ctx, timeout_ms);
953 }
954 
975  coap_socket_t *sockets[],
976  unsigned int max_sockets,
977  unsigned int *num_sockets,
978  coap_tick_t now
979 ) {
980  return coap_io_prepare_io(ctx, sockets, max_sockets, num_sockets, now);
981 }
982 
995 ) {
996  coap_io_do_io(ctx, now);
997 }
998 
999 /* Old definitions which may be hanging around in old code - be helpful! */
1000 #define COAP_RUN_NONBLOCK COAP_RUN_NONBLOCK_deprecated_use_COAP_IO_NO_WAIT
1001 #define COAP_RUN_BLOCK COAP_RUN_BLOCK_deprecated_use_COAP_IO_WAIT
1002 
1003 #endif /* COAP_NET_H_ */
coap_nack_reason_t
Definition: coap_io.h:223
Pseudo Random Numbers.
Defines the application visible session information.
Clock Handling.
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: net.c:1690
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:1001
void coap_io_do_epoll(coap_context_t *ctx, struct epoll_event *events, size_t nevents)
Process all the epoll events.
Definition: net.c:1751
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:1053
int coap_io_process(coap_context_t *ctx, uint32_t timeout_ms)
The main I/O processing function.
Definition: coap_io.c:1253
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.
Definition: coap_io.c:1258
uint64_t coap_tick_t
This data type represents internal timer ticks with COAP_TICKS_PER_SECOND resolution.
Definition: coap_time.h:120
void(* coap_resource_release_userdata_handler_t)(void *user_data)
Definition of release resource user_data callback function.
Definition: resource.h:213
int(* coap_event_handler_t)(struct coap_context_t *, coap_event_t event, struct coap_session_t *session)
Type for event handler functions that can be registered with a CoAP context using the unction coap_se...
Definition: coap_event.h:62
unsigned int coap_event_t
Scalar type to represent different events, e.g.
Definition: coap_event.h:25
int coap_option_filter_set(coap_opt_filter_t *filter, uint16_t type)
Sets the corresponding entry for type in filter.
Definition: option.c:486
#define COAP_DEPRECATED
Definition: libcoap.h:46
#define COAP_STATIC_INLINE
Definition: libcoap.h:38
COAP_STATIC_INLINE 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: net.h:267
coap_queue_t * coap_peek_next(coap_context_t *context)
Returns the next pdu to send without removing from sendqeue.
Definition: net.c:272
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.
Definition: net.c:406
void(* coap_ping_handler_t)(struct coap_context_t *context, coap_session_t *session, coap_pdu_t *received, const coap_mid_t id)
Received Ping handler that is used as callback in coap_context_t.
Definition: net.h:129
unsigned int coap_adjust_basetime(coap_context_t *ctx, coap_tick_t now)
Set sendqueue_basetime in the given context object ctx to now.
Definition: net.c:155
coap_pdu_t * coap_new_error_response(coap_pdu_t *request, unsigned char code, coap_opt_filter_t *opts)
Creates a new ACK PDU with specified error code.
Definition: net.c:2009
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: net.c:3080
void coap_delete_all(coap_queue_t *queue)
Removes all items from given queue and frees the allocated storage.
Definition: net.c:249
int coap_context_get_coap_fd(coap_context_t *context)
Get the libcoap internal file descriptor for using in an application's select() or returned as an eve...
Definition: net.c:449
int coap_remove_from_queue(coap_queue_t **queue, coap_session_t *session, coap_mid_t id, coap_queue_t **node)
This function removes the element with given id from the list given list.
Definition: net.c:1887
int coap_delete_node(coap_queue_t *node)
Destroys specified node.
Definition: net.c:229
coap_queue_t * coap_new_node(void)
Creates a new node suitable for adding to the CoAP sendqueue.
Definition: net.c:258
coap_queue_t * coap_pop_next(coap_context_t *context)
Returns the next pdu to send and removes it from the sendqeue.
Definition: net.c:280
void * coap_get_app_data(const coap_context_t *context)
Returns any application-specific data that has been stored with context using the function coap_set_a...
Definition: net.c:579
void coap_free_context(coap_context_t *context)
CoAP stack context must be released with coap_free_context().
Definition: net.c:585
COAP_STATIC_INLINE 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: net.h:280
struct coap_queue_t coap_queue_t
Queue entry.
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: net.c:3069
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.
Definition: net.c:386
COAP_STATIC_INLINE void coap_register_option(coap_context_t *ctx, uint16_t type)
Registers the option type type with the given context object ctx.
Definition: net.h:292
coap_pdu_t * coap_wellknown_response(coap_context_t *context, coap_session_t *session, coap_pdu_t *request)
Creates a new response for given request with the contents of .well-known/core.
Definition: net.c:2139
coap_response_t
Definition: net.h:83
@ COAP_RESPONSE_FAIL
Response not liked - send CoAP RST packet.
Definition: net.h:84
@ COAP_RESPONSE_OK
Response is fine.
Definition: net.h:85
void coap_ticks(coap_tick_t *)
Returns the current value of an internal tick counter.
coap_mid_t coap_send_message_type(coap_session_t *session, coap_pdu_t *request, unsigned char type)
Helper function to create and send a message with type (usually ACK or RST).
Definition: net.c:873
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: net.c:435
void coap_dispatch(coap_context_t *context, coap_session_t *session, coap_pdu_t *pdu)
Dispatches the PDUs from the receive queue in given context.
Definition: net.c:2885
COAP_STATIC_INLINE 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: net.h:239
int coap_insert_node(coap_queue_t **queue, coap_queue_t *node)
Adds node to given queue, ordered by variable t in node.
Definition: net.c:192
unsigned int coap_calc_timeout(coap_session_t *session, unsigned char r)
Calculates the initial timeout based on the session CoAP transmission parameters 'ack_timeout',...
Definition: net.c:899
coap_mid_t coap_send_ack(coap_session_t *session, coap_pdu_t *request)
Sends an ACK message with code 0 for the specified request to dst.
Definition: net.c:706
void(* coap_pong_handler_t)(struct coap_context_t *context, coap_session_t *session, coap_pdu_t *received, const coap_mid_t id)
Received Pong handler that is used as callback in coap_context_t.
Definition: net.h:142
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: net.c:459
coap_response_t(* coap_response_handler_t)(struct coap_context_t *context, coap_session_t *session, coap_pdu_t *sent, coap_pdu_t *received, const coap_mid_t id)
Response handler that is used as callback in coap_context_t.
Definition: net.h:100
int coap_option_check_critical(coap_context_t *ctx, coap_pdu_t *pdu, coap_opt_filter_t unknown)
Verifies that pdu contains no unknown critical options.
Definition: net.c:654
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.
Definition: net.c:420
coap_mid_t coap_retransmit(coap_context_t *context, coap_queue_t *node)
Handles retransmissions of confirmable messages.
Definition: net.c:1292
void coap_cancel_all_messages(coap_context_t *context, coap_session_t *session, const uint8_t *token, size_t token_length)
Cancels all outstanding messages for session session that have the specified token.
Definition: net.c:1968
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...
Definition: net.c:3135
void(* coap_nack_handler_t)(struct coap_context_t *context, coap_session_t *session, coap_pdu_t *sent, coap_nack_reason_t reason, const coap_mid_t id)
Negative Acknowedge handler that is used as callback in coap_context_t.
Definition: net.h:115
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)
Definition: net.h:974
coap_mid_t coap_send_error(coap_session_t *session, coap_pdu_t *request, unsigned char code, coap_opt_filter_t *opts)
Sends an error response with code code for request request to dst.
Definition: net.c:855
COAP_STATIC_INLINE COAP_DEPRECATED int coap_run_once(coap_context_t *ctx, uint32_t timeout_ms)
Definition: net.h:950
coap_mid_t coap_send_large(coap_session_t *session, coap_pdu_t *pdu)
Sends a CoAP message to given peer.
Definition: net.c:1009
void coap_context_set_keepalive(coap_context_t *context, unsigned int seconds)
Set the context keepalive timer for sessions.
Definition: net.c:445
void coap_set_app_data(coap_context_t *context, void *data)
Stores data with the given CoAP context.
Definition: net.c:573
COAP_STATIC_INLINE coap_mid_t coap_send_rst(coap_session_t *session, coap_pdu_t *request)
Sends an RST message with code 0 for the specified request to dst.
Definition: net.h:528
coap_mid_t coap_wait_ack(coap_context_t *context, coap_session_t *session, coap_queue_t *node)
Definition: net.c:925
void coap_cancel_session_messages(coap_context_t *context, coap_session_t *session, coap_nack_reason_t reason)
Cancels all outstanding messages for session session.
Definition: net.c:1931
COAP_STATIC_INLINE uint16_t coap_new_message_id(coap_session_t *session)
Returns a new message id and updates session->tx_mid accordingly.
Definition: net.h:412
COAP_STATIC_INLINE 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: net.h:254
int coap_handle_dgram(coap_context_t *ctx, coap_session_t *session, uint8_t *data, size_t data_len)
Parses and interprets a CoAP datagram with context ctx.
Definition: net.c:1850
coap_mid_t coap_send(coap_session_t *session, coap_pdu_t *pdu)
Sends a CoAP message to given peer.
Definition: net.c:1109
COAP_STATIC_INLINE COAP_DEPRECATED void coap_read(coap_context_t *ctx, coap_tick_t now)
Definition: net.h:994
Helpers for handling options in CoAP PDUs.
Pre-defined constants that reflect defaults for CoAP.
int coap_mid_t
coap_mid_t is used to store the CoAP Message ID of a CoAP PDU.
Definition: pdu.h:244
#define COAP_MESSAGE_RST
Definition: pdu.h:78
Generic resource handling.
multi-purpose address abstraction
Definition: address.h:94
The CoAP stack's global state is stored in a coap_context_t object.
Definition: net.h:150
coap_tick_t sendqueue_basetime
The time stamp in the first element of the sendqeue is relative to sendqueue_basetime.
Definition: net.h:171
coap_pong_handler_t pong_handler
Definition: net.h:191
uint64_t etag
Next ETag to use.
Definition: net.h:218
ssize_t(* network_read)(coap_socket_t *sock, struct coap_packet_t *packet)
Definition: net.h:201
unsigned int csm_timeout
Timeout for waiting for a CSM from the remote side.
Definition: net.h:215
void * app
application-specific data
Definition: net.h:223
struct coap_async_state_t * async_state
list of asynchronous message ids
Definition: net.h:165
coap_session_t * sessions
client sessions
Definition: net.h:174
coap_nack_handler_t nack_handler
Definition: net.h:189
unsigned int ping_timeout
Minimum inactivity time before sending a ping message.
Definition: net.h:214
size_t(* get_server_psk)(const coap_session_t *session, const uint8_t *identity, size_t identity_len, uint8_t *psk, size_t max_psk_len)
Definition: net.h:204
coap_resource_t * resources
hash table or list of known resources
Definition: net.h:152
ssize_t(* network_send)(coap_socket_t *sock, const coap_session_t *session, const uint8_t *data, size_t datalen)
Definition: net.h:199
uint16_t * cache_ignore_options
CoAP options to ignore when creating a cache-key.
Definition: net.h:221
void * dtls_context
Definition: net.h:207
coap_opt_filter_t known_options
Definition: net.h:151
coap_resource_release_userdata_handler_t release_userdata
function to release user_data when resource is deleted
Definition: net.h:158
coap_ping_handler_t ping_handler
Definition: net.h:190
size_t cache_ignore_count
The number of CoAP options to ignore when creating a cache-key.
Definition: net.h:222
unsigned int max_handshake_sessions
Maximum number of simultaneous negotating sessions per endpoint.
Definition: net.h:213
coap_queue_t * sendqueue
Definition: net.h:172
coap_response_handler_t response_handler
Definition: net.h:188
coap_cache_entry_t * cache
CoAP cache-entry cache.
Definition: net.h:220
uint8_t observe_pending
Observe response pending.
Definition: net.h:216
coap_endpoint_t * endpoint
the endpoints used for listening
Definition: net.h:173
size_t(* get_server_hint)(const coap_session_t *session, uint8_t *hint, size_t max_hint_len)
Definition: net.h:205
coap_event_handler_t handle_event
Callback function that is used to signal events to the application.
Definition: net.h:197
unsigned int session_timeout
Number of seconds of inactivity after which an unused session will be closed.
Definition: net.h:211
size_t(* get_client_psk)(const coap_session_t *session, const uint8_t *hint, size_t hint_len, uint8_t *identity, size_t *identity_len, size_t max_identity_len, uint8_t *psk, size_t max_psk_len)
Definition: net.h:203
coap_resource_t * proxy_uri_resource
can be used for handling proxy URI resources
Definition: net.h:156
coap_dtls_spsk_t spsk_setup_data
Contains the initial PSK server setup data.
Definition: net.h:209
uint8_t block_mode
Zero or more COAP_BLOCK_ or'd options.
Definition: net.h:217
coap_resource_t * unknown_resource
can be used for handling unknown resources
Definition: net.h:154
unsigned int max_idle_sessions
Maximum number of simultaneous unused sessions per endpoint.
Definition: net.h:212
The structure used for defining the PKI setup data to be used.
Definition: coap_dtls.h:245
The structure used for defining the Server PSK setup data to be used.
Definition: coap_dtls.h:426
Abstraction of virtual endpoint that can be attached to coap_context_t.
structure for CoAP PDUs token, if any, follows the fixed size header, then options until payload mark...
Definition: pdu.h:287
Queue entry.
Definition: net.h:37
coap_session_t * session
the CoAP session
Definition: net.h:43
coap_pdu_t * pdu
the CoAP PDU to send
Definition: net.h:45
unsigned int timeout
the randomized timeout value
Definition: net.h:42
struct coap_queue_t * next
Definition: net.h:38
coap_mid_t id
CoAP message id.
Definition: net.h:44
coap_tick_t t
when to send PDU for the next time
Definition: net.h:39
unsigned char retransmit_cnt
retransmission counter, will be removed when zero
Definition: net.h:40
Abstraction of resource that can be attached to coap_context_t.
uint16_t tx_mid
the last message id that was used in this session
Definition: coap_session.h:75