--- name: "coap_uri" section: "3" platform: "linux" package: "libcoap3t64" version: "4.3.4-1.1+deb13u3" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/coap_uri" --- # coap\_uri(3) Work with CoAP URIs ## NAME coap\_uri, coap\_split\_uri, coap\_split\_proxy\_uri, coap\_new\_uri, coap\_clone\_uri, coap\_delete\_uri, coap\_uri\_into\_options - Work with CoAP URIs ## SYNOPSIS **#include \** **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\_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***);** For specific (D)TLS library support, link with **-lcoap-3-notls**, **-lcoap-3-gnutls**, **-lcoap-3-openssl**, **-lcoap-3-mbedtls** or **-lcoap-3-tinydtls**. Otherwise, link with **-lcoap-3** to get the default (D)TLS library support. ## DESCRIPTION This man page describes the functionality available to work with CoAP URIs and break them down into the component parts. A CoAP URI is of the form \\\<(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. *(optional):port* is ignored for Unix domain socket’s *host* definitions. 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_split_path() or coap_uri_into_options(). */ coap_str_const_t query; /* The complete query if present or {0, NULL}. Needs to be split using coap_split_query() or coap_uri_into_options(). */ 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. **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. **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**(). **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**(). **Function: coap\_delete\_uri()** The **coap\_delete\_uri**() function frees off a previously created *uri* coap\_uri\_t structure. **Function: coap\_uri\_into\_options()** The **coap\_uri\_into\_options**() 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)](/coap_insert_optlist/3.md) has been previously used). 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 Port option is added to *optlist\_chain*. If there is a path, then this is broken down into individual Path options for each segment which are then added to *optlist\_chain*. Likewise, if there is a query, individual Query options for each segment are then added to *optlist\_chain*. *buf* provides a scratch buffer to use, of size *buflen* bytes. *buf* needs to be as big as the path or query lengths. **NOTE:** It is the responsibility of the application to free off the entries added to *optlist\_chain* using [**coap\_delete\_optlist**(3)](/coap_delete_optlist/3.md). ## RETURN VALUES **coap\_split\_uri**(), **coap\_split\_proxy\_uri**(), and **coap\_uri\_into\_options**() return 0 on success, else \< 0 on failure. **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 /* * 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; #define BUFSIZE 100 unsigned char buf[BUFSIZE]; /* 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 */ res = coap_uri_into_options(&uri, dst, &optlist, 1, buf, sizeof(buf)); if (res != 0) 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)](/coap_endpoint_client/3.md) and [**coap\_pdu\_setup**(3)](/coap_pdu_setup/3.md). ## FURTHER INFORMATION See "RFC7252: The Constrained Application Protocol (CoAP)" for further information. ## BUGS Please report bugs on the mailing list for libcoap: libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at https://github.com/obgm/libcoap/issues ## AUTHORS The libcoap project \