'\" t
.\" Title: coap_uri
.\" Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 10/28/2023
.\" Manual: libcoap Manual
.\" Source: coap_uri 4.3.4
.\" Language: English
.\"
.TH "COAP_URI" "3" "10/28/2023" "coap_uri 4\&.3\&.4" "libcoap Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "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
.SH "SYNOPSIS"
.sp
\fB#include \fR
.sp
\fBint coap_split_uri(const uint8_t *\fR\fB\fIuri_def\fR\fR\fB, size_t \fR\fB\fIlength\fR\fR\fB, coap_uri_t *\fR\fB\fIuri\fR\fR\fB);\fR
.sp
\fBint coap_split_proxy_uri(const uint8_t *\fR\fB\fIuri_def\fR\fR\fB, size_t \fR\fB\fIlength\fR\fR\fB, coap_uri_t *\fR\fB\fIuri\fR\fR\fB);\fR
.sp
\fBcoap_uri_t *coap_new_uri(const uint8_t *\fR\fB\fIuri_def\fR\fR\fB, unsigned int \fR\fB\fIlength\fR\fR\fB);\fR
.sp
\fBcoap_uri_t *coap_clone_uri(const coap_uri_t *\fR\fB\fIuri\fR\fR\fB);\fR
.sp
\fBvoid coap_delete_uri(coap_uri_t *\fR\fB\fIuri\fR\fR\fB);\fR
.sp
\fBint coap_uri_into_options(const coap_uri_t *\fR\fB\fIuri\fR\fR\fB, const coap_address_t *\fR\fB\fIdst\fR\fR\fB, coap_optlist_t **\fR\fB\fIoptlist_chain\fR\fR\fB, int \fR\fB\fIcreate_port_host_opt\fR\fR\fB, uint8_t *\fR\fB\fIbuf\fR\fR\fB, size_t \fR\fB\fIbuflen\fR\fR\fB);\fR
.sp
For specific (D)TLS library support, link with \fB\-lcoap\-3\-notls\fR, \fB\-lcoap\-3\-gnutls\fR, \fB\-lcoap\-3\-openssl\fR, \fB\-lcoap\-3\-mbedtls\fR or \fB\-lcoap\-3\-tinydtls\fR\&. Otherwise, link with \fB\-lcoap\-3\fR to get the default (D)TLS library support\&.
.SH "DESCRIPTION"
.sp
This man page describes the functionality available to work with CoAP URIs and break them down into the component parts\&.
.sp
A CoAP URI is of the form
.sp
<(optional):port><(optional)path><(optional)?query>
.sp
where \fIscheme\fR can be one of coap://, coaps://, coap+tcp:// and coaps+tcp://\&.
.sp
\fIhost\fR 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 \fIpath\fR can easily be determined\&.
.sp
\fI(optional):port\fR is ignored for Unix domain socket\(cqs \fIhost\fR definitions\&.
.sp
The parsed uri structure is of the form
.sp
.if n \{\
.RS 4
.\}
.nf
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;
.fi
.if n \{\
.RE
.\}
.SH "FUNCTIONS"
.sp
\fBFunction: coap_split_uri()\fR
.sp
The \fBcoap_split_uri\fR() function is used to parse the provided \fIuri_def\fR of length \fIlength\fR into the component parts held in the \fIuri\fR structure\&. These component parts are the host, port, path, query and the CoAP URI scheme\&.
.sp
\fBFunction: coap_split_proxy_uri()\fR
.sp
The \fBcoap_split_proxy_uri\fR() function is used to parse the provided \fIuri_def\fR of length \fIlength\fR into the component parts held in the \fIuri\fR 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\&.
.sp
\fBFunction: coap_new_uri()\fR
.sp
The \fBcoap_new_uri\fR() function creates a new coap_uri_t structure and populates it using \fBcoap_split_uri\fR() with \fIuri_def\fR and \fIlength\fR as input\&. The returned coap_uri_t structure needs to be freed off using \fBcoap_delete_uri\fR()\&.
.sp
\fBFunction: coap_clone_uri()\fR
.sp
The \fBcoap_clone_uri\fR() function duplicates a \fIuri\fR coap_uri_t structure\&. The returned coap_uri_t structure needs to be freed off using \fBcoap_delete_uri\fR()\&.
.sp
\fBFunction: coap_delete_uri()\fR
.sp
The \fBcoap_delete_uri\fR() function frees off a previously created \fIuri\fR coap_uri_t structure\&.
.sp
\fBFunction: coap_uri_into_options()\fR
.sp
The \fBcoap_uri_into_options\fR() function takes the \fIuri\fR structure and then takes CoAP options derived from this information and adds them to \fIoptlist_chain\fR\&. The initial \fIoptlist_chain\fR entry should be set to NULL before this function is called (unless \fBcoap_insert_optlist\fR(3) has been previously used)\&.
.sp
If \fIdst\fR is not NULL and \fIcreate_port_host_opt\fR is not 0, then the Uri\-Host option is added in if the \fIuri\fR host definition is not an exact match with the ascii readable version of _dst\&.
.sp
If the port is not the default port and \fIcreate_port_host_opt\fR is not 0, then the Port option is added to \fIoptlist_chain\fR\&.
.sp
If there is a path, then this is broken down into individual Path options for each segment which are then added to \fIoptlist_chain\fR\&.
.sp
Likewise, if there is a query, individual Query options for each segment are then added to \fIoptlist_chain\fR\&.
.sp
\fIbuf\fR provides a scratch buffer to use, of size \fIbuflen\fR bytes\&. \fIbuf\fR needs to be as big as the path or query lengths\&.
.sp
\fBNOTE:\fR It is the responsibility of the application to free off the entries added to \fIoptlist_chain\fR using \fBcoap_delete_optlist\fR(3)\&.
.SH "RETURN VALUES"
.sp
\fBcoap_split_uri\fR(), \fBcoap_split_proxy_uri\fR(), and \fBcoap_uri_into_options\fR() return 0 on success, else < 0 on failure\&.
.sp
\fBcoap_new_uri\fR() and \fBcoap_clone_uri\fR() return a newly allocated coap_uri_t structure or NULL on failure\&.
.SH "EXAMPLES"
.sp
\fBSetup PDU and Transmit\fR
.sp
.if n \{\
.RS 4
.\}
.nf
#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;
}
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.sp
\fBcoap_endpoint_client\fR(3) and \fBcoap_pdu_setup\fR(3)\&.
.SH "FURTHER INFORMATION"
.sp
See
.sp
"RFC7252: The Constrained Application Protocol (CoAP)"
.sp
for further information\&.
.SH "BUGS"
.sp
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
.SH "AUTHORS"
.sp
The libcoap project