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 27 G_BEGIN_DECLS 28 29 G_GNUC_BEGIN_IGNORE_DEPRECATIONS 30 31 typedef struct _GUri GUri; 32 33 GLIB_AVAILABLE_IN_2_66 34 GUri * g_uri_ref (GUri *uri); 35 GLIB_AVAILABLE_IN_2_66 36 void 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 */ 79 GLIB_AVAILABLE_TYPE_IN_2_66 80 typedef 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 93 GLIB_AVAILABLE_IN_2_66 94 gboolean 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); 104 GLIB_AVAILABLE_IN_2_66 105 gboolean 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); 117 GLIB_AVAILABLE_IN_2_66 118 gboolean g_uri_split_network (const gchar *uri_string, 119 GUriFlags flags, 120 gchar **scheme, 121 gchar **host, 122 gint *port, 123 GError **error); 124 125 GLIB_AVAILABLE_IN_2_66 126 gboolean g_uri_is_valid (const gchar *uri_string, 127 GUriFlags flags, 128 GError **error); 129 130 GLIB_AVAILABLE_IN_2_66 131 gchar * 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); 139 GLIB_AVAILABLE_IN_2_66 140 gchar * 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 151 GLIB_AVAILABLE_IN_2_66 152 GUri * g_uri_parse (const gchar *uri_string, 153 GUriFlags flags, 154 GError **error); 155 GLIB_AVAILABLE_IN_2_66 156 GUri * g_uri_parse_relative (GUri *base_uri, 157 const gchar *uri_ref, 158 GUriFlags flags, 159 GError **error); 160 161 GLIB_AVAILABLE_IN_2_66 162 gchar * g_uri_resolve_relative (const gchar *base_uri_string, 163 const gchar *uri_ref, 164 GUriFlags flags, 165 GError **error); 166 167 GLIB_AVAILABLE_IN_2_66 168 GUri * 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); 176 GLIB_AVAILABLE_IN_2_66 177 GUri * 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 */ 204 GLIB_AVAILABLE_TYPE_IN_2_66 205 typedef 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 214 GLIB_AVAILABLE_IN_2_66 215 char * g_uri_to_string (GUri *uri); 216 GLIB_AVAILABLE_IN_2_66 217 char * g_uri_to_string_partial (GUri *uri, 218 GUriHideFlags flags); 219 220 GLIB_AVAILABLE_IN_2_66 221 const gchar *g_uri_get_scheme (GUri *uri); 222 GLIB_AVAILABLE_IN_2_66 223 const gchar *g_uri_get_userinfo (GUri *uri); 224 GLIB_AVAILABLE_IN_2_66 225 const gchar *g_uri_get_user (GUri *uri); 226 GLIB_AVAILABLE_IN_2_66 227 const gchar *g_uri_get_password (GUri *uri); 228 GLIB_AVAILABLE_IN_2_66 229 const gchar *g_uri_get_auth_params (GUri *uri); 230 GLIB_AVAILABLE_IN_2_66 231 const gchar *g_uri_get_host (GUri *uri); 232 GLIB_AVAILABLE_IN_2_66 233 gint g_uri_get_port (GUri *uri); 234 GLIB_AVAILABLE_IN_2_66 235 const gchar *g_uri_get_path (GUri *uri); 236 GLIB_AVAILABLE_IN_2_66 237 const gchar *g_uri_get_query (GUri *uri); 238 GLIB_AVAILABLE_IN_2_66 239 const gchar *g_uri_get_fragment (GUri *uri); 240 GLIB_AVAILABLE_IN_2_66 241 GUriFlags 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 */ 256 GLIB_AVAILABLE_TYPE_IN_2_66 257 typedef 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 264 GLIB_AVAILABLE_IN_2_66 265 GHashTable *g_uri_parse_params (const gchar *params, 266 gssize length, 267 const gchar *separators, 268 GUriParamsFlags flags, 269 GError **error); 270 271 typedef struct _GUriParamsIter GUriParamsIter; 272 273 struct _GUriParamsIter 274 { 275 /*< private >*/ 276 gint dummy0; 277 gpointer dummy1; 278 gpointer dummy2; 279 guint8 dummy3[256]; 280 }; 281 282 GLIB_AVAILABLE_IN_2_66 283 void g_uri_params_iter_init (GUriParamsIter *iter, 284 const gchar *params, 285 gssize length, 286 const gchar *separators, 287 GUriParamsFlags flags); 288 289 GLIB_AVAILABLE_IN_2_66 290 gboolean 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 305 GLIB_AVAILABLE_IN_2_66 306 GQuark 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 */ 326 typedef 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 387 GLIB_AVAILABLE_IN_ALL 388 char * g_uri_unescape_string (const char *escaped_string, 389 const char *illegal_characters); 390 GLIB_AVAILABLE_IN_ALL 391 char * g_uri_unescape_segment (const char *escaped_string, 392 const char *escaped_string_end, 393 const char *illegal_characters); 394 395 GLIB_AVAILABLE_IN_ALL 396 char * g_uri_parse_scheme (const char *uri); 397 GLIB_AVAILABLE_IN_2_66 398 const char *g_uri_peek_scheme (const char *uri); 399 400 GLIB_AVAILABLE_IN_ALL 401 char * g_uri_escape_string (const char *unescaped, 402 const char *reserved_chars_allowed, 403 gboolean allow_utf8); 404 405 GLIB_AVAILABLE_IN_2_66 406 GBytes * g_uri_unescape_bytes (const char *escaped_string, 407 gssize length, 408 const char *illegal_characters, 409 GError **error); 410 411 GLIB_AVAILABLE_IN_2_66 412 char * g_uri_escape_bytes (const guint8 *unescaped, 413 gsize length, 414 const char *reserved_chars_allowed); 415 416 G_GNUC_END_IGNORE_DEPRECATIONS 417 418 G_END_DECLS 419