COAP_DEPRECATED(3)

📦
version 4.3.5b · 7 versions
, in alpine 3.24

okay so welcome to COAP_DEPRECATED(3) bestie 💖 this page lives in the libcoap Manual and honestly? it's the glow-up guide nobody asked for but everybody needs. it's the "these functions are so last season, here's what's serving now" page. no cap.

✨ NAME ✨

coap_deprecated, coap_clear_event_handler, coap_context_get_csm_timeout, coap_context_set_csm_timeout, coap_context_set_psk, coap_encode_var_bytes, coap_new_client_session_psk, coap_option_clrb, coap_option_getb, coap_option_setb, coap_read, coap_register_handler, coap_resource_set_dirty, coap_run_once, coap_set_event_handler, coap_write, coap_get_app_data, coap_set_app_data — aka the whole "work with CoAP deprecated functions" situation 🫶

🌸 SYNOPSIS 🌸

#include <coap3/coap.h>

void coap_clear_event_handler(coap_context_t *context);

unsigned int coap_context_get_csm_timeout(const coap_context_t *context);

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

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

int coap_encode_var_bytes(uint8_t *buffer, unsigned int value);

coap_session_t *coap_new_client_session_psk(coap_context_t *context, const coap_address_t *local_if, const coap_address_t *server, coap_proto_t proto, const char *identity, const uint8_t *key, unsigned key_len);

int coap_option_clrb(coap_opt_filter_t *filter, uint16_t type);

int coap_option_getb(coap_opt_filter_t *filter, uint16_t type);

int coap_option_setb(coap_opt_filter_t *filter, uint16_t type);

void coap_read(coap_context_t *context, coap_tick_t now);

void coap_register_handler(coap_resource_t *resource, coap_request_t method, coap_method_handler_t handler);

int coap_resource_set_dirty(coap_resource_t *resource, const coap_string_t *query);

int coap_run_once(coap_context_t *context, uint32_t timeout_ms);

void coap_set_event_handler(coap_context_t *context, coap_event_handler_t handler);

unsigned int coap_write(coap_context_t *context, coap_socket_t *sockets[], unsigned int max_sockets, unsigned int *num_sockets, coap_tick_t now);

void coap_set_app_data(coap_context_t *context, void *app_data);

void *coap_get_app_data(const coap_context_t *context);

and for the specific (D)TLS library support, you link with -lcoap-3-notls, -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls, -lcoap-3-wolfssl or -lcoap-3-tinydtls. otherwise you link with -lcoap-3 and you get whatever the default (D)TLS library support is. pick your fighter 🥊

🦋 DESCRIPTION 🦋

so several of the existing CoAP API functions have been deprecated 💀 like, they still exist, but they're giving "we don't talk about bruno" energy.

they're all listed here on this page, and right next to each one is the function that should now be used instead. it's a whole before/after moment, a makeover montage, if you will ✨

💅 FUNCTIONS 💅

Function: coap_clear_event_handler()

coap_clear_event_handler() is replaced by coap_register_event_handler(3), using NULL for handler.

Function: coap_context_get_csm_timeout()

coap_context_get_csm_timeout() is replaced by coap_context_get_csm_timeout_ms(3) — and the new one returns milli-secs instead of seconds. tiny unit glow-up, big difference ⏱️

Function: coap_context_set_csm_timeout()

coap_context_set_csm_timeout() is replaced by coap_context_set_csm_timeout_ms(3), by defining milli-secs instead of seconds. same deal, just the metric prefix said "let me cook" 🍳

Function: coap_context_set_psk()

coap_context_set_psk() is replaced by coap_context_set_psk2(3), which gives you additional PSK configuration capability by the use of the coap_dtls_spsk_t structure. more knobs, more slay 🔐

Function: coap_encode_var_bytes()

coap_encode_var_bytes() is replaced by coap_encode_var_safe(3). the name literally tells you it's the safe one, bestie 🧚

Function: coap_new_client_session_psk()

coap_new_client_session_psk() is replaced by coap_new_client_session_psk2(3), which gives you additional PSK configuration capability by the use of the coap_dtls_cpsk_t structure. yes there's a 2, yes it's the main character 👑

Function: coap_option_clrb()

coap_option_clrb() is replaced by coap_option_filter_unset(3).

Function: coap_option_getb()

coap_option_getb() is replaced by coap_option_filter_get(3).

Function: coap_option_setb()

coap_option_setb() is replaced by coap_option_filter_set(3).

Function: coap_read()

coap_read() is replaced by coap_io_do_io(3).

Function: coap_register_handler()

coap_register_handler() is replaced by coap_register_request_handler(3).

Function: coap_resource_set_dirty()

coap_resource_set_dirty() is replaced by coap_resource_notify_observers(3).

Function: coap_run_once()

coap_run_once() is replaced by coap_io_process(3).

Function: coap_set_event_handler()

coap_set_event_handler() is replaced by coap_register_event_handler(3).

Function: coap_clear_event_handler()

The coap_write() function is replaced by coap_io_prepare_io(3).

okay so yes, the heading up there literally says coap_clear_event_handler() a second time while the body is talking about coap_write(). that's just how the page is, bestie 🙈 i'm reporting what's on the page, not fixing it — that's a job for the GitHub links down below 💀

Function: coap_set_app_data()

coap_set_app_data() is replaced by coap_context_set_app_data(3).

Function: coap_get_app_data()

coap_get_app_data() is replaced by coap_context_get_app_data(3).

🔥 RETURN VALUES 🔥

here's the vibe check on what each one hands back to you:

  • coap_context_get_csm_timeout() returns the seconds to wait for a (TCP) CSM negotiation response from the peer.
  • coap_context_set_psk() returns 1 if success, 0 on failure.
  • coap_encode_var_bytes() returns either the length of bytes encoded (which can be 0 when encoding 0) or 0 on failure. yes, both of those are 0. live with it 🫠
  • coap_new_client_session_psk() returns a new session if success, NULL on failure.
  • coap_option_clrb() returns 1 if bit was set, -1 otherwise.
  • coap_option_getb() returns 1 if bit was set, 0 if not.
  • coap_option_setb() returns 1 if bit was set, -1 otherwise.
  • coap_resource_set_dirty() returns 1 if success, 0 on failure.
  • coap_run_once() returns number of milliseconds spent in function or -1 if there was an error.
  • coap_write() returns the number of milli-seconds that need to be waited before the function should next be called.
  • coap_get_app_data() returns a previously defined pointer.

👀 SEE ALSO 👀

like, go read these next, i'm obsessed:

coap_context(3), coap_endpoint_client(3), coap_endpoint_server(3), coap_handler(3), coap_io(3), coap_observe(3), coap_pdu_access(3) and coap_pdu_setup(3).

🌈 FURTHER INFORMATION 🌈

See

"RFC7252: The Constrained Application Protocol (CoAP)"

for further information. it's giving required reading, but like, in a fun way 📚

🍓 BUGS 🍓

spotted something cursed? Please raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report any bugs. 🐛

got a fix and you're feeling generous? Please raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes. be the change you want to see in the source tree 💜

🎀 AUTHORS 🎀

The libcoap project <libcoap-developers@lists.sourceforge.net> — they ate, fr fr 💖

and that's the whole thing, bestie! this little masterpiece is coap_deprecated version 4.3.5b, dated 04/28/2026 — screenshot it, frame it, cite it in your PR description. mwah 💋 COAP_DEPRECATED(3) out! 🦋✨

📦 where this page comes from