1 /* GLIB - Library of useful routines for C programming
2 * Copyright © 2020 Red Hat, Inc.
4 * SPDX-License-Identifier: LGPL-2.1-or-later
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
16 * You should have received a copy of the GNU Lesser General
17 * Public License along with this library; if not, see
18 * <http://www.gnu.org/licenses/>.
23 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
24 #error "Only <glib.h> can be included directly."
27 #include <glib/gtypes.h>
31 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
33 typedef struct _GUri GUri;
35 GLIB_AVAILABLE_IN_2_66
36 GUri * g_uri_ref (GUri *uri);
37 GLIB_AVAILABLE_IN_2_66
38 void g_uri_unref (GUri *uri);
42 * @G_URI_FLAGS_NONE: No flags set.
43 * @G_URI_FLAGS_PARSE_RELAXED: Parse the URI more relaxedly than the
44 * [RFC 3986](https://tools.ietf.org/html/rfc3986) grammar specifies,
45 * fixing up or ignoring common mistakes in URIs coming from external
46 * sources. This is also needed for some obscure URI schemes where `;`
47 * separates the host from the path. Don’t use this flag unless you need to.
48 * @G_URI_FLAGS_HAS_PASSWORD: The userinfo field may contain a password,
49 * which will be separated from the username by `:`.
50 * @G_URI_FLAGS_HAS_AUTH_PARAMS: The userinfo may contain additional
51 * authentication-related parameters, which will be separated from
52 * the username and/or password by `;`.
53 * @G_URI_FLAGS_NON_DNS: The host component should not be assumed to be a
54 * DNS hostname or IP address (for example, for `smb` URIs with NetBIOS
56 * @G_URI_FLAGS_ENCODED: When parsing a URI, this indicates that `%`-encoded
57 * characters in the userinfo, path, query, and fragment fields
58 * should not be decoded. (And likewise the host field if
59 * %G_URI_FLAGS_NON_DNS is also set.) When building a URI, it indicates
60 * that you have already `%`-encoded the components, and so #GUri
61 * should not do any encoding itself.
62 * @G_URI_FLAGS_ENCODED_QUERY: Same as %G_URI_FLAGS_ENCODED, for the query
64 * @G_URI_FLAGS_ENCODED_PATH: Same as %G_URI_FLAGS_ENCODED, for the path only.
65 * @G_URI_FLAGS_ENCODED_FRAGMENT: Same as %G_URI_FLAGS_ENCODED, for the
67 * @G_URI_FLAGS_SCHEME_NORMALIZE: A scheme-based normalization will be applied.
68 * For example, when parsing an HTTP URI changing omitted path to `/` and
69 * omitted port to `80`; and when building a URI, changing empty path to `/`
70 * and default port `80`). This only supports a subset of known schemes. (Since: 2.68)
72 * Flags that describe a URI.
74 * When parsing a URI, if you need to choose different flags based on
75 * the type of URI, you can use g_uri_peek_scheme() on the URI string
76 * to check the scheme first, and use that to decide what flags to
81 GLIB_AVAILABLE_TYPE_IN_2_66
84 G_URI_FLAGS_PARSE_RELAXED = 1 << 0,
85 G_URI_FLAGS_HAS_PASSWORD = 1 << 1,
86 G_URI_FLAGS_HAS_AUTH_PARAMS = 1 << 2,
87 G_URI_FLAGS_ENCODED = 1 << 3,
88 G_URI_FLAGS_NON_DNS = 1 << 4,
89 G_URI_FLAGS_ENCODED_QUERY = 1 << 5,
90 G_URI_FLAGS_ENCODED_PATH = 1 << 6,
91 G_URI_FLAGS_ENCODED_FRAGMENT = 1 << 7,
92 G_URI_FLAGS_SCHEME_NORMALIZE GLIB_AVAILABLE_ENUMERATOR_IN_2_68 = 1 << 8,
95 GLIB_AVAILABLE_IN_2_66
96 gboolean g_uri_split (const gchar *uri_ref,
106 GLIB_AVAILABLE_IN_2_66
107 gboolean g_uri_split_with_user (const gchar *uri_ref,
119 GLIB_AVAILABLE_IN_2_66
120 gboolean g_uri_split_network (const gchar *uri_string,
127 GLIB_AVAILABLE_IN_2_66
128 gboolean g_uri_is_valid (const gchar *uri_string,
132 GLIB_AVAILABLE_IN_2_66
133 gchar * g_uri_join (GUriFlags flags,
135 const gchar *userinfo,
140 const gchar *fragment);
141 GLIB_AVAILABLE_IN_2_66
142 gchar * g_uri_join_with_user (GUriFlags flags,
145 const gchar *password,
146 const gchar *auth_params,
151 const gchar *fragment);
153 GLIB_AVAILABLE_IN_2_66
154 GUri * g_uri_parse (const gchar *uri_string,
157 GLIB_AVAILABLE_IN_2_66
158 GUri * g_uri_parse_relative (GUri *base_uri,
159 const gchar *uri_ref,
163 GLIB_AVAILABLE_IN_2_66
164 gchar * g_uri_resolve_relative (const gchar *base_uri_string,
165 const gchar *uri_ref,
169 GLIB_AVAILABLE_IN_2_66
170 GUri * g_uri_build (GUriFlags flags,
172 const gchar *userinfo,
177 const gchar *fragment);
178 GLIB_AVAILABLE_IN_2_66
179 GUri * g_uri_build_with_user (GUriFlags flags,
182 const gchar *password,
183 const gchar *auth_params,
188 const gchar *fragment);
192 * @G_URI_HIDE_NONE: No flags set.
193 * @G_URI_HIDE_USERINFO: Hide the userinfo.
194 * @G_URI_HIDE_PASSWORD: Hide the password.
195 * @G_URI_HIDE_AUTH_PARAMS: Hide the auth_params.
196 * @G_URI_HIDE_QUERY: Hide the query.
197 * @G_URI_HIDE_FRAGMENT: Hide the fragment.
199 * Flags describing what parts of the URI to hide in
200 * g_uri_to_string_partial(). Note that %G_URI_HIDE_PASSWORD and
201 * %G_URI_HIDE_AUTH_PARAMS will only work if the #GUri was parsed with
202 * the corresponding flags.
206 GLIB_AVAILABLE_TYPE_IN_2_66
209 G_URI_HIDE_USERINFO = 1 << 0,
210 G_URI_HIDE_PASSWORD = 1 << 1,
211 G_URI_HIDE_AUTH_PARAMS = 1 << 2,
212 G_URI_HIDE_QUERY = 1 << 3,
213 G_URI_HIDE_FRAGMENT = 1 << 4,
216 GLIB_AVAILABLE_IN_2_66
217 char * g_uri_to_string (GUri *uri);
218 GLIB_AVAILABLE_IN_2_66
219 char * g_uri_to_string_partial (GUri *uri,
220 GUriHideFlags flags);
222 GLIB_AVAILABLE_IN_2_66
223 const gchar *g_uri_get_scheme (GUri *uri);
224 GLIB_AVAILABLE_IN_2_66
225 const gchar *g_uri_get_userinfo (GUri *uri);
226 GLIB_AVAILABLE_IN_2_66
227 const gchar *g_uri_get_user (GUri *uri);
228 GLIB_AVAILABLE_IN_2_66
229 const gchar *g_uri_get_password (GUri *uri);
230 GLIB_AVAILABLE_IN_2_66
231 const gchar *g_uri_get_auth_params (GUri *uri);
232 GLIB_AVAILABLE_IN_2_66
233 const gchar *g_uri_get_host (GUri *uri);
234 GLIB_AVAILABLE_IN_2_66
235 gint g_uri_get_port (GUri *uri);
236 GLIB_AVAILABLE_IN_2_66
237 const gchar *g_uri_get_path (GUri *uri);
238 GLIB_AVAILABLE_IN_2_66
239 const gchar *g_uri_get_query (GUri *uri);
240 GLIB_AVAILABLE_IN_2_66
241 const gchar *g_uri_get_fragment (GUri *uri);
242 GLIB_AVAILABLE_IN_2_66
243 GUriFlags g_uri_get_flags (GUri *uri);
247 * @G_URI_PARAMS_NONE: No flags set.
248 * @G_URI_PARAMS_CASE_INSENSITIVE: Parameter names are case insensitive.
249 * @G_URI_PARAMS_WWW_FORM: Replace `+` with space character. Only useful for
250 * URLs on the web, using the `https` or `http` schemas.
251 * @G_URI_PARAMS_PARSE_RELAXED: See %G_URI_FLAGS_PARSE_RELAXED.
253 * Flags modifying the way parameters are handled by g_uri_parse_params() and
258 GLIB_AVAILABLE_TYPE_IN_2_66
260 G_URI_PARAMS_NONE = 0,
261 G_URI_PARAMS_CASE_INSENSITIVE = 1 << 0,
262 G_URI_PARAMS_WWW_FORM = 1 << 1,
263 G_URI_PARAMS_PARSE_RELAXED = 1 << 2,
266 GLIB_AVAILABLE_IN_2_66
267 GHashTable *g_uri_parse_params (const gchar *params,
269 const gchar *separators,
270 GUriParamsFlags flags,
273 typedef struct _GUriParamsIter GUriParamsIter;
275 struct _GUriParamsIter
284 GLIB_AVAILABLE_IN_2_66
285 void g_uri_params_iter_init (GUriParamsIter *iter,
288 const gchar *separators,
289 GUriParamsFlags flags);
291 GLIB_AVAILABLE_IN_2_66
292 gboolean g_uri_params_iter_next (GUriParamsIter *iter,
300 * Error domain for URI methods. Errors in this domain will be from
301 * the #GUriError enumeration. See #GError for information on error
306 #define G_URI_ERROR (g_uri_error_quark ()) GLIB_AVAILABLE_MACRO_IN_2_66
307 GLIB_AVAILABLE_IN_2_66
308 GQuark g_uri_error_quark (void);
312 * @G_URI_ERROR_FAILED: Generic error if no more specific error is available.
313 * See the error message for details.
314 * @G_URI_ERROR_BAD_SCHEME: The scheme of a URI could not be parsed.
315 * @G_URI_ERROR_BAD_USER: The user/userinfo of a URI could not be parsed.
316 * @G_URI_ERROR_BAD_PASSWORD: The password of a URI could not be parsed.
317 * @G_URI_ERROR_BAD_AUTH_PARAMS: The authentication parameters of a URI could not be parsed.
318 * @G_URI_ERROR_BAD_HOST: The host of a URI could not be parsed.
319 * @G_URI_ERROR_BAD_PORT: The port of a URI could not be parsed.
320 * @G_URI_ERROR_BAD_PATH: The path of a URI could not be parsed.
321 * @G_URI_ERROR_BAD_QUERY: The query of a URI could not be parsed.
322 * @G_URI_ERROR_BAD_FRAGMENT: The fragment of a URI could not be parsed.
324 * Error codes returned by #GUri methods.
330 G_URI_ERROR_BAD_SCHEME,
331 G_URI_ERROR_BAD_USER,
332 G_URI_ERROR_BAD_PASSWORD,
333 G_URI_ERROR_BAD_AUTH_PARAMS,
334 G_URI_ERROR_BAD_HOST,
335 G_URI_ERROR_BAD_PORT,
336 G_URI_ERROR_BAD_PATH,
337 G_URI_ERROR_BAD_QUERY,
338 G_URI_ERROR_BAD_FRAGMENT,
342 * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS:
344 * Generic delimiters characters as defined in
345 * [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `:/?#[]@`.
349 #define G_URI_RESERVED_CHARS_GENERIC_DELIMITERS ":/?#[]@"
352 * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS:
354 * Subcomponent delimiter characters as defined in
355 * [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=`.
359 #define G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS "!$&'()*+,;="
362 * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT:
364 * Allowed characters in path elements. Includes `!$&'()*+,;=:@`.
368 #define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":@"
371 * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH:
373 * Allowed characters in a path. Includes `!$&'()*+,;=:@/`.
377 #define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT "/"
380 * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO:
382 * Allowed characters in userinfo as defined in
383 * [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=:`.
387 #define G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":"
389 GLIB_AVAILABLE_IN_ALL
390 char * g_uri_unescape_string (const char *escaped_string,
391 const char *illegal_characters);
392 GLIB_AVAILABLE_IN_ALL
393 char * g_uri_unescape_segment (const char *escaped_string,
394 const char *escaped_string_end,
395 const char *illegal_characters);
397 GLIB_AVAILABLE_IN_ALL
398 char * g_uri_parse_scheme (const char *uri);
399 GLIB_AVAILABLE_IN_2_66
400 const char *g_uri_peek_scheme (const char *uri);
402 GLIB_AVAILABLE_IN_ALL
403 char * g_uri_escape_string (const char *unescaped,
404 const char *reserved_chars_allowed,
405 gboolean allow_utf8);
407 GLIB_AVAILABLE_IN_2_66
408 GBytes * g_uri_unescape_bytes (const char *escaped_string,
410 const char *illegal_characters,
413 GLIB_AVAILABLE_IN_2_66
414 char * g_uri_escape_bytes (const guint8 *unescaped,
416 const char *reserved_chars_allowed);
418 G_GNUC_END_IGNORE_DEPRECATIONS