glib/guri.h

   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 = 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