'\" t
.\"     Title: coap_uri
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      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 <coap3/coap\&.h>\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
<scheme><host><(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 <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;
#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 <libcoap\-developers@lists\&.sourceforge\&.net>