COAP_URI(3)

💅 COAP_URI(3) — your girl's guide to CoAP URIs 💅

okay so like, hi bestie!! welcome to the libcoap Manual ✨ this page is all about coap_uri, coap_split_uri, coap_split_proxy_uri, coap_new_uri, coap_clone_uri, coap_delete_uri, coap_uri_into_optlist and coap_uri_into_options — aka the whole "work with CoAP URIs" friend group. they're all icons, no cap 🫶

✨ NAME ✨

coap_uri, coap_split_uri, coap_split_proxy_uri, coap_new_uri, coap_clone_uri, coap_delete_uri, coap_uri_into_optlist, coap_uri_into_options — work with CoAP URIs 💖

---

🌸 SYNOPSIS 🌸

#include <coap3/coap.h>

int coap_split_uri(const uint8_t *uri_def, size_t length, coap_uri_t
*uri);

int coap_split_proxy_uri(const uint8_t *uri_def, size_t length,
coap_uri_t *uri);

coap_uri_t *coap_new_uri(const uint8_t *uri_def, unsigned int length);

coap_uri_t *coap_clone_uri(const coap_uri_t *uri);

void coap_delete_uri(coap_uri_t *uri);

int coap_uri_into_optlist(const coap_uri_t *uri, const coap_address_t
*dst, coap_optlist_t **optlist_chain, int create_port_host_opt);

int coap_uri_into_options(const coap_uri_t *uri, const coap_address_t
*dst, coap_optlist_t **optlist_chain, int create_port_host_opt, uint8_t
*buf, size_t buflen);

so like, for 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, link with -lcoap-3 to get the default (D)TLS library support. pick your fighter bestie 🎀

---

🦋 DESCRIPTION 🦋

this man page describes the functionality available to work with CoAP URIs and break them down into the component parts. it's giving demolition crew but make it cute 💅

a CoAP URI is of the form

<scheme><host><(optional):port><(optional)path><(optional)?query>

where scheme can be one of coap://, coaps://, coap+tcp:// and coaps+tcp://.

host can be an IPv4 or IPv6 (enclosed in []) address, a DNS resolvable name or a Unix domain socket name which is encoded as a unix file name with %2F replacing each / of the file name so that the start of the path can easily be determined. lowkey clever, right?? 🔥

(optional):port is ignored for Unix domain socket's host definitions. yeah, it's just not invited to that party 🙈

the parsed uri structure is of the form

typedef struct {
  coap_str_const_t host;  /* The host part of the URI */
  uint16_t port;          /* The port in host byte order */
  coap_str_const_t path;  /* The complete path if present or {0, NULL}.
                             Needs to be split using coap_path_into_optlist(3)
                             or coap_uri_into_optlist(). */
  coap_str_const_t query; /* The complete query if present or {0, NULL}.
                             Needs to be split using coap_query_into_optlist(3)
                             or coap_uri_into_optlist(). */
  enum coap_uri_scheme_t scheme; /* The parsed scheme specifier. */
} coap_uri_t;

---

🌈 FUNCTIONS 🌈

👑 Function: coap_split_uri()

the coap_split_uri() function is used to parse the provided uri_def of length length into the component parts held in the uri structure. these component parts are the host, port, path, query and the CoAP URI scheme. she does it all, main character energy fr fr 💜

🧚 Function: coap_split_proxy_uri()

the coap_split_proxy_uri() function is used to parse the provided uri_def of length length into the component parts held in the uri structure. these component parts are the host, port, path, query and the URI scheme. the schemes also includes support for http:// and https:// as the proxy may need to be a coap-to-http proxy. yes bestie, she's bilingual 😭✨

🍓 Function: coap_new_uri()

the coap_new_uri() function creates a new coap_uri_t structure and populates it using coap_split_uri() with uri_def and length as input. the returned coap_uri_t structure needs to be freed off using coap_delete_uri(). don't ghost her, clean up after yourself 🫶

⭐ Function: coap_clone_uri()

the coap_clone_uri() function duplicates a uri coap_uri_t structure. the returned coap_uri_t structure needs to be freed off using coap_delete_uri(). twin where have you been 💀

🎀 Function: coap_delete_uri()

the coap_delete_uri() function frees off a previously created uri coap_uri_t structure. be free bestie 🦋

🔥 Function: coap_uri_into_optlist()

the coap_uri_into_optlist() function takes the uri structure and then takes CoAP options derived from this information and adds them to optlist_chain. the initial optlist_chain entry should be set to NULL before this function is called (unless coap_insert_optlist(3) has been previously used). set it to NULL first, i'm serious, that's the vibe check 👀

if dst is not NULL and create_port_host_opt is not 0, then the Uri-Host option is added in if the uri host definition is not an exact match with the ascii readable version of dst.

if the port is not the default port and create_port_host_opt is not 0, then the Uri-Port option is added to optlist_chain.

if there is a path, then this is broken down into individual Uri-Path options for each segment which are then added to optlist_chain. chopping it up, per segment, we love a systematic queen 💅

likewise, if there is a query, individual Uri-Query options for each segment are then added to optlist_chain.

NOTE: it is the responsibility of the application to free off the entries added to optlist_chain using coap_delete_optlist(3). that's on you bestie, don't come crying to me about leaks 😭

🌸 Function: coap_uri_into_options()

the coap_uri_into_options() function has the same functionality as coap_uri_into_optlist() except that buf and buflen are ignored, but the return values are different. yes, ignored — they're just there for the aesthetic 🙈

---

💖 RETURN VALUES 💖

coap_split_uri(), coap_split_proxy_uri(), and coap_uri_into_options() return 0 on success, else < 0 on failure. so like, zero is the slay number here ⭐

coap_uri_into_optlist() returns 1 on success, 0 on failure. different scale, same drama 💀

coap_new_uri() and coap_clone_uri() return a newly allocated coap_uri_t structure or NULL on failure.

---

🧚 EXAMPLES 🧚

Setup PDU and Transmit

#include <coap3/coap.h>

/*
 * Returns 0 failure, 1 success
 */
static int
parse_and_send_uri(coap_session_t *session, const char *do_uri) {
  coap_uri_t uri;
  coap_optlist_t *optlist = NULL;
  coap_pdu_t *pdu;
  coap_proto_t proto = coap_session_get_proto(session);
  const coap_address_t *dst = coap_session_get_addr_remote(session);
  int res;
  coap_mid_t mid;

  /* Parse the URI */
  res = coap_split_uri((const uint8_t *)do_uri, strlen(do_uri), &uri);
  if (res != 0)
    return 0;

  /* Check the scheme matches the session type */
  switch (uri.scheme) {
  case COAP_URI_SCHEME_COAP:
    if (proto != COAP_PROTO_UDP)
      return 0;
    break;
  case COAP_URI_SCHEME_COAPS:
    if (proto != COAP_PROTO_DTLS)
      return 0;
    break;
  case COAP_URI_SCHEME_COAP_TCP:
    if (proto != COAP_PROTO_TCP)
      return 0;
    break;
  case COAP_URI_SCHEME_COAPS_TCP:
    if (proto != COAP_PROTO_TLS)
      return 0;
    break;
  case COAP_URI_SCHEME_COAP_WS:
    if (proto != COAP_PROTO_WS)
      return 0;
    break;
  case COAP_URI_SCHEME_COAPS_WS:
    if (proto != COAP_PROTO_WSS)
      return 0;
    break;
  /* Proxy support only */
  case COAP_URI_SCHEME_HTTP:
  case COAP_URI_SCHEME_HTTPS:
  case COAP_URI_SCHEME_LAST:
  default:
    return 0;
  }

  /* construct CoAP message */
  pdu = coap_pdu_init(COAP_MESSAGE_CON,
                      COAP_REQUEST_CODE_GET,
                      coap_new_message_id(session),
                      coap_session_max_pdu_size(session));
  if (pdu == NULL)
    return 0;

  /* Create all the necessary options from the URI */
  if (!coap_uri_into_optlist(&uri, dst, &optlist, 1))
    return 0;

  /* Add option list (which will get sorted) to the PDU */
  if (optlist) {
    res = coap_add_optlist_pdu(pdu, &optlist);
    coap_delete_optlist(optlist);
    if (res != 1)
      return 0;
  }

  /* and send the PDU */
  mid = coap_send(session, pdu);
  if (mid == COAP_INVALID_MID)
    return 0;
  return 1;
}

---

🔍 SEE ALSO 🔍

coap_endpoint_client(3) and coap_pdu_setup(3). go read those too, iykyk 💜

---

🌟 FURTHER INFORMATION 🌟

see

"RFC7252: The Constrained Application Protocol (CoAP)"

for further information. required reading bestie, sorry not sorry 📚

---

💀 BUGS 💀

please raise an issue on GitHub at https://github.com/obgm/libcoap/issues to report any bugs. don't suffer in silence, tell the group chat 🫶

please raise a Pull Request at https://github.com/obgm/libcoap/pulls for any fixes. be the change you want to see in the codebase ✨

---

🎀 AUTHORS 🎀

the libcoap project <libcoap-developers@lists.sourceforge.net> — literal legends 👑

---

and that's the whole page bestie, you ate that 💅 this was coap_uri version 4.3.5, dated 08/24/2026, from the libcoap fam — now go out there and parse some URIs, periodt 🦋✨