glib/guri.h

   1 /* GLIB - Library of useful routines for C programming
   2  * Copyright © 2020 Red Hat, Inc.
   3  *
   4  * SPDX-License-Identifier: LGPL-2.1-or-later
   5  *
   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.
  10  *
  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.
  15  *
  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/>.
  19  */
  20
  21 #pragma once
  22
  23 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
  24 #error "Only <glib.h> can be included directly."
  25 #endif
  26
  27 #include <glib/gtypes.h>
  28
  29 G_BEGIN_DECLS
  30
  31 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
  32
  33 typedef struct _GUri GUri;
  34
  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);
  39
  40 /**
  41  * GUriFlags:
  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
  55  *     hostnames).
  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
  63  *     field only.
  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
  66  *     fragment only.
  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)
  71  *
  72  * Flags that describe a URI.
  73  *
  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
  77  * parse it with.
  78  *
  79  * Since: 2.66
  80  */
  81 GLIB_AVAILABLE_TYPE_IN_2_66
  82 typedef enum {
  83   G_URI_FLAGS_NONE            = 0,
  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,
  93 } GUriFlags;
  94
  95 GLIB_AVAILABLE_IN_2_66
  96 gboolean     g_uri_split            (const gchar  *uri_ref,
  97                                      GUriFlags     flags,
  98                                      gchar       **scheme,
  99                                      gchar       **userinfo,
 100                                      gchar       **host,
 101                                      gint         *port,
 102                                      gchar       **path,
 103                                      gchar       **query,
 104                                      gchar       **fragment,
 105                                      GError      **error);
 106 GLIB_AVAILABLE_IN_2_66
 107 gboolean     g_uri_split_with_user  (const gchar  *uri_ref,
 108                                      GUriFlags     flags,
 109                                      gchar       **scheme,
 110                                      gchar       **user,
 111                                      gchar       **password,
 112                                      gchar       **auth_params,
 113                                      gchar       **host,
 114                                      gint         *port,
 115                                      gchar       **path,
 116                                      gchar       **query,
 117                                      gchar       **fragment,
 118                                      GError      **error);
 119 GLIB_AVAILABLE_IN_2_66
 120 gboolean     g_uri_split_network    (const gchar  *uri_string,
 121                                      GUriFlags     flags,
 122                                      gchar       **scheme,
 123                                      gchar       **host,
 124                                      gint         *port,
 125                                      GError      **error);
 126
 127 GLIB_AVAILABLE_IN_2_66
 128 gboolean     g_uri_is_valid         (const gchar  *uri_string,
 129                                      GUriFlags     flags,
 130                                      GError      **error);
 131
 132 GLIB_AVAILABLE_IN_2_66
 133 gchar *      g_uri_join             (GUriFlags     flags,
 134                                      const gchar  *scheme,
 135                                      const gchar  *userinfo,
 136                                      const gchar  *host,
 137                                      gint          port,
 138                                      const gchar  *path,
 139                                      const gchar  *query,
 140                                      const gchar  *fragment);
 141 GLIB_AVAILABLE_IN_2_66
 142 gchar *      g_uri_join_with_user   (GUriFlags     flags,
 143                                      const gchar  *scheme,
 144                                      const gchar  *user,
 145                                      const gchar  *password,
 146                                      const gchar  *auth_params,
 147                                      const gchar  *host,
 148                                      gint          port,
 149                                      const gchar  *path,
 150                                      const gchar  *query,
 151                                      const gchar  *fragment);
 152
 153 GLIB_AVAILABLE_IN_2_66
 154 GUri *       g_uri_parse            (const gchar  *uri_string,
 155                                      GUriFlags     flags,
 156                                      GError      **error);
 157 GLIB_AVAILABLE_IN_2_66
 158 GUri *       g_uri_parse_relative   (GUri         *base_uri,
 159                                      const gchar  *uri_ref,
 160                                      GUriFlags     flags,
 161                                      GError      **error);
 162
 163 GLIB_AVAILABLE_IN_2_66
 164 gchar *      g_uri_resolve_relative (const gchar  *base_uri_string,
 165                                      const gchar  *uri_ref,
 166                                      GUriFlags     flags,
 167                                      GError      **error);
 168
 169 GLIB_AVAILABLE_IN_2_66
 170 GUri *       g_uri_build            (GUriFlags     flags,
 171                                      const gchar  *scheme,
 172                                      const gchar  *userinfo,
 173                                      const gchar  *host,
 174                                      gint          port,
 175                                      const gchar  *path,
 176                                      const gchar  *query,
 177                                      const gchar  *fragment);
 178 GLIB_AVAILABLE_IN_2_66
 179 GUri *       g_uri_build_with_user  (GUriFlags     flags,
 180                                      const gchar  *scheme,
 181                                      const gchar  *user,
 182                                      const gchar  *password,
 183                                      const gchar  *auth_params,
 184                                      const gchar  *host,
 185                                      gint          port,
 186                                      const gchar  *path,
 187                                      const gchar  *query,
 188                                      const gchar  *fragment);
 189
 190 /**
 191  * GUriHideFlags:
 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.
 198  *
 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.
 203  *
 204  * Since: 2.66
 205  */
 206 GLIB_AVAILABLE_TYPE_IN_2_66
 207 typedef enum {
 208   G_URI_HIDE_NONE        = 0,
 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,
 214 } GUriHideFlags;
 215
 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);
 221
 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);
 244
 245 /**
 246  * GUriParamsFlags:
 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.
 252  *
 253  * Flags modifying the way parameters are handled by g_uri_parse_params() and
 254  * #GUriParamsIter.
 255  *
 256  * Since: 2.66
 257  */
 258 GLIB_AVAILABLE_TYPE_IN_2_66
 259 typedef enum {
 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,
 264 } GUriParamsFlags;
 265
 266 GLIB_AVAILABLE_IN_2_66
 267 GHashTable *g_uri_parse_params       (const gchar    *params,
 268                                       gssize          length,
 269                                       const gchar    *separators,
 270                                       GUriParamsFlags flags,
 271                                       GError        **error);
 272
 273 typedef struct _GUriParamsIter GUriParamsIter;
 274
 275 struct _GUriParamsIter
 276 {
 277   /*< private >*/
 278   gint     dummy0;
 279   gpointer dummy1;
 280   gpointer dummy2;
 281   guint8   dummy3[256];
 282 };
 283
 284 GLIB_AVAILABLE_IN_2_66
 285 void        g_uri_params_iter_init   (GUriParamsIter *iter,
 286                                       const gchar    *params,
 287                                       gssize          length,
 288                                       const gchar    *separators,
 289                                       GUriParamsFlags flags);
 290
 291 GLIB_AVAILABLE_IN_2_66
 292 gboolean    g_uri_params_iter_next   (GUriParamsIter *iter,
 293                                       gchar         **attribute,
 294                                       gchar         **value,
 295                                       GError        **error);
 296
 297 /**
 298  * G_URI_ERROR:
 299  *
 300  * Error domain for URI methods. Errors in this domain will be from
 301  * the #GUriError enumeration. See #GError for information on error
 302  * domains.
 303  *
 304  * Since: 2.66
 305  */
 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);
 309
 310 /**
 311  * GUriError:
 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.
 323  *
 324  * Error codes returned by #GUri methods.
 325  *
 326  * Since: 2.66
 327  */
 328 typedef enum {
 329   G_URI_ERROR_FAILED,
 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,
 339 } GUriError;
 340
 341 /**
 342  * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS:
 343  *
 344  * Generic delimiters characters as defined in
 345  * [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `:/?#[]@`.
 346  *
 347  * Since: 2.16
 348  **/
 349 #define G_URI_RESERVED_CHARS_GENERIC_DELIMITERS ":/?#[]@"
 350
 351 /**
 352  * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS:
 353  *
 354  * Subcomponent delimiter characters as defined in
 355  * [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=`.
 356  *
 357  * Since: 2.16
 358  **/
 359 #define G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS "!$&'()*+,;="
 360
 361 /**
 362  * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT:
 363  *
 364  * Allowed characters in path elements. Includes `!$&'()*+,;=:@`.
 365  *
 366  * Since: 2.16
 367  **/
 368 #define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":@"
 369
 370 /**
 371  * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH:
 372  *
 373  * Allowed characters in a path. Includes `!$&'()*+,;=:@/`.
 374  *
 375  * Since: 2.16
 376  **/
 377 #define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT "/"
 378
 379 /**
 380  * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO:
 381  *
 382  * Allowed characters in userinfo as defined in
 383  * [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=:`.
 384  *
 385  * Since: 2.16
 386  **/
 387 #define G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":"
 388
 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);
 396
 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);
 401
 402 GLIB_AVAILABLE_IN_ALL
 403 char *      g_uri_escape_string    (const char *unescaped,
 404                                     const char *reserved_chars_allowed,
 405                                     gboolean    allow_utf8);
 406
 407 GLIB_AVAILABLE_IN_2_66
 408 GBytes *    g_uri_unescape_bytes   (const char *escaped_string,
 409                                     gssize      length,
 410                                     const char *illegal_characters,
 411                                     GError    **error);
 412
 413 GLIB_AVAILABLE_IN_2_66
 414 char *      g_uri_escape_bytes     (const guint8 *unescaped,
 415                                     gsize         length,
 416                                     const char   *reserved_chars_allowed);
 417
 418 G_GNUC_END_IGNORE_DEPRECATIONS
 419
 420 G_END_DECLS