1/* GLIB - Library of useful routines for C programming
2 * Copyright © 2020 Red Hat, Inc.
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
13 *
14 * You should have received a copy of the GNU Lesser General
15 * Public License along with this library; if not, see
16 * <http://www.gnu.org/licenses/>.
17 */
18
19#pragma once
20
21#if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
22#error "Only <glib.h> can be included directly."
23#endif
24
25#include <glib/gtypes.h>
26
27G_BEGIN_DECLS
28
29G_GNUC_BEGIN_IGNORE_DEPRECATIONS
30
31typedef struct _GUri GUri;
32
33GLIB_AVAILABLE_IN_2_66
34GUri * g_uri_ref (GUri *uri);
35GLIB_AVAILABLE_IN_2_66
36void g_uri_unref (GUri *uri);
37
38/**
39 * GUriFlags:
40 * @G_URI_FLAGS_NONE: No flags set.
41 * @G_URI_FLAGS_PARSE_RELAXED: Parse the URI more relaxedly than the
42 * [RFC 3986](https://tools.ietf.org/html/rfc3986) grammar specifies,
43 * fixing up or ignoring common mistakes in URIs coming from external
44 * sources. This is also needed for some obscure URI schemes where `;`
45 * separates the host from the path. Don’t use this flag unless you need to.
46 * @G_URI_FLAGS_HAS_PASSWORD: The userinfo field may contain a password,
47 * which will be separated from the username by `:`.
48 * @G_URI_FLAGS_HAS_AUTH_PARAMS: The userinfo may contain additional
49 * authentication-related parameters, which will be separated from
50 * the username and/or password by `;`.
51 * @G_URI_FLAGS_NON_DNS: The host component should not be assumed to be a
52 * DNS hostname or IP address (for example, for `smb` URIs with NetBIOS
53 * hostnames).
54 * @G_URI_FLAGS_ENCODED: When parsing a URI, this indicates that `%`-encoded
55 * characters in the userinfo, path, query, and fragment fields
56 * should not be decoded. (And likewise the host field if
57 * %G_URI_FLAGS_NON_DNS is also set.) When building a URI, it indicates
58 * that you have already `%`-encoded the components, and so #GUri
59 * should not do any encoding itself.
60 * @G_URI_FLAGS_ENCODED_QUERY: Same as %G_URI_FLAGS_ENCODED, for the query
61 * field only.
62 * @G_URI_FLAGS_ENCODED_PATH: Same as %G_URI_FLAGS_ENCODED, for the path only.
63 * @G_URI_FLAGS_ENCODED_FRAGMENT: Same as %G_URI_FLAGS_ENCODED, for the
64 * fragment only.
65 * @G_URI_FLAGS_SCHEME_NORMALIZE: A scheme-based normalization will be applied.
66 * For example, when parsing an HTTP URI changing omitted path to `/` and
67 * omitted port to `80`; and when building a URI, changing empty path to `/`
68 * and default port `80`). This only supports a subset of known schemes. (Since: 2.68)
69 *
70 * Flags that describe a URI.
71 *
72 * When parsing a URI, if you need to choose different flags based on
73 * the type of URI, you can use g_uri_peek_scheme() on the URI string
74 * to check the scheme first, and use that to decide what flags to
75 * parse it with.
76 *
77 * Since: 2.66
78 */
79GLIB_AVAILABLE_TYPE_IN_2_66
80typedef enum {
81 G_URI_FLAGS_NONE = 0,
82 G_URI_FLAGS_PARSE_RELAXED = 1 << 0,
83 G_URI_FLAGS_HAS_PASSWORD = 1 << 1,
84 G_URI_FLAGS_HAS_AUTH_PARAMS = 1 << 2,
85 G_URI_FLAGS_ENCODED = 1 << 3,
86 G_URI_FLAGS_NON_DNS = 1 << 4,
87 G_URI_FLAGS_ENCODED_QUERY = 1 << 5,
88 G_URI_FLAGS_ENCODED_PATH = 1 << 6,
89 G_URI_FLAGS_ENCODED_FRAGMENT = 1 << 7,
90 G_URI_FLAGS_SCHEME_NORMALIZE GLIB_AVAILABLE_ENUMERATOR_IN_2_68 = 1 << 8,
91} GUriFlags;
92
93GLIB_AVAILABLE_IN_2_66
94gboolean g_uri_split (const gchar *uri_ref,
95 GUriFlags flags,
96 gchar **scheme,
97 gchar **userinfo,
98 gchar **host,
99 gint *port,
100 gchar **path,
101 gchar **query,
102 gchar **fragment,
103 GError **error);
104GLIB_AVAILABLE_IN_2_66
105gboolean g_uri_split_with_user (const gchar *uri_ref,
106 GUriFlags flags,
107 gchar **scheme,
108 gchar **user,
109 gchar **password,
110 gchar **auth_params,
111 gchar **host,
112 gint *port,
113 gchar **path,
114 gchar **query,
115 gchar **fragment,
116 GError **error);
117GLIB_AVAILABLE_IN_2_66
118gboolean g_uri_split_network (const gchar *uri_string,
119 GUriFlags flags,
120 gchar **scheme,
121 gchar **host,
122 gint *port,
123 GError **error);
124
125GLIB_AVAILABLE_IN_2_66
126gboolean g_uri_is_valid (const gchar *uri_string,
127 GUriFlags flags,
128 GError **error);
129
130GLIB_AVAILABLE_IN_2_66
131gchar * g_uri_join (GUriFlags flags,
132 const gchar *scheme,
133 const gchar *userinfo,
134 const gchar *host,
135 gint port,
136 const gchar *path,
137 const gchar *query,
138 const gchar *fragment);
139GLIB_AVAILABLE_IN_2_66
140gchar * g_uri_join_with_user (GUriFlags flags,
141 const gchar *scheme,
142 const gchar *user,
143 const gchar *password,
144 const gchar *auth_params,
145 const gchar *host,
146 gint port,
147 const gchar *path,
148 const gchar *query,
149 const gchar *fragment);
150
151GLIB_AVAILABLE_IN_2_66
152GUri * g_uri_parse (const gchar *uri_string,
153 GUriFlags flags,
154 GError **error);
155GLIB_AVAILABLE_IN_2_66
156GUri * g_uri_parse_relative (GUri *base_uri,
157 const gchar *uri_ref,
158 GUriFlags flags,
159 GError **error);
160
161GLIB_AVAILABLE_IN_2_66
162gchar * g_uri_resolve_relative (const gchar *base_uri_string,
163 const gchar *uri_ref,
164 GUriFlags flags,
165 GError **error);
166
167GLIB_AVAILABLE_IN_2_66
168GUri * g_uri_build (GUriFlags flags,
169 const gchar *scheme,
170 const gchar *userinfo,
171 const gchar *host,
172 gint port,
173 const gchar *path,
174 const gchar *query,
175 const gchar *fragment);
176GLIB_AVAILABLE_IN_2_66
177GUri * g_uri_build_with_user (GUriFlags flags,
178 const gchar *scheme,
179 const gchar *user,
180 const gchar *password,
181 const gchar *auth_params,
182 const gchar *host,
183 gint port,
184 const gchar *path,
185 const gchar *query,
186 const gchar *fragment);
187
188/**
189 * GUriHideFlags:
190 * @G_URI_HIDE_NONE: No flags set.
191 * @G_URI_HIDE_USERINFO: Hide the userinfo.
192 * @G_URI_HIDE_PASSWORD: Hide the password.
193 * @G_URI_HIDE_AUTH_PARAMS: Hide the auth_params.
194 * @G_URI_HIDE_QUERY: Hide the query.
195 * @G_URI_HIDE_FRAGMENT: Hide the fragment.
196 *
197 * Flags describing what parts of the URI to hide in
198 * g_uri_to_string_partial(). Note that %G_URI_HIDE_PASSWORD and
199 * %G_URI_HIDE_AUTH_PARAMS will only work if the #GUri was parsed with
200 * the corresponding flags.
201 *
202 * Since: 2.66
203 */
204GLIB_AVAILABLE_TYPE_IN_2_66
205typedef enum {
206 G_URI_HIDE_NONE = 0,
207 G_URI_HIDE_USERINFO = 1 << 0,
208 G_URI_HIDE_PASSWORD = 1 << 1,
209 G_URI_HIDE_AUTH_PARAMS = 1 << 2,
210 G_URI_HIDE_QUERY = 1 << 3,
211 G_URI_HIDE_FRAGMENT = 1 << 4,
212} GUriHideFlags;
213
214GLIB_AVAILABLE_IN_2_66
215char * g_uri_to_string (GUri *uri);
216GLIB_AVAILABLE_IN_2_66
217char * g_uri_to_string_partial (GUri *uri,
218 GUriHideFlags flags);
219
220GLIB_AVAILABLE_IN_2_66
221const gchar *g_uri_get_scheme (GUri *uri);
222GLIB_AVAILABLE_IN_2_66
223const gchar *g_uri_get_userinfo (GUri *uri);
224GLIB_AVAILABLE_IN_2_66
225const gchar *g_uri_get_user (GUri *uri);
226GLIB_AVAILABLE_IN_2_66
227const gchar *g_uri_get_password (GUri *uri);
228GLIB_AVAILABLE_IN_2_66
229const gchar *g_uri_get_auth_params (GUri *uri);
230GLIB_AVAILABLE_IN_2_66
231const gchar *g_uri_get_host (GUri *uri);
232GLIB_AVAILABLE_IN_2_66
233gint g_uri_get_port (GUri *uri);
234GLIB_AVAILABLE_IN_2_66
235const gchar *g_uri_get_path (GUri *uri);
236GLIB_AVAILABLE_IN_2_66
237const gchar *g_uri_get_query (GUri *uri);
238GLIB_AVAILABLE_IN_2_66
239const gchar *g_uri_get_fragment (GUri *uri);
240GLIB_AVAILABLE_IN_2_66
241GUriFlags g_uri_get_flags (GUri *uri);
242
243/**
244 * GUriParamsFlags:
245 * @G_URI_PARAMS_NONE: No flags set.
246 * @G_URI_PARAMS_CASE_INSENSITIVE: Parameter names are case insensitive.
247 * @G_URI_PARAMS_WWW_FORM: Replace `+` with space character. Only useful for
248 * URLs on the web, using the `https` or `http` schemas.
249 * @G_URI_PARAMS_PARSE_RELAXED: See %G_URI_FLAGS_PARSE_RELAXED.
250 *
251 * Flags modifying the way parameters are handled by g_uri_parse_params() and
252 * #GUriParamsIter.
253 *
254 * Since: 2.66
255 */
256GLIB_AVAILABLE_TYPE_IN_2_66
257typedef enum {
258 G_URI_PARAMS_NONE = 0,
259 G_URI_PARAMS_CASE_INSENSITIVE = 1 << 0,
260 G_URI_PARAMS_WWW_FORM = 1 << 1,
261 G_URI_PARAMS_PARSE_RELAXED = 1 << 2,
262} GUriParamsFlags;
263
264GLIB_AVAILABLE_IN_2_66
265GHashTable *g_uri_parse_params (const gchar *params,
266 gssize length,
267 const gchar *separators,
268 GUriParamsFlags flags,
269 GError **error);
270
271typedef struct _GUriParamsIter GUriParamsIter;
272
273struct _GUriParamsIter
274{
275 /*< private >*/
276 gint dummy0;
277 gpointer dummy1;
278 gpointer dummy2;
279 guint8 dummy3[256];
280};
281
282GLIB_AVAILABLE_IN_2_66
283void g_uri_params_iter_init (GUriParamsIter *iter,
284 const gchar *params,
285 gssize length,
286 const gchar *separators,
287 GUriParamsFlags flags);
288
289GLIB_AVAILABLE_IN_2_66
290gboolean g_uri_params_iter_next (GUriParamsIter *iter,
291 gchar **attribute,
292 gchar **value,
293 GError **error);
294
295/**
296 * G_URI_ERROR:
297 *
298 * Error domain for URI methods. Errors in this domain will be from
299 * the #GUriError enumeration. See #GError for information on error
300 * domains.
301 *
302 * Since: 2.66
303 */
304#define G_URI_ERROR (g_uri_error_quark ()) GLIB_AVAILABLE_MACRO_IN_2_66
305GLIB_AVAILABLE_IN_2_66
306GQuark g_uri_error_quark (void);
307
308/**
309 * GUriError:
310 * @G_URI_ERROR_FAILED: Generic error if no more specific error is available.
311 * See the error message for details.
312 * @G_URI_ERROR_BAD_SCHEME: The scheme of a URI could not be parsed.
313 * @G_URI_ERROR_BAD_USER: The user/userinfo of a URI could not be parsed.
314 * @G_URI_ERROR_BAD_PASSWORD: The password of a URI could not be parsed.
315 * @G_URI_ERROR_BAD_AUTH_PARAMS: The authentication parameters of a URI could not be parsed.
316 * @G_URI_ERROR_BAD_HOST: The host of a URI could not be parsed.
317 * @G_URI_ERROR_BAD_PORT: The port of a URI could not be parsed.
318 * @G_URI_ERROR_BAD_PATH: The path of a URI could not be parsed.
319 * @G_URI_ERROR_BAD_QUERY: The query of a URI could not be parsed.
320 * @G_URI_ERROR_BAD_FRAGMENT: The fragment of a URI could not be parsed.
321 *
322 * Error codes returned by #GUri methods.
323 *
324 * Since: 2.66
325 */
326typedef enum {
327 G_URI_ERROR_FAILED,
328 G_URI_ERROR_BAD_SCHEME,
329 G_URI_ERROR_BAD_USER,
330 G_URI_ERROR_BAD_PASSWORD,
331 G_URI_ERROR_BAD_AUTH_PARAMS,
332 G_URI_ERROR_BAD_HOST,
333 G_URI_ERROR_BAD_PORT,
334 G_URI_ERROR_BAD_PATH,
335 G_URI_ERROR_BAD_QUERY,
336 G_URI_ERROR_BAD_FRAGMENT,
337} GUriError;
338
339/**
340 * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS:
341 *
342 * Generic delimiters characters as defined in
343 * [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `:/?#[]@`.
344 *
345 * Since: 2.16
346 **/
347#define G_URI_RESERVED_CHARS_GENERIC_DELIMITERS ":/?#[]@"
348
349/**
350 * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS:
351 *
352 * Subcomponent delimiter characters as defined in
353 * [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=`.
354 *
355 * Since: 2.16
356 **/
357#define G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS "!$&'()*+,;="
358
359/**
360 * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT:
361 *
362 * Allowed characters in path elements. Includes `!$&'()*+,;=:@`.
363 *
364 * Since: 2.16
365 **/
366#define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":@"
367
368/**
369 * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH:
370 *
371 * Allowed characters in a path. Includes `!$&'()*+,;=:@/`.
372 *
373 * Since: 2.16
374 **/
375#define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT "/"
376
377/**
378 * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO:
379 *
380 * Allowed characters in userinfo as defined in
381 * [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=:`.
382 *
383 * Since: 2.16
384 **/
385#define G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":"
386
387GLIB_AVAILABLE_IN_ALL
388char * g_uri_unescape_string (const char *escaped_string,
389 const char *illegal_characters);
390GLIB_AVAILABLE_IN_ALL
391char * g_uri_unescape_segment (const char *escaped_string,
392 const char *escaped_string_end,
393 const char *illegal_characters);
394
395GLIB_AVAILABLE_IN_ALL
396char * g_uri_parse_scheme (const char *uri);
397GLIB_AVAILABLE_IN_2_66
398const char *g_uri_peek_scheme (const char *uri);
399
400GLIB_AVAILABLE_IN_ALL
401char * g_uri_escape_string (const char *unescaped,
402 const char *reserved_chars_allowed,
403 gboolean allow_utf8);
404
405GLIB_AVAILABLE_IN_2_66
406GBytes * g_uri_unescape_bytes (const char *escaped_string,
407 gssize length,
408 const char *illegal_characters,
409 GError **error);
410
411GLIB_AVAILABLE_IN_2_66
412char * g_uri_escape_bytes (const guint8 *unescaped,
413 gsize length,
414 const char *reserved_chars_allowed);
415
416G_GNUC_END_IGNORE_DEPRECATIONS
417
418G_END_DECLS
419

source code of include/glib-2.0/glib/guri.h