coap_net.h

Go to the documentation of this file.

/*
 * coap_net.h -- CoAP context interface
 *
 * Copyright (C) 2010-2026 Olaf Bergmann <bergmann@tzi.org>
 *
 * SPDX-License-Identifier: BSD-2-Clause
 *
 * This file is part of the CoAP library libcoap. Please see README for terms
 * of use.
 */

 
#ifndef COAP_NET_H_
#define COAP_NET_H_
 
#if !defined(WITH_LWIP) && !defined(WITH_CONTIKI) && !defined(RIOT_VERSION) && !defined(_WIN32)
#include <sys/select.h>
#endif /* ! WITH_LWIP && ! WITH_CONTIKI && ! RIOT_VERSION && ! _WIN32 */
 
#ifdef WITH_LWIP
#include <lwip/ip_addr.h>
#endif
 
#if defined(__ZEPHYR__) && !defined(__unix__) && !defined(__linux__)
#include <zephyr/net/socket_select.h>
#define fd_set zsock_fd_set
#endif
 
#include "coap_io.h"
#include "coap_dtls.h"
#include "coap_event.h"
#include "coap_pdu.h"
#include "coap_session.h"
#include "coap_debug.h"
 
#ifdef __cplusplus
extern "C" {
#endif

 
typedef enum coap_response_t {
  COAP_RESPONSE_FAIL, 
  COAP_RESPONSE_OK    
} coap_response_t;

typedef 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);

typedef 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);

typedef void (*coap_ping_handler_t)(coap_session_t *session,
                                    const coap_pdu_t *received,
                                    const coap_mid_t mid);

typedef void (*coap_pong_handler_t)(coap_session_t *session,
                                    const coap_pdu_t *received,
                                    const coap_mid_t mid);

typedef coap_resource_t *(*coap_resource_dynamic_create_t)(coap_session_t *session,
                                                           const coap_pdu_t *request);

typedef coap_response_t (*coap_block_data_handler_t)(coap_session_t *session,
                                                     coap_pdu_t *pdu,
                                                     coap_resource_t *resource,
                                                     coap_binary_t **body_data,
                                                     size_t length,
                                                     const uint8_t *data,
                                                     size_t offset,
                                                     size_t total);

void coap_register_response_handler(coap_context_t *context,
                                    coap_response_handler_t handler);

void coap_register_nack_handler(coap_context_t *context,
                                coap_nack_handler_t handler);

void coap_register_ping_handler(coap_context_t *context,
                                coap_ping_handler_t handler);

void coap_register_pong_handler(coap_context_t *context,
                                coap_pong_handler_t handler);

void coap_register_dynamic_resource_handler(coap_context_t *context,
                                            coap_resource_dynamic_create_t create_handler,
                                            uint32_t dynamic_max);

void coap_register_block_data_handler(coap_context_t *context,
                                      coap_block_data_handler_t handler);

COAP_API void coap_register_option(coap_context_t *context,
                                   coap_option_num_t number);

coap_context_t *coap_new_context(const coap_address_t *listen_addr);

COAP_API int coap_context_set_psk(coap_context_t *context, const char *hint,
                                  const uint8_t *key, size_t key_len);

COAP_API int coap_context_set_psk2(coap_context_t *context,
                                   coap_dtls_spsk_t *setup_data);

COAP_API int coap_context_set_pki(coap_context_t *context,
                                  const coap_dtls_pki_t *setup_data);

COAP_API int coap_context_set_pki_root_cas(coap_context_t *context,
                                           const char *ca_file,
                                           const char *ca_dir);

COAP_API int coap_context_load_pki_trust_store(coap_context_t *context);

void coap_context_set_keepalive(coap_context_t *context, unsigned int seconds);

int coap_context_set_cid_tuple_change(coap_context_t *context, uint8_t every);

void coap_context_rate_limit_ppm(coap_context_t *context,
                                 uint64_t rate_limit_ppm);

void coap_context_set_max_body_size(coap_context_t *context,
                                    size_t max_body_size);

void coap_context_set_max_bodies_ram(coap_context_t *context,
                                     size_t max_bodies_ram);

void coap_context_set_max_token_size(coap_context_t *context,
                                     size_t max_token_size);

int coap_context_get_coap_fd(const coap_context_t *context);

void coap_context_set_max_idle_sessions(coap_context_t *context,
                                        unsigned int max_idle_sessions);

unsigned int coap_context_get_max_idle_sessions(const coap_context_t *context);

void coap_context_set_session_timeout(coap_context_t *context,
                                      unsigned int session_timeout);

void coap_context_set_session_reconnect_time(coap_context_t *context,
                                             unsigned int reconnect_time);

void coap_context_set_session_reconnect_time2(coap_context_t *context,
                                              unsigned int reconnect_time,
                                              uint8_t retry_count);
unsigned int coap_context_get_session_timeout(const coap_context_t *context);
 
/*
 * Stop sending out observe subscriptons when calling coap_free_context().
 *
 * If this is not called, then 5.03 messages are sent out for every observe
 * subscription when the context is freed off.
 *
 * @param context The coap_context_t object.
 */
void coap_context_set_shutdown_no_observe(coap_context_t *context);

COAP_DEPRECATED void coap_context_set_csm_timeout(coap_context_t *context,
                                                  unsigned int csm_timeout);

COAP_DEPRECATED unsigned int coap_context_get_csm_timeout(const coap_context_t *context);

void coap_context_set_csm_timeout_ms(coap_context_t *context,
                                     unsigned int csm_timeout_ms);

unsigned int coap_context_get_csm_timeout_ms(const coap_context_t *context);

void coap_context_set_csm_max_message_size(coap_context_t *context,
                                           uint32_t csm_max_message_size);

uint32_t coap_context_get_csm_max_message_size(const coap_context_t *context);

void coap_context_set_max_handshake_sessions(coap_context_t *context,
                                             unsigned int max_handshake_sessions);

unsigned int coap_context_get_max_handshake_sessions(const coap_context_t *context);

COAP_API uint16_t coap_new_message_id(coap_session_t *session);

COAP_API void coap_free_context(coap_context_t *context);

COAP_DEPRECATED void coap_set_app_data(coap_context_t *context, void *data);

COAP_DEPRECATED void *coap_get_app_data(const coap_context_t *context);

coap_pdu_t *coap_new_error_response(const coap_pdu_t *request,
                                    coap_pdu_code_t code,
                                    coap_opt_filter_t *opts);

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);

COAP_API coap_mid_t coap_send_message_type(coap_session_t *session, const coap_pdu_t *request,
                                           coap_pdu_type_t type);

COAP_API coap_mid_t coap_send_ack(coap_session_t *session, const coap_pdu_t *request);

COAP_API coap_mid_t coap_send_rst(coap_session_t *session, const coap_pdu_t *request);

COAP_API coap_mid_t coap_send(coap_session_t *session, coap_pdu_t *pdu);
 
#define coap_send_large(session, pdu) coap_send(session, pdu)
 
/*
 * Send a request PDU and wait for the response PDU.
 *
 * @param session     The CoAP session.
 * @param request_pdu The requesting PDU. If this PDU contains the Observe
 *                    option, the unsolocited responses will get handled by the
 *                    defined response handler. This PDU must be freed off by the
 *                    caller after processing.
 * @param response_pdu If there is a response, the response PDU is put here.
 *                     This PDU must be freed off by the caller after processing.
 * @param timeout_ms Positive maximum number of milliseconds to wait for response
 *                   packet following the request. If there is a large block transfer
 *                   this timeout is for between each request and response.
 *
 * @return 0 or +ve Time in function in ms after successful transfer (which can be
 *                  bigger than timeout_ms).
 *               -1 Invalid timeout parameter
 *               -2 Failed to transmit PDU
 *               -3 Nack or Event handler invoked, cancelling request
 *               -4 coap_io_process returned error (fail to re-lock or select())
 *               -5 Response not received in the given time
 *               -6 Terminated by user
 *               -7 Client mode code not enabled
 */
COAP_API int coap_send_recv(coap_session_t *session, coap_pdu_t *request_pdu,
                            coap_pdu_t **response_pdu, uint32_t timeout_ms);

void coap_send_recv_terminate(void);

COAP_API int coap_handle_event(coap_context_t *context,
                               coap_event_t event,
                               coap_session_t *session);
COAP_API int coap_can_exit(coap_context_t *context);

void coap_ticks(coap_tick_t *);

COAP_API int coap_join_mcast_group_intf(coap_context_t *ctx, const char *groupname,
                                        const char *ifname);
 
#define coap_join_mcast_group(ctx, groupname) \
  (coap_join_mcast_group_intf(ctx, groupname, NULL))

COAP_API int coap_endpoint_join_mcast_group_intf(coap_endpoint_t *endpoint,
                                                 const char *groupname,
                                                 const char *ifname);

int coap_mcast_set_hops(coap_session_t *session, size_t hops);

void coap_mcast_per_resource(coap_context_t *context);

COAP_DEPRECATED void coap_context_set_app_data(coap_context_t *context,
                                               void *data);

COAP_API void *coap_context_set_app_data2(coap_context_t *context, void *data,
                                          coap_app_data_free_callback_t callback);

void *coap_context_get_app_data(const coap_context_t *context);


 
#define COAP_IO_WAIT    0
#define COAP_IO_NO_WAIT ((uint32_t)-1)

COAP_API int coap_io_process(coap_context_t *ctx, uint32_t timeout_ms);
 
#if !defined(WITH_LWIP) && !defined(RIOT_VERSION) && !defined(WITH_CONTIKI)
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);
#endif /* ! WITH_LWIP && ! RIOT_VERSION && ! WITH_CONTIKI */

COAP_API int coap_io_pending(coap_context_t *context);

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
                                        );

COAP_API void coap_io_do_io(coap_context_t *ctx, coap_tick_t now);

COAP_API unsigned int coap_io_prepare_epoll(coap_context_t *ctx, coap_tick_t now);
 
struct epoll_event;

COAP_API void coap_io_do_epoll(coap_context_t *ctx, struct epoll_event *events,
                               size_t nevents);

typedef void (*coap_io_process_thread_t)(void *arg);

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);

void coap_io_process_terminate_loop(void);

int coap_io_process_configure_threads(coap_context_t *context,
                                      uint32_t thread_count);

COAP_API void coap_io_process_remove_threads(coap_context_t *context);

COAP_API coap_fd_t coap_socket_get_fd(coap_socket_t *socket);
 
/*
 * Get the current libcoap usage of file descriptors that are in a read or write pending state.
 *
 * @param context The current CoAP context.
 * @param read_fds Array to populate with file descriptors in the read pending state.
 * @param have_read_fds Updated with the number of fds found in read pending state.
 * @param max_read_fds Maximum size of read_fds[] array.
 * @param write_fds Array to populate with file descriptors in the write pending state.
 * @param have_write_fds Updated with the number of fds found in write pending state.
 * @param max_write_fds Maximum size of write_fds[] array.
 * @param rem_timeout_ms Remaining timeout time to next libcoap activity in milli-secs.
 *
 * @return @c 1 if successful, else @c 0 if error.
 */
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);

COAP_API coap_socket_flags_t coap_socket_get_flags(coap_socket_t *socket);

COAP_API void coap_socket_set_flags(coap_socket_t *socket, coap_socket_flags_t flags);

 
#if defined(WITH_LWIP) || defined(WITH_LWIP_MAN_CHECK) || defined(__DOXYGEN__)

void coap_lwip_dump_memory_pools(coap_log_t log_level);

typedef int (*coap_lwip_input_wait_handler_t)(void *arg, uint32_t milli_secs);

void coap_lwip_set_input_wait_handler(coap_context_t *context,
                                      coap_lwip_input_wait_handler_t handler,
                                      void *input_arg);

#endif /* WITH_LWIP || WITH_LWIP_MAN_CHECK || defined(__DOXYGEN__) */

#define coap_run_once(ctx, timeout_ms) coap_io_process(ctx, timeout_ms)

#define coap_write(ctx, sockets, max_sockets, num_sockets, now) \
  coap_io_prepare_io(ctx, sockets, max_sockets, num_sockets, now)

#define coap_read(ctx, now) coap_io_do_io(ctx, now)
 
/* Old definitions which may be hanging around in old code - be helpful! */
#define COAP_RUN_NONBLOCK COAP_RUN_NONBLOCK_deprecated_use_COAP_IO_NO_WAIT
#define COAP_RUN_BLOCK COAP_RUN_BLOCK_deprecated_use_COAP_IO_WAIT
 
#ifdef __cplusplus
}
#endif
 
#endif /* COAP_NET_H_ */