1 /*
2 * uri.h -- helper functions for URI treatment
3 *
4 * Copyright (C) 2010-2020 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 #ifndef COAP_URI_H_
13 #define COAP_URI_H_
14
15 #include <stdint.h>
16
17 #include "str.h"
18
19 /**
20 * The scheme specifiers. Secure schemes have an odd numeric value,
21 * others are even.
22 */
23 typedef enum coap_uri_scheme_t {
24 COAP_URI_SCHEME_COAP = 0,
25 COAP_URI_SCHEME_COAPS, /* 1 */
26 COAP_URI_SCHEME_COAP_TCP, /* 2 */
27 COAP_URI_SCHEME_COAPS_TCP, /* 3 */
28 COAP_URI_SCHEME_HTTP, /* 4 Proxy-Uri only */
29 COAP_URI_SCHEME_HTTPS /* 5 Proxy-Uri only */
30 } coap_uri_scheme_t;
31
32 /** This mask can be used to check if a parsed URI scheme is secure. */
33 #define COAP_URI_SCHEME_SECURE_MASK 0x01
34
35 /**
36 * Representation of parsed URI. Components may be filled from a string with
37 * coap_split_uri() or coap_split_proxy_uri() and can be used as input for
38 * option-creation functions.
39 */
40 typedef struct {
41 coap_str_const_t host; /**< host part of the URI */
42 uint16_t port; /**< The port in host byte order */
43 coap_str_const_t path; /**< Beginning of the first path segment.
44 Use coap_split_path() to create Uri-Path options */
45 coap_str_const_t query; /**< The query part if present */
46
47 /** The parsed scheme specifier. */
48 enum coap_uri_scheme_t scheme;
49 } coap_uri_t;
50
51 static inline int
coap_uri_scheme_is_secure(const coap_uri_t * uri)52 coap_uri_scheme_is_secure(const coap_uri_t *uri) {
53 return uri && ((uri->scheme & COAP_URI_SCHEME_SECURE_MASK) != 0);
54 }
55
56 /**
57 * Creates a new coap_uri_t object from the specified URI. Returns the new
58 * object or NULL on error. The memory allocated by the new coap_uri_t
59 * must be released using coap_free().
60 *
61 * @param uri The URI path to copy.
62 * @param length The length of uri.
63 *
64 * @return New URI object or NULL on error.
65 */
66 coap_uri_t *coap_new_uri(const uint8_t *uri, unsigned int length);
67
68 /**
69 * Clones the specified coap_uri_t object. Thie function allocates sufficient
70 * memory to hold the coap_uri_t structure and its contents. The object must
71 * be released with coap_free(). */
72 coap_uri_t *coap_clone_uri(const coap_uri_t *uri);
73
74 /**
75 * @defgroup uri_parse URI Parsing Functions
76 *
77 * CoAP PDUs contain normalized URIs with their path and query split into
78 * multiple segments. The functions in this module help splitting strings.
79 * @{
80 */
81
82 /**
83 * Parses a given string into URI components. The identified syntactic
84 * components are stored in the result parameter @p uri. Optional URI
85 * components that are not specified will be set to { 0, 0 }, except for the
86 * port which is set to the default port for the protocol. This function
87 * returns @p 0 if parsing succeeded, a value less than zero otherwise.
88 *
89 * @param str_var The string to split up.
90 * @param len The actual length of @p str_var
91 * @param uri The coap_uri_t object to store the result.
92 *
93 * @return @c 0 on success, or < 0 on error.
94 *
95 */
96 int coap_split_uri(const uint8_t *str_var, size_t len, coap_uri_t *uri);
97
98 /**
99 * Parses a given string into URI components. The identified syntactic
100 * components are stored in the result parameter @p uri. Optional URI
101 * components that are not specified will be set to { 0, 0 }, except for the
102 * port which is set to default port for the protocol. This function returns
103 * @p 0 if parsing succeeded, a value less than zero otherwise.
104 * Note: This function enforces that the given string is in Proxy-Uri format
105 * as well as supports different schema such as http.
106 *
107 * @param str_var The string to split up.
108 * @param len The actual length of @p str_var
109 * @param uri The coap_uri_t object to store the result.
110 *
111 * @return @c 0 on success, or < 0 on error.
112 *
113 */
114 int coap_split_proxy_uri(const uint8_t *str_var, size_t len, coap_uri_t *uri);
115
116 /**
117 * Splits the given URI path into segments. Each segment is preceded
118 * by an option pseudo-header with delta-value 0 and the actual length
119 * of the respective segment after percent-decoding.
120 *
121 * @param s The path string to split.
122 * @param length The actual length of @p s.
123 * @param buf Result buffer for parsed segments.
124 * @param buflen Maximum length of @p buf. Will be set to the actual number
125 * of bytes written into buf on success.
126 *
127 * @return The number of segments created or @c -1 on error.
128 */
129 int coap_split_path(const uint8_t *s,
130 size_t length,
131 unsigned char *buf,
132 size_t *buflen);
133
134 /**
135 * Splits the given URI query into segments. Each segment is preceded
136 * by an option pseudo-header with delta-value 0 and the actual length
137 * of the respective query term.
138 *
139 * @param s The query string to split.
140 * @param length The actual length of @p s.
141 * @param buf Result buffer for parsed segments.
142 * @param buflen Maximum length of @p buf. Will be set to the actual number
143 * of bytes written into buf on success.
144 *
145 * @return The number of segments created or @c -1 on error.
146 *
147 * @bug This function does not reserve additional space for delta > 12.
148 */
149 int coap_split_query(const uint8_t *s,
150 size_t length,
151 unsigned char *buf,
152 size_t *buflen);
153
154 /**
155 * Extract query string from request PDU according to escape rules in 6.5.8.
156 * @param request Request PDU.
157 * @return Reconstructed and escaped query string part or @c NULL if
158 * no query was contained in @p request. The coap_string_t
159 * object returned by this function must be released with
160 * coap_delete_string.
161 */
162 coap_string_t *coap_get_query(const coap_pdu_t *request);
163
164 /**
165 * Extract uri_path string from request PDU
166 * @param request Request PDU.
167 * @return Reconstructed and escaped uri path string part or @c NULL
168 * if no URI-Path was contained in @p request. The
169 * coap_string_t object returned by this function must be
170 * released with coap_delete_string.
171 */
172 coap_string_t *coap_get_uri_path(const coap_pdu_t *request);
173
174 /** @} */
175
176 #endif /* COAP_URI_H_ */
177