1/*
2Copyright (c) 2012, Broadcom Europe Ltd
3All rights reserved.
4
5Redistribution and use in source and binary forms, with or without
6modification, are permitted provided that the following conditions are met:
7 * Redistributions of source code must retain the above copyright
8 notice, this list of conditions and the following disclaimer.
9 * Redistributions in binary form must reproduce the above copyright
10 notice, this list of conditions and the following disclaimer in the
11 documentation and/or other materials provided with the distribution.
12 * Neither the name of the copyright holder nor the
13 names of its contributors may be used to endorse or promote products
14 derived from this software without specific prior written permission.
15
16THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
17ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
18WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
19DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY
20DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
21(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
22LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
23ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
24(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
25SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26*/
27
28#ifndef VC_CONTAINERS_URI_H
29#define VC_CONTAINERS_URI_H
30
31/** \file containers_uri.h
32 * API for parsing and building URI strings as described in RFC3986.
33 */
34
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39#include "containers/containers.h"
40
41typedef struct VC_URI_PARTS_T VC_URI_PARTS_T;
42
43/** Create an empty URI structure.
44 *
45 * \return The new URI structure. */
46VC_URI_PARTS_T *vc_uri_create( void );
47
48/** Destroy a URI structure.
49 *
50 * \param p_uri Pointer to a URI parts structure. */
51void vc_uri_release( VC_URI_PARTS_T *p_uri );
52
53/** Clear a URI structure.
54 * Any URI component strings held are released, but the structure itself is not.
55 *
56 * \param p_uri Pointer to a URI parts structure. */
57void vc_uri_clear( VC_URI_PARTS_T *p_uri );
58
59/** Parses and unescapes a URI into the component parts.
60 *
61 * \param p_uri Pointer to a URI parts structure.
62 * \param uri Pointer to a URI string to be parsed.
63 * \return True if successful, false if not. */
64bool vc_uri_parse( VC_URI_PARTS_T *p_uri, const char *uri );
65
66/** Builds the URI component parts into a URI string.
67 * If buffer is NULL, or buffer_size is too small, nothing is written to the
68 * buffer but the required string length is still returned. buffer_size must be
69 * at least one more than the value returned.
70 *
71 * \param p_uri Pointer to a URI parts structure.
72 * \param buffer Pointer to where the URI string is to be built, or NULL.
73 * \param buffer_size Number of bytes available in the buffer.
74 * \return The length of the URI string. */
75uint32_t vc_uri_build( const VC_URI_PARTS_T *p_uri, char *buffer, size_t buffer_size );
76
77/** Retrieves the scheme of the URI.
78 * The string is valid until either the scheme is changed or the URI is released.
79 *
80 * \param p_uri The parsed URI.
81 * \return Pointer to the scheme string. */
82const char *vc_uri_scheme( const VC_URI_PARTS_T *p_uri );
83
84/** Retrieves the userinfo of the URI.
85 * The string is valid until either the userinfo is changed or the URI is released.
86 *
87 * \param p_uri The parsed URI.
88 * \return Pointer to the userinfo string. */
89const char *vc_uri_userinfo( const VC_URI_PARTS_T *p_uri );
90
91/** Retrieves the host of the URI.
92 * The string is valid until either the host is changed or the URI is released.
93 *
94 * \param p_uri The parsed URI.
95 * \return Pointer to the host string. */
96const char *vc_uri_host( const VC_URI_PARTS_T *p_uri );
97
98/** Retrieves the port of the URI.
99 * The string is valid until either the port is changed or the URI is released.
100 *
101 * \param p_uri The parsed URI.
102 * \return Pointer to the port string. */
103const char *vc_uri_port( const VC_URI_PARTS_T *p_uri );
104
105/** Retrieves the path of the URI.
106 * The string is valid until either the path is changed or the URI is released.
107 *
108 * \param p_uri The parsed URI.
109 * \return Pointer to the path string. */
110const char *vc_uri_path( const VC_URI_PARTS_T *p_uri );
111
112/** Retrieves the extension part of the path of the URI.
113 * The string is valid until either the path is changed or the URI is released.
114 *
115 * \param p_uri The parsed URI.
116 * \return Pointer to the extension string. */
117const char *vc_uri_path_extension( const VC_URI_PARTS_T *p_uri );
118
119/** Retrieves the fragment of the URI.
120 * The string is valid until either the fragment is changed or the URI is released.
121 *
122 * \param p_uri The parsed URI.
123 * \return Pointer to the fragment string. */
124const char *vc_uri_fragment( const VC_URI_PARTS_T *p_uri );
125
126/** Returns the number of query name/value pairs stored.
127 *
128 * \param p_uri The parsed URI.
129 * \return Number of queries stored. */
130uint32_t vc_uri_num_queries( const VC_URI_PARTS_T *p_uri );
131
132/** Retrieves a given query's name and value
133 * If either p_name or p_value are NULL, that part of the query is not returned,
134 * otherwise it is set to the address of the string (which may itself be NULL).
135 *
136 * \param p_uri The parsed URI.
137 * \param index Selects the query to get.
138 * \param p_name Address of a string pointer to receive query name, or NULL.
139 * \param p_value Address of a string pointer to receive query value, or NULL. */
140void vc_uri_query( const VC_URI_PARTS_T *p_uri, uint32_t index, const char **p_name, const char **p_value );
141
142/** Finds a specific query in the array.
143 * If p_index is NULL, then it is assumed the search should start at index 0,
144 * otherwise the search will start at the specified index and the index will
145 * be updated on return to point to the query which has been found.
146 * If p_value is NULL, that part of the query is not returned,
147 * otherwise it is set to the address of the value string (which may itself be NULL).
148 *
149 * \param p_uri Pointer to a URI parts structure.
150 * \param p_index Index from which to start the search. May be NULL.
151 * \param name Unescaped query name.
152 * \param value Unescaped query value. May be NULL.
153 * \return True if successful, false if not. */
154bool vc_uri_find_query( VC_URI_PARTS_T *p_uri, uint32_t *p_index, const char *name, const char **p_value );
155
156/** Sets the scheme of the URI.
157 * The string will be copied and stored in the URI, releasing and replacing
158 * any existing string. If NULL is passed, any existing string shall simply be
159 * released.
160 *
161 * \param p_uri The parsed URI.
162 * \param scheme Pointer to the new scheme string, or NULL.
163 * \return True if successful, false on memory allocation failure. */
164bool vc_uri_set_scheme( VC_URI_PARTS_T *p_uri, const char *scheme );
165
166/** Sets the userinfo of the URI.
167 * The string will be copied and stored in the URI, releasing and replacing
168 * any existing string. If NULL is passed, any existing string shall simply be
169 * released.
170 *
171 * \param p_uri The parsed URI.
172 * \param userinfo Pointer to the new userinfo string, or NULL.
173 * \return True if successful, false on memory allocation failure. */
174bool vc_uri_set_userinfo( VC_URI_PARTS_T *p_uri, const char *userinfo );
175
176/** Sets the host of the URI.
177 * The string will be copied and stored in the URI, releasing and replacing
178 * any existing string. If NULL is passed, any existing string shall simply be
179 * released.
180 *
181 * \param p_uri The parsed URI.
182 * \param host Pointer to the new host string, or NULL.
183 * \return True if successful, false on memory allocation failure. */
184bool vc_uri_set_host( VC_URI_PARTS_T *p_uri, const char *host );
185
186/** Sets the port of the URI.
187 * The string will be copied and stored in the URI, releasing and replacing
188 * any existing string. If NULL is passed, any existing string shall simply be
189 * released.
190 *
191 * \param p_uri The parsed URI.
192 * \param port Pointer to the new port string, or NULL.
193 * \return True if successful, false on memory allocation failure. */
194bool vc_uri_set_port( VC_URI_PARTS_T *p_uri, const char *port );
195
196/** Sets the path of the URI.
197 * The string will be copied and stored in the URI, releasing and replacing
198 * any existing string. If NULL is passed, any existing string shall simply be
199 * released.
200 *
201 * \param p_uri The parsed URI.
202 * \param path Pointer to the new path string, or NULL.
203 * \return True if successful, false on memory allocation failure. */
204bool vc_uri_set_path( VC_URI_PARTS_T *p_uri, const char *path );
205
206/** Sets the fragment of the URI.
207 * The string will be copied and stored in the URI, releasing and replacing
208 * any existing string. If NULL is passed, any existing string shall simply be
209 * released.
210 *
211 * \param p_uri The parsed URI.
212 * \param fragment Pointer to the new fragment string, or NULL.
213 * \return True if successful, false on memory allocation failure. */
214bool vc_uri_set_fragment( VC_URI_PARTS_T *p_uri, const char *fragment );
215
216/** Adds an query to the array.
217 * Note that the queries pointer may change after this function is called.
218 * May fail due to memory allocation failure or invalid parameters.
219 *
220 * \param p_uri Pointer to a URI parts structure.
221 * \param name Unescaped query name.
222 * \param value Unescaped query value. May be NULL.
223 * \return True if successful, false if not. */
224bool vc_uri_add_query( VC_URI_PARTS_T *p_uri, const char *name, const char *value );
225
226/** Merge a base URI and a relative URI.
227 * In general, where the relative URI does not have a given element, the
228 * corresponding element from the base URI is used. See RFC1808.
229 * The combined URI is left in relative_uri. If the function is unsuccessful,
230 * the relative_uri may have been partially modified.
231 *
232 * \param base_uri Pointer to the base URI parts structure.
233 * \param relative_uri Pointer to the relative URI parts structure.
234 * \return True if successful, false if not. */
235bool vc_uri_merge( const VC_URI_PARTS_T *base_uri, VC_URI_PARTS_T *relative_uri );
236
237#ifdef __cplusplus
238}
239#endif
240
241#endif /* VC_CONTAINERS_URI_H */
242