1// -*- mode:doc; -*- 2// vim: set syntax=asciidoc tw=0 3 4coap_uri(3) 5============ 6:doctype: manpage 7:man source: coap_uri 8:man version: @PACKAGE_VERSION@ 9:man manual: libcoap Manual 10 11NAME 12---- 13coap_uri, 14coap_split_uri, 15coap_split_proxy_uri, 16coap_new_uri, 17coap_clone_uri, 18coap_delete_uri, 19coap_uri_into_options 20- Work with CoAP URIs 21 22SYNOPSIS 23-------- 24*#include <coap@LIBCOAP_API_VERSION@/coap.h>* 25 26*int coap_split_uri(const uint8_t *_uri_def_, size_t _length_, 27coap_uri_t *_uri_);* 28 29*int coap_split_proxy_uri(const uint8_t *_uri_def_, size_t _length_, 30coap_uri_t *_uri_);* 31 32*coap_uri_t *coap_new_uri(const uint8_t *_uri_def_, unsigned int _length_);* 33 34*coap_uri_t *coap_clone_uri(const coap_uri_t *_uri_);* 35 36*void coap_delete_uri(coap_uri_t *_uri_);* 37 38*int coap_uri_into_options(const coap_uri_t *_uri_, 39const coap_address_t *_dst_, coap_optlist_t **_optlist_chain_, 40int _create_port_host_opt_, uint8_t *_buf_, size_t _buflen_);* 41 42For specific (D)TLS library support, link with 43*-lcoap-@LIBCOAP_API_VERSION@-notls*, *-lcoap-@LIBCOAP_API_VERSION@-gnutls*, 44*-lcoap-@LIBCOAP_API_VERSION@-openssl*, *-lcoap-@LIBCOAP_API_VERSION@-mbedtls* 45or *-lcoap-@LIBCOAP_API_VERSION@-tinydtls*. Otherwise, link with 46*-lcoap-@LIBCOAP_API_VERSION@* to get the default (D)TLS library support. 47 48DESCRIPTION 49----------- 50This man page describes the functionality available to work with CoAP URIs and 51break them down into the component parts. 52 53A CoAP URI is of the form 54 55<scheme><host><(optional):port><(optional)path><(optional)?query> 56 57where _scheme_ can be one of coap://, coaps://, coap+tcp:// and coaps+tcp://. 58 59_host_ can be an IPv4 or IPv6 (enclosed in []) address, a DNS resolvable name or 60a Unix domain socket name which is encoded as a unix file name with %2F 61replacing each / of the file name so that the start of the _path_ can easily be 62determined. 63 64'(optional):port' is ignored for Unix domain socket's _host_ definitions. 65 66The parsed uri structure is of the form 67 68[source, c] 69---- 70typedef struct { 71 coap_str_const_t host; /* The host part of the URI */ 72 uint16_t port; /* The port in host byte order */ 73 coap_str_const_t path; /* The complete path if present or {0, NULL}. 74 Needs to be split using coap_split_path() 75 or coap_uri_into_options(). */ 76 coap_str_const_t query; /* The complete query if present or {0, NULL}. 77 Needs to be split using coap_split_query() 78 or coap_uri_into_options(). */ 79 enum coap_uri_scheme_t scheme; /* The parsed scheme specifier. */ 80} coap_uri_t; 81---- 82 83FUNCTIONS 84--------- 85 86*Function: coap_split_uri()* 87 88The *coap_split_uri*() function is used to parse the provided _uri_def_ of 89length _length_ into the component parts held in the _uri_ structure. These 90component parts are the host, port, path, query and the CoAP URI scheme. 91 92*Function: coap_split_proxy_uri()* 93 94The *coap_split_proxy_uri*() function is used to parse the provided _uri_def_ of 95length _length_ into the component parts held in the _uri_ structure. These 96component parts are the host, port, path, query and the URI scheme. The 97schemes also includes support for http:// and https:// as the proxy may need to 98be a coap-to-http proxy. 99 100*Function: coap_new_uri()* 101 102The *coap_new_uri*() function creates a new coap_uri_t structure and populates 103it using *coap_split_uri*() with _uri_def_ and _length_ as input. The returned 104coap_uri_t structure needs to be freed off using *coap_delete_uri*(). 105 106*Function: coap_clone_uri()* 107 108The *coap_clone_uri*() function duplicates a _uri_ coap_uri_t structure. 109The returned coap_uri_t structure needs to be freed off using 110*coap_delete_uri*(). 111 112*Function: coap_delete_uri()* 113 114The *coap_delete_uri*() function frees off a previously created _uri_ 115coap_uri_t structure. 116 117*Function: coap_uri_into_options()* 118 119The *coap_uri_into_options*() function takes the _uri_ structure and then takes 120CoAP options derived from this information and adds them to _optlist_chain_. 121The initial _optlist_chain_ entry should be set to NULL before 122this function is called (unless *coap_insert_optlist*(3) has been previously 123used). 124 125If _dst_ is not NULL and _create_port_host_opt_ is not 0, then the Uri-Host 126option is added in if the _uri_ host definition is not an exact match with the 127ascii readable version of _dst. 128 129If the port is not the default port and _create_port_host_opt_ is not 0, then 130the Port option is added to _optlist_chain_. 131 132If there is a path, then this is broken down into individual Path options for 133each segment which are then added to _optlist_chain_. 134 135Likewise, if 136there is a query, individual Query options for each segment are then added to 137_optlist_chain_. 138 139_buf_ provides a scratch buffer to use, of size _buflen_ bytes. _buf_ needs 140to be as big as the path or query lengths. 141 142*NOTE:* It is the responsibility of the application to free off the entries 143added to _optlist_chain_ using *coap_delete_optlist*(3). 144 145RETURN VALUES 146------------- 147*coap_split_uri*(), *coap_split_proxy_uri*(), and 148*coap_uri_into_options*() return 0 on success, else < 0 on failure. 149 150*coap_new_uri*() and *coap_clone_uri*() return a newly allocated coap_uri_t 151structure or NULL on failure. 152 153EXAMPLES 154-------- 155*Setup PDU and Transmit* 156 157[source, c] 158---- 159#include <coap@LIBCOAP_API_VERSION@/coap.h> 160 161/* 162 * Returns 0 failure, 1 success 163 */ 164static int 165parse_and_send_uri(coap_session_t *session, const char *do_uri) { 166 coap_uri_t uri; 167 coap_optlist_t *optlist = NULL; 168 coap_pdu_t *pdu; 169 coap_proto_t proto = coap_session_get_proto(session); 170 const coap_address_t *dst = coap_session_get_addr_remote(session); 171 int res; 172 coap_mid_t mid; 173#define BUFSIZE 100 174 unsigned char buf[BUFSIZE]; 175 176 /* Parse the URI */ 177 res = coap_split_uri((const uint8_t*)do_uri, strlen(do_uri), &uri); 178 if (res != 0) 179 return 0; 180 181 /* Check the scheme matches the session type */ 182 switch (uri.scheme) { 183 case COAP_URI_SCHEME_COAP: 184 if (proto != COAP_PROTO_UDP) 185 return 0; 186 break; 187 case COAP_URI_SCHEME_COAPS: 188 if (proto != COAP_PROTO_DTLS) 189 return 0; 190 break; 191 case COAP_URI_SCHEME_COAP_TCP: 192 if (proto != COAP_PROTO_TCP) 193 return 0; 194 break; 195 case COAP_URI_SCHEME_COAPS_TCP: 196 if (proto != COAP_PROTO_TLS) 197 return 0; 198 break; 199 case COAP_URI_SCHEME_COAP_WS: 200 if (proto != COAP_PROTO_WS) 201 return 0; 202 break; 203 case COAP_URI_SCHEME_COAPS_WS: 204 if (proto != COAP_PROTO_WSS) 205 return 0; 206 break; 207 /* Proxy support only */ 208 case COAP_URI_SCHEME_HTTP: 209 case COAP_URI_SCHEME_HTTPS: 210 case COAP_URI_SCHEME_LAST: 211 default: 212 return 0; 213 } 214 215 /* construct CoAP message */ 216 pdu = coap_pdu_init(COAP_MESSAGE_CON, 217 COAP_REQUEST_CODE_GET, 218 coap_new_message_id(session), 219 coap_session_max_pdu_size(session)); 220 if (pdu == NULL) 221 return 0; 222 223 /* Create all the necessary options from the URI */ 224 res = coap_uri_into_options(&uri, dst, &optlist, 1, buf, sizeof(buf)); 225 if (res != 0) 226 return 0; 227 228 /* Add option list (which will get sorted) to the PDU */ 229 if (optlist) { 230 res = coap_add_optlist_pdu(pdu, &optlist); 231 coap_delete_optlist(optlist); 232 if (res != 1) 233 return 0; 234 } 235 236 /* and send the PDU */ 237 mid = coap_send(session, pdu); 238 if (mid == COAP_INVALID_MID) 239 return 0; 240 return 1; 241} 242 243---- 244 245SEE ALSO 246-------- 247*coap_endpoint_client*(3) and *coap_pdu_setup*(3). 248 249FURTHER INFORMATION 250------------------- 251See 252 253"https://rfc-editor.org/rfc/rfc7252[RFC7252: The Constrained Application Protocol (CoAP)]" 254 255for further information. 256 257BUGS 258---- 259Please report bugs on the mailing list for libcoap: 260libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at 261https://github.com/obgm/libcoap/issues 262 263AUTHORS 264------- 265The libcoap project <libcoap-developers@lists.sourceforge.net> 266