libcoap  4.3.0rc2
Go to the documentation of this file.
1 /*
2  * net.h -- CoAP network interface
3  *
4  * Copyright (C) 2010-2021 Olaf Bergmann <>
5  *
6  * This file is part of the CoAP library libcoap. Please see README for terms
7  * of use.
8  */
10 #ifndef COAP_NET_H_
11 #define COAP_NET_H_
13 #include <stdlib.h>
14 #include <string.h>
15 #ifndef _WIN32
16 #include <sys/time.h>
17 #endif
18 #include <time.h>
20 #ifdef WITH_LWIP
21 #include <lwip/ip_addr.h>
22 #endif
24 #include "coap_io.h"
25 #include "coap_dtls.h"
26 #include "coap_event.h"
27 #include "pdu.h"
28 #include "coap_session.h"
36 typedef enum coap_response_t {
54  coap_session_t *session,
55  coap_pdu_t *sent,
56  coap_pdu_t *received,
57  const coap_mid_t id);
68 typedef void (*coap_nack_handler_t)(coap_context_t *context,
69  coap_session_t *session,
70  coap_pdu_t *sent,
71  coap_nack_reason_t reason,
72  const coap_mid_t id);
82 typedef void (*coap_ping_handler_t)(coap_context_t *context,
83  coap_session_t *session,
84  coap_pdu_t *received,
85  const coap_mid_t id);
95 typedef void (*coap_pong_handler_t)(coap_context_t *context,
96  coap_session_t *session,
97  coap_pdu_t *received,
98  const coap_mid_t id);
107 void
109  coap_response_handler_t handler);
120 void
122  coap_nack_handler_t handler);
131 void
133  coap_ping_handler_t handler);
142 void
144  coap_pong_handler_t handler);
152 void
153 coap_register_option(coap_context_t *ctx, uint16_t type);
158 coap_context_t *coap_new_context(const coap_address_t *listen_addr);
172 int coap_context_set_psk( coap_context_t *context, const char *hint,
173  const uint8_t *key, size_t key_len );
185  coap_dtls_spsk_t *setup_data);
196 int
198  const coap_dtls_pki_t *setup_data);
211 int
213  const char *ca_file,
214  const char *ca_dir);
232 void coap_context_set_keepalive(coap_context_t *context, unsigned int seconds);
242 int coap_context_get_coap_fd(const coap_context_t *context);
253 void
255  unsigned int max_idle_sessions);
264 unsigned int
275 void
277  unsigned int session_timeout);
286 unsigned int
297 void
299  unsigned int csm_tmeout);
308 unsigned int
320 void
322  unsigned int max_handshake_sessions);
331 unsigned int
343 uint16_t coap_new_message_id(coap_session_t *session);
353 void coap_free_context(coap_context_t *context);
364 void coap_set_app_data(coap_context_t *context, void *data);
375 void *coap_get_app_data(const coap_context_t *context);
395  unsigned char code,
396  coap_opt_filter_t *opts);
414  coap_pdu_t *request,
415  unsigned char code,
416  coap_opt_filter_t *opts);
430 coap_send_message_type(coap_session_t *session, coap_pdu_t *request, unsigned char type);
458  return coap_send_message_type(session, request, COAP_MESSAGE_RST);
459 }
501 int coap_handle_event(coap_context_t *context,
502  coap_event_t event,
503  coap_session_t *session);
507 int coap_can_exit(coap_context_t *context);
526 int
527 coap_join_mcast_group_intf(coap_context_t *ctx, const char *groupname,
528  const char *ifname);
530 #define coap_join_mcast_group(ctx, groupname) \
531  (coap_join_mcast_group_intf(ctx, groupname, NULL))
543 int
544 coap_mcast_set_hops(coap_session_t *session, size_t hops);
554 #define COAP_IO_WAIT 0
555 #define COAP_IO_NO_WAIT ((uint32_t)-1)
585 int coap_io_process(coap_context_t *ctx, uint32_t timeout_ms);
587 #ifndef RIOT_VERSION
615 int coap_io_process_with_fds(coap_context_t *ctx, uint32_t timeout_ms,
616  int nfds, fd_set *readfds, fd_set *writefds,
617  fd_set *exceptfds);
618 #endif /* !RIOT_VERSION */
661 unsigned int
663  coap_socket_t *sockets[],
664  unsigned int max_sockets,
665  unsigned int *num_sockets,
666  coap_tick_t now
667 );
703 unsigned int
706 struct epoll_event;
721 void coap_io_do_epoll(coap_context_t *ctx, struct epoll_event* events,
722  size_t nevents);
746 coap_run_once(coap_context_t *ctx, uint32_t timeout_ms)
747 {
748  return coap_io_process(ctx, timeout_ms);
749 }
771  coap_socket_t *sockets[],
772  unsigned int max_sockets,
773  unsigned int *num_sockets,
774  coap_tick_t now
775 ) {
776  return coap_io_prepare_io(ctx, sockets, max_sockets, num_sockets, now);
777 }
791 ) {
792  coap_io_do_io(ctx, now);
793 }
795 /* Old definitions which may be hanging around in old code - be helpful! */
797 #define COAP_RUN_BLOCK COAP_RUN_BLOCK_deprecated_use_COAP_IO_WAIT
799 #endif /* COAP_NET_H_ */
Definition: coap_io.h:62
Defines the application visible session information.
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:1738
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:1005
void coap_io_do_epoll(coap_context_t *ctx, struct epoll_event *events, size_t nevents)
Process all the epoll events.
Definition: net.c:1799
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:1057
int coap_io_process(coap_context_t *ctx, uint32_t timeout_ms)
The main I/O processing function.
Definition: coap_io.c:1263
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:1268
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_context_set_session_timeout(coap_context_t *context, unsigned int session_timeout)
Set the session timeout value.
Definition: net.c:483
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
unsigned int coap_context_get_max_handshake_sessions(const coap_context_t *context)
Get the session timeout value.
Definition: net.c:467
uint16_t coap_new_message_id(coap_session_t *session)
Returns a new message id and updates session->tx_mid accordingly.
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:2057
unsigned int coap_context_get_max_idle_sessions(const coap_context_t *context)
Get the maximum idle sessions count.
Definition: net.c:456
coap_response_t(* coap_response_handler_t)(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:53
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:3166
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.c:3242
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:623
void coap_free_context(coap_context_t *context)
CoAP stack context must be released with coap_free_context().
Definition: net.c:629
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: net.c:461
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: net.c:493
void(* coap_pong_handler_t)(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:95
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:3155
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
int coap_mcast_set_hops(coap_session_t *session, size_t hops)
Function interface for defining the hop count (ttl) for sending multicast traffic.
Definition: net.c:3495
Definition: net.h:36
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:918
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
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:750
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:503
unsigned int coap_context_get_session_timeout(const coap_context_t *context)
Get the session timeout value.
Definition: net.c:489
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
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.c:3254
void coap_register_option(coap_context_t *ctx, uint16_t type)
Registers the option type type with the given context object ctx.
Definition: net.c:3266
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:3272
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:900
void coap_context_set_max_idle_sessions(coap_context_t *context, unsigned int max_idle_sessions)
Set the maximum idle sessions count.
Definition: net.c:450
void(* coap_nack_handler_t)(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:68
coap_mid_t coap_send_large(coap_session_t *session, coap_pdu_t *pdu)
Sends a CoAP message to given peer.
Definition: net.c:1054
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:617
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:457
unsigned int coap_context_get_csm_timeout(const coap_context_t *context)
Get the CSM timeout value.
Definition: net.c:478
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.c:3260
coap_mid_t coap_send(coap_session_t *session, coap_pdu_t *pdu)
Sends a CoAP message to given peer.
Definition: net.c:1154
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.c:3248
void(* coap_ping_handler_t)(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:82
void coap_context_set_csm_timeout(coap_context_t *context, unsigned int csm_tmeout)
Set the CSM timeout value.
Definition: net.c:472
Response not liked - send CoAP RST packet.
Definition: net.h:37
Response is fine.
Definition: net.h:38
unsigned int coap_event_t
Scalar type to represent different events, e.g.
Definition: coap_event.h:25
int coap_mid_t
coap_mid_t is used to store the CoAP Message ID of a CoAP PDU.
Definition: pdu.h:229
Definition: pdu.h:58
Definition: libcoap.h:46
Definition: libcoap.h:38
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:770
COAP_STATIC_INLINE COAP_DEPRECATED int coap_run_once(coap_context_t *ctx, uint32_t timeout_ms)
Definition: net.h:746
COAP_STATIC_INLINE COAP_DEPRECATED void coap_read(coap_context_t *ctx, coap_tick_t now)
Definition: net.h:790
Pre-defined constants that reflect defaults for CoAP.
multi-purpose address abstraction
Definition: address.h:94
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:240
The structure used for defining the Server PSK setup data to be used.
Definition: coap_dtls.h:421
structure for CoAP PDUs token, if any, follows the fixed size header, then options until payload mark...
Abstraction of virtual session that can be attached to coap_context_t (client) or coap_endpoint_t (se...