1 /*
2 * coap_uri.h -- helper functions for URI treatment
3 *
4 * Copyright (C) 2010-2023 Olaf Bergmann <bergmann@tzi.org>
5 *
6 * SPDX-License-Identifier: BSD-2-Clause
7 *
8 * This file is part of the CoAP library libcoap. Please see README for terms
9 * of use.
10 */
11
12 /**
13 * @file coap_uri.h
14 * @brief Helper functions for URI treatment
15 */
16
17 #ifndef COAP_URI_H_
18 #define COAP_URI_H_
19
20 #include <stdint.h>
21
22 #include "coap_str.h"
23
24 /**
25 * The scheme specifiers. Secure schemes have an odd numeric value,
26 * others are even.
27 */
28 typedef enum coap_uri_scheme_t {
29 COAP_URI_SCHEME_COAP = 0,
30 COAP_URI_SCHEME_COAPS, /* 1 */
31 COAP_URI_SCHEME_COAP_TCP, /* 2 */
32 COAP_URI_SCHEME_COAPS_TCP, /* 3 */
33 COAP_URI_SCHEME_HTTP, /* 4 Proxy-Uri only */
34 COAP_URI_SCHEME_HTTPS, /* 5 Proxy-Uri only */
35 COAP_URI_SCHEME_COAP_WS, /* 6 */
36 COAP_URI_SCHEME_COAPS_WS, /* 7 */
37 COAP_URI_SCHEME_LAST /* 8 Size of scheme */
38 } coap_uri_scheme_t;
39
40 /** This mask can be used to check if a parsed URI scheme is secure. */
41 #define COAP_URI_SCHEME_SECURE_MASK 0x01
42
43 #define COAP_URI_SCHEME_COAP_BIT (1 << COAP_URI_SCHEME_COAP)
44 #define COAP_URI_SCHEME_COAPS_BIT (1 << COAP_URI_SCHEME_COAPS)
45 #define COAP_URI_SCHEME_COAP_TCP_BIT (1 << COAP_URI_SCHEME_COAP_TCP)
46 #define COAP_URI_SCHEME_COAPS_TCP_BIT (1 << COAP_URI_SCHEME_COAPS_TCP)
47 #define COAP_URI_SCHEME_HTTP_BIT (1 << COAP_URI_SCHEME_HTTP)
48 #define COAP_URI_SCHEME_HTTPS_BIT (1 << COAP_URI_SCHEME_HTTPS)
49 #define COAP_URI_SCHEME_COAP_WS_BIT (1 << COAP_URI_SCHEME_COAP_WS)
50 #define COAP_URI_SCHEME_COAPS_WS_BIT (1 << COAP_URI_SCHEME_COAPS_WS)
51
52 #define COAP_URI_SCHEME_ALL_COAP_BITS (COAP_URI_SCHEME_COAP_BIT | \
53 COAP_URI_SCHEME_COAPS_BIT | \
54 COAP_URI_SCHEME_COAP_TCP_BIT | \
55 COAP_URI_SCHEME_COAPS_TCP_BIT | \
56 COAP_URI_SCHEME_COAP_WS_BIT | \
57 COAP_URI_SCHEME_COAPS_WS_BIT)
58
59 /**
60 * Representation of parsed URI. Components may be filled from a string with
61 * coap_split_uri() or coap_split_proxy_uri() and can be used as input for
62 * option-creation functions. Alternatively, coap_uri_into_options() can
63 * be used to convert coap_uri_t into CoAP options.
64 */
65 typedef struct {
66 coap_str_const_t host; /**< The host part of the URI */
67 uint16_t port; /**< The port in host byte order */
68 coap_str_const_t path; /**< The complete path if present or {0, NULL}.
69 Needs to be split using coap_split_path()
70 or coap_uri_into_options(). */
71 coap_str_const_t query; /**< The complete query if present or {0, NULL}.
72 Needs to be split using coap_split_query()
73 or coap_uri_into_options(). */
74 /** The parsed scheme specifier. */
75 enum coap_uri_scheme_t scheme;
76 } coap_uri_t;
77
78 static inline int
coap_uri_scheme_is_secure(const coap_uri_t * uri)79 coap_uri_scheme_is_secure(const coap_uri_t *uri) {
80 return uri && ((uri->scheme & COAP_URI_SCHEME_SECURE_MASK) != 0);
81 }
82
83 /**
84 * Determines from the @p host whether this is a Unix Domain socket
85 * request.
86 *
87 * @param host The host object.
88 *
89 * @return @c 0 on failure, or @c 1 on success.
90 *
91 */
92 int coap_host_is_unix_domain(const coap_str_const_t *host);
93
94 /**
95 * Creates a new coap_uri_t object from the specified URI. Returns the new
96 * object or NULL on error. The memory allocated by the new coap_uri_t
97 * should be released using coap_delete_uri().
98 *
99 * @param uri The URI path to copy.
100 * @param length The length of uri.
101 *
102 * @return New URI object or NULL on error.
103 */
104 coap_uri_t *coap_new_uri(const uint8_t *uri, unsigned int length);
105
106 /**
107 * Clones the specified coap_uri_t object. This function allocates sufficient
108 * memory to hold the coap_uri_t structure and its contents. The object should
109 * be released with delete_uri().
110 *
111 * @param uri The coap_uri_t structure to copy.
112 *
113 * @return New URI object or NULL on error.
114 */
115 coap_uri_t *coap_clone_uri(const coap_uri_t *uri);
116
117 /**
118 * Removes the specified coap_uri_t object.
119 *
120 * @param uri The coap_uri_t structure to remove.
121 */
122 void coap_delete_uri(coap_uri_t *uri);
123
124 /**
125 * @ingroup application_api
126 * @defgroup uri_parse URI Parsing Functions
127 * API for parsing URIs.
128 * CoAP PDUs contain normalized URIs with their path and query split into
129 * multiple segments. The functions in this module help splitting strings.
130 * @{
131 */
132
133 /**
134 * Parses a given string into URI components. The identified syntactic
135 * components are stored in the result parameter @p uri. Optional URI
136 * components that are not specified will be set to { 0, 0 }, except for the
137 * port which is set to the default port for the protocol. This function
138 * returns @p 0 if parsing succeeded, a value less than zero otherwise.
139 *
140 * @param str_var The string to split up.
141 * @param len The actual length of @p str_var
142 * @param uri The coap_uri_t object to store the result.
143 *
144 * @return @c 0 on success, or < 0 on error.
145 *
146 */
147 int coap_split_uri(const uint8_t *str_var, size_t len, coap_uri_t *uri);
148
149 /**
150 * Parses a given string into URI components. The identified syntactic
151 * components are stored in the result parameter @p uri. Optional URI
152 * components that are not specified will be set to { 0, 0 }, except for the
153 * port which is set to default port for the protocol. This function returns
154 * @p 0 if parsing succeeded, a value less than zero otherwise.
155 * Note: This function enforces that the given string is in Proxy-Uri format
156 * as well as supports different schema such as http and https.
157 *
158 * @param str_var The string to split up.
159 * @param len The actual length of @p str_var
160 * @param uri The coap_uri_t object to store the result.
161 *
162 * @return @c 0 on success, or < 0 on error.
163 *
164 */
165 int coap_split_proxy_uri(const uint8_t *str_var, size_t len, coap_uri_t *uri);
166
167 /**
168 * Takes a coap_uri_t and then adds CoAP options into the @p optlist_chain.
169 * If the port is not the default port and create_port_host_opt is not 0, then
170 * the Port option is added to the @p optlist_chain.
171 * If the dst defines an address that does not match the host in uri->host and
172 * is not 0, then the Host option is added to the @p optlist_chain.
173 * Any path or query are broken down into the individual segment Path or Query
174 * options and added to the @p optlist_chain.
175 *
176 * @param uri The coap_uri_t object.
177 * @param dst The destination, or NULL if URI_HOST not to be added.
178 * @param optlist_chain Where to store the chain of options.
179 * @param buf Scratch buffer area (needs to be bigger than
180 * uri->path.length and uri->query.length)
181 * @param buflen Size of scratch buffer.
182 * @param create_port_host_opt @c 1 if port/host option to be added
183 * (if non-default) else @c 0
184 *
185 * @return @c 0 on success, or < 0 on error.
186 *
187 */
188 int coap_uri_into_options(const coap_uri_t *uri, const coap_address_t *dst,
189 coap_optlist_t **optlist_chain,
190 int create_port_host_opt,
191 uint8_t *buf, size_t buflen);
192
193 /**
194 * Splits the given URI path into segments. Each segment is preceded
195 * by an option pseudo-header with delta-value 0 and the actual length
196 * of the respective segment after percent-decoding.
197 *
198 * @param s The path string to split.
199 * @param length The actual length of @p s.
200 * @param buf Result buffer for parsed segments.
201 * @param buflen Maximum length of @p buf. Will be set to the actual number
202 * of bytes written into buf on success.
203 *
204 * @return The number of segments created or @c -1 on error.
205 */
206 int coap_split_path(const uint8_t *s,
207 size_t length,
208 unsigned char *buf,
209 size_t *buflen);
210
211 /**
212 * Splits the given URI query into segments. Each segment is preceded
213 * by an option pseudo-header with delta-value 0 and the actual length
214 * of the respective query term.
215 *
216 * @param s The query string to split.
217 * @param length The actual length of @p s.
218 * @param buf Result buffer for parsed segments.
219 * @param buflen Maximum length of @p buf. Will be set to the actual number
220 * of bytes written into buf on success.
221 *
222 * @return The number of segments created or @c -1 on error.
223 *
224 * @bug This function does not reserve additional space for delta > 12.
225 */
226 int coap_split_query(const uint8_t *s,
227 size_t length,
228 unsigned char *buf,
229 size_t *buflen);
230
231 /**
232 * Extract query string from request PDU according to escape rules in 6.5.8.
233 * @param request Request PDU.
234 * @return Reconstructed and escaped query string part or @c NULL if
235 * no query was contained in @p request. The coap_string_t
236 * object returned by this function must be released with
237 * coap_delete_string.
238 */
239 coap_string_t *coap_get_query(const coap_pdu_t *request);
240
241 /**
242 * Extract uri_path string from request PDU
243 * @param request Request PDU.
244 * @return Reconstructed and escaped uri path string part or @c NULL
245 * if no URI-Path was contained in @p request. The
246 * coap_string_t object returned by this function must be
247 * released with coap_delete_string.
248 */
249 coap_string_t *coap_get_uri_path(const coap_pdu_t *request);
250
251 /** @} */
252
253 #endif /* COAP_URI_H_ */
254