1COAP_URI(3) libcoap Manual COAP_URI(3)
2
6 coap_uri, coap_split_uri, coap_split_proxy_uri, coap_new_uri,
7 coap_clone_uri, coap_delete_uri, coap_uri_into_options - Work with CoAP
8 URIs
9
11 #include <coap3/coap.h>
12 int coap_split_uri(const uint8_t *uri_def, size_t length, coap_uri_t
14 *uri);
15 int coap_split_proxy_uri(const uint8_t *uri_def, size_t length,
17 coap_uri_t *uri);
18 coap_uri_t *coap_new_uri(const uint8_t *uri_def, unsigned int length);
20 coap_uri_t *coap_clone_uri(const coap_uri_t *uri);
22 void coap_delete_uri(coap_uri_t *uri);
24 int coap_uri_into_options(const coap_uri_t *uri, const coap_address_t
26 *dst, coap_optlist_t **optlist_chain, int create_port_host_opt, uint8_t
27 *buf, size_t buflen);
28 For specific (D)TLS library support, link with -lcoap-3-notls,
30 -lcoap-3-gnutls, -lcoap-3-openssl, -lcoap-3-mbedtls or
31 -lcoap-3-tinydtls. Otherwise, link with -lcoap-3 to get the default
32 (D)TLS library support.
33
35 This man page describes the functionality available to work with CoAP
36 URIs and break them down into the component parts.
37 A CoAP URI is of the form
39 <scheme><host><(optional):port><(optional)path><(optional)?query>
41 where scheme can be one of coap://, coaps://, coap+tcp:// and
43 coaps+tcp://.
44 host can be an IPv4 or IPv6 (enclosed in []) address, a DNS resolvable
46 name or a Unix domain socket name which is encoded as a unix file name
47 with %2F replacing each / of the file name so that the start of the
48 path can easily be determined.
49 (optional):port is ignored for Unix domain socket’s host definitions.
51 The parsed uri structure is of the form
53 typedef struct {
55 coap_str_const_t host; /* The host part of the URI */
56 uint16_t port; /* The port in host byte order */
57 coap_str_const_t path; /* The complete path if present or {0, NULL}.
58 Needs to be split using coap_split_path()
59 or coap_uri_into_options(). */
60 coap_str_const_t query; /* The complete query if present or {0, NULL}.
61 Needs to be split using coap_split_query()
62 or coap_uri_into_options(). */
63 enum coap_uri_scheme_t scheme; /* The parsed scheme specifier. */
64 } coap_uri_t;
65
67 Function: coap_split_uri()
68 The coap_split_uri() function is used to parse the provided uri_def of
70 length length into the component parts held in the uri structure. These
71 component parts are the host, port, path, query and the CoAP URI
72 scheme.
73 Function: coap_split_proxy_uri()
75 The coap_split_proxy_uri() function is used to parse the provided
77 uri_def of length length into the component parts held in the uri
78 structure. These component parts are the host, port, path, query and
79 the URI scheme. The schemes also includes support for http:// and
80 https:// as the proxy may need to be a coap-to-http proxy.
81 Function: coap_new_uri()
83 The coap_new_uri() function creates a new coap_uri_t structure and
85 populates it using coap_split_uri() with uri_def and length as input.
86 The returned coap_uri_t structure needs to be freed off using
87 coap_delete_uri().
88 Function: coap_clone_uri()
90 The coap_clone_uri() function duplicates a uri coap_uri_t structure.
92 The returned coap_uri_t structure needs to be freed off using
93 coap_delete_uri().
94 Function: coap_delete_uri()
96 The coap_delete_uri() function frees off a previously created uri
98 coap_uri_t structure.
99 Function: coap_uri_into_options()
101 The coap_uri_into_options() function takes the uri structure and then
103 takes CoAP options derived from this information and adds them to
104 optlist_chain. The initial optlist_chain entry should be set to NULL
105 before this function is called (unless coap_insert_optlist(3) has been
106 previously used).
107 If dst is not NULL and create_port_host_opt is not 0, then the Uri-Host
109 option is added in if the uri host definition is not an exact match
110 with the ascii readable version of _dst.
111 If the port is not the default port and create_port_host_opt is not 0,
113 then the Port option is added to optlist_chain.
114 If there is a path, then this is broken down into individual Path
116 options for each segment which are then added to optlist_chain.
117 Likewise, if there is a query, individual Query options for each
119 segment are then added to optlist_chain.
120 buf provides a scratch buffer to use, of size buflen bytes. buf needs
122 to be as big as the path or query lengths.
123 NOTE: It is the responsibility of the application to free off the
125 entries added to optlist_chain using coap_delete_optlist(3).
126
128 coap_split_uri(), coap_split_proxy_uri(), and coap_uri_into_options()
129 return 0 on success, else < 0 on failure.
130 coap_new_uri() and coap_clone_uri() return a newly allocated coap_uri_t
132 structure or NULL on failure.
133
135 Setup PDU and Transmit
136 #include <coap3/coap.h>
138 /*
140 * Returns 0 failure, 1 success
141 */
142 static int
143 parse_and_send_uri(coap_session_t *session, const char *do_uri) {
144 coap_uri_t uri;
145 coap_optlist_t *optlist = NULL;
146 coap_pdu_t *pdu;
147 coap_proto_t proto = coap_session_get_proto(session);
148 const coap_address_t *dst = coap_session_get_addr_remote(session);
149 int res;
150 coap_mid_t mid;
151 #define BUFSIZE 100
152 unsigned char buf[BUFSIZE];
153 /* Parse the URI */
155 res = coap_split_uri((const uint8_t*)do_uri, strlen(do_uri), &uri);
156 if (res != 0)
157 return 0;
158 /* Check the scheme matches the session type */
160 switch (uri.scheme) {
161 case COAP_URI_SCHEME_COAP:
162 if (proto != COAP_PROTO_UDP)
163 return 0;
164 break;
165 case COAP_URI_SCHEME_COAPS:
166 if (proto != COAP_PROTO_DTLS)
167 return 0;
168 break;
169 case COAP_URI_SCHEME_COAP_TCP:
170 if (proto != COAP_PROTO_TCP)
171 return 0;
172 break;
173 case COAP_URI_SCHEME_COAPS_TCP:
174 if (proto != COAP_PROTO_TLS)
175 return 0;
176 break;
177 case COAP_URI_SCHEME_COAP_WS:
178 if (proto != COAP_PROTO_WS)
179 return 0;
180 break;
181 case COAP_URI_SCHEME_COAPS_WS:
182 if (proto != COAP_PROTO_WSS)
183 return 0;
184 break;
185 /* Proxy support only */
186 case COAP_URI_SCHEME_HTTP:
187 case COAP_URI_SCHEME_HTTPS:
188 case COAP_URI_SCHEME_LAST:
189 default:
190 return 0;
191 }
192 /* construct CoAP message */
194 pdu = coap_pdu_init(COAP_MESSAGE_CON,
195 COAP_REQUEST_CODE_GET,
196 coap_new_message_id(session),
197 coap_session_max_pdu_size(session));
198 if (pdu == NULL)
199 return 0;
200 /* Create all the necessary options from the URI */
202 res = coap_uri_into_options(&uri, dst, &optlist, 1, buf, sizeof(buf));
203 if (res != 0)
204 return 0;
205 /* Add option list (which will get sorted) to the PDU */
207 if (optlist) {
208 res = coap_add_optlist_pdu(pdu, &optlist);
209 coap_delete_optlist(optlist);
210 if (res != 1)
211 return 0;
212 }
213 /* and send the PDU */
215 mid = coap_send(session, pdu);
216 if (mid == COAP_INVALID_MID)
217 return 0;
218 return 1;
219 }
220
222 coap_endpoint_client(3) and coap_pdu_setup(3).
223
225 See
226 "RFC7252: The Constrained Application Protocol (CoAP)"
228 for further information.
230
232 Please report bugs on the mailing list for libcoap:
233 libcoap-developers@lists.sourceforge.net or raise an issue on GitHub at
234 https://github.com/obgm/libcoap/issues
235
237 The libcoap project <libcoap-developers@lists.sourceforge.net>
238coap_uri 4.3.4 10/09/2023 COAP_URI(3)