1COAP_URI(3)                     libcoap Manual                     COAP_URI(3)
2
3
4

NAME

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

SYNOPSIS

11       #include <coap3/coap.h>
12
13       int coap_split_uri(const uint8_t *uri_def, size_t length, coap_uri_t
14       *uri);
15
16       int coap_split_proxy_uri(const uint8_t *uri_def, size_t length,
17       coap_uri_t *uri);
18
19       coap_uri_t *coap_new_uri(const uint8_t *uri_def, unsigned int length);
20
21       coap_uri_t *coap_clone_uri(const coap_uri_t *uri);
22
23       void coap_delete_uri(coap_uri_t *uri);
24
25       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
29       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

DESCRIPTION

35       This man page describes the functionality available to work with CoAP
36       URIs and break them down into the component parts.
37
38       A CoAP URI is of the form
39
40       <scheme><host><(optional):port><(optional)path><(optional)?query>
41
42       where scheme can be one of coap://, coaps://, coap+tcp:// and
43       coaps+tcp://.
44
45       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
50       (optional):port is ignored for Unix domain socket’s host definitions.
51
52       The parsed uri structure is of the form
53
54           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

FUNCTIONS

67       Function: coap_split_uri()
68
69       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
74       Function: coap_split_proxy_uri()
75
76       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
82       Function: coap_new_uri()
83
84       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
89       Function: coap_clone_uri()
90
91       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
95       Function: coap_delete_uri()
96
97       The coap_delete_uri() function frees off a previously created uri
98       coap_uri_t structure.
99
100       Function: coap_uri_into_options()
101
102       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
108       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
112       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
115       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
118       Likewise, if there is a query, individual Query options for each
119       segment are then added to optlist_chain.
120
121       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
124       NOTE: It is the responsibility of the application to free off the
125       entries added to optlist_chain using coap_delete_optlist(3).
126

RETURN VALUES

128       coap_split_uri(), coap_split_proxy_uri(), and coap_uri_into_options()
129       return 0 on success, else < 0 on failure.
130
131       coap_new_uri() and coap_clone_uri() return a newly allocated coap_uri_t
132       structure or NULL on failure.
133

EXAMPLES

135       Setup PDU and Transmit
136
137           #include <coap3/coap.h>
138
139           /*
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
154             /* 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
159             /* 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
193             /* 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
201             /* 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
206             /* 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
214             /* and send the PDU */
215             mid = coap_send(session, pdu);
216             if (mid == COAP_INVALID_MID)
217               return 0;
218             return 1;
219           }
220

SEE ALSO

222       coap_endpoint_client(3) and coap_pdu_setup(3).
223

FURTHER INFORMATION

225       See
226
227       "RFC7252: The Constrained Application Protocol (CoAP)"
228
229       for further information.
230

BUGS

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

AUTHORS

237       The libcoap project <libcoap-developers@lists.sourceforge.net>
238
239
240
241coap_uri 4.3.4                    10/09/2023                       COAP_URI(3)
Impressum