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