glib-2.0/glib/guri.h

0001 /* GLIB - Library of useful routines for C programming
0002  * Copyright © 2020 Red Hat, Inc.
0003  *
0004  * SPDX-License-Identifier: LGPL-2.1-or-later
0005  *
0006  * This library is free software; you can redistribute it and/or
0007  * modify it under the terms of the GNU Lesser General Public
0008  * License as published by the Free Software Foundation; either
0009  * version 2 of the License, or (at your option) any later version.
0010  *
0011  * This library is distributed in the hope that it will be useful,
0012  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0014  * Lesser General Public License for more details.
0015  *
0016  * You should have received a copy of the GNU Lesser General
0017  * Public License along with this library; if not, see
0018  * <http://www.gnu.org/licenses/>.
0019  */
0020
0021 #pragma once
0022
0023 #if !defined (__GLIB_H_INSIDE__) && !defined (GLIB_COMPILATION)
0024 #error "Only <glib.h> can be included directly."
0025 #endif
0026
0027 #include <glib/gtypes.h>
0028
0029 G_BEGIN_DECLS
0030
0031 G_GNUC_BEGIN_IGNORE_DEPRECATIONS
0032
0033 typedef struct _GUri GUri;
0034
0035 GLIB_AVAILABLE_IN_2_66
0036 GUri *       g_uri_ref              (GUri *uri);
0037 GLIB_AVAILABLE_IN_2_66
0038 void         g_uri_unref            (GUri *uri);
0039
0040 /**
0041  * GUriFlags:
0042  * @G_URI_FLAGS_NONE: No flags set.
0043  * @G_URI_FLAGS_PARSE_RELAXED: Parse the URI more relaxedly than the
0044  *     [RFC 3986](https://tools.ietf.org/html/rfc3986) grammar specifies,
0045  *     fixing up or ignoring common mistakes in URIs coming from external
0046  *     sources. This is also needed for some obscure URI schemes where `;`
0047  *     separates the host from the path. Don’t use this flag unless you need to.
0048  * @G_URI_FLAGS_HAS_PASSWORD: The userinfo field may contain a password,
0049  *     which will be separated from the username by `:`.
0050  * @G_URI_FLAGS_HAS_AUTH_PARAMS: The userinfo may contain additional
0051  *     authentication-related parameters, which will be separated from
0052  *     the username and/or password by `;`.
0053  * @G_URI_FLAGS_NON_DNS: The host component should not be assumed to be a
0054  *     DNS hostname or IP address (for example, for `smb` URIs with NetBIOS
0055  *     hostnames).
0056  * @G_URI_FLAGS_ENCODED: When parsing a URI, this indicates that `%`-encoded
0057  *     characters in the userinfo, path, query, and fragment fields
0058  *     should not be decoded. (And likewise the host field if
0059  *     %G_URI_FLAGS_NON_DNS is also set.) When building a URI, it indicates
0060  *     that you have already `%`-encoded the components, and so #GUri
0061  *     should not do any encoding itself.
0062  * @G_URI_FLAGS_ENCODED_QUERY: Same as %G_URI_FLAGS_ENCODED, for the query
0063  *     field only.
0064  * @G_URI_FLAGS_ENCODED_PATH: Same as %G_URI_FLAGS_ENCODED, for the path only.
0065  * @G_URI_FLAGS_ENCODED_FRAGMENT: Same as %G_URI_FLAGS_ENCODED, for the
0066  *     fragment only.
0067  * @G_URI_FLAGS_SCHEME_NORMALIZE: A scheme-based normalization will be applied.
0068  *     For example, when parsing an HTTP URI changing omitted path to `/` and
0069  *     omitted port to `80`; and when building a URI, changing empty path to `/`
0070  *     and default port `80`). This only supports a subset of known schemes. (Since: 2.68)
0071  *
0072  * Flags that describe a URI.
0073  *
0074  * When parsing a URI, if you need to choose different flags based on
0075  * the type of URI, you can use g_uri_peek_scheme() on the URI string
0076  * to check the scheme first, and use that to decide what flags to
0077  * parse it with.
0078  *
0079  * Since: 2.66
0080  */
0081 GLIB_AVAILABLE_TYPE_IN_2_66
0082 typedef enum {
0083   G_URI_FLAGS_NONE            = 0,
0084   G_URI_FLAGS_PARSE_RELAXED   = 1 << 0,
0085   G_URI_FLAGS_HAS_PASSWORD    = 1 << 1,
0086   G_URI_FLAGS_HAS_AUTH_PARAMS = 1 << 2,
0087   G_URI_FLAGS_ENCODED         = 1 << 3,
0088   G_URI_FLAGS_NON_DNS         = 1 << 4,
0089   G_URI_FLAGS_ENCODED_QUERY   = 1 << 5,
0090   G_URI_FLAGS_ENCODED_PATH    = 1 << 6,
0091   G_URI_FLAGS_ENCODED_FRAGMENT = 1 << 7,
0092   G_URI_FLAGS_SCHEME_NORMALIZE GLIB_AVAILABLE_ENUMERATOR_IN_2_68 = 1 << 8,
0093 } GUriFlags;
0094
0095 GLIB_AVAILABLE_IN_2_66
0096 gboolean     g_uri_split            (const gchar  *uri_ref,
0097                                      GUriFlags     flags,
0098                                      gchar       **scheme,
0099                                      gchar       **userinfo,
0100                                      gchar       **host,
0101                                      gint         *port,
0102                                      gchar       **path,
0103                                      gchar       **query,
0104                                      gchar       **fragment,
0105                                      GError      **error);
0106 GLIB_AVAILABLE_IN_2_66
0107 gboolean     g_uri_split_with_user  (const gchar  *uri_ref,
0108                                      GUriFlags     flags,
0109                                      gchar       **scheme,
0110                                      gchar       **user,
0111                                      gchar       **password,
0112                                      gchar       **auth_params,
0113                                      gchar       **host,
0114                                      gint         *port,
0115                                      gchar       **path,
0116                                      gchar       **query,
0117                                      gchar       **fragment,
0118                                      GError      **error);
0119 GLIB_AVAILABLE_IN_2_66
0120 gboolean     g_uri_split_network    (const gchar  *uri_string,
0121                                      GUriFlags     flags,
0122                                      gchar       **scheme,
0123                                      gchar       **host,
0124                                      gint         *port,
0125                                      GError      **error);
0126
0127 GLIB_AVAILABLE_IN_2_66
0128 gboolean     g_uri_is_valid         (const gchar  *uri_string,
0129                                      GUriFlags     flags,
0130                                      GError      **error);
0131
0132 GLIB_AVAILABLE_IN_2_66
0133 gchar *      g_uri_join             (GUriFlags     flags,
0134                                      const gchar  *scheme,
0135                                      const gchar  *userinfo,
0136                                      const gchar  *host,
0137                                      gint          port,
0138                                      const gchar  *path,
0139                                      const gchar  *query,
0140                                      const gchar  *fragment);
0141 GLIB_AVAILABLE_IN_2_66
0142 gchar *      g_uri_join_with_user   (GUriFlags     flags,
0143                                      const gchar  *scheme,
0144                                      const gchar  *user,
0145                                      const gchar  *password,
0146                                      const gchar  *auth_params,
0147                                      const gchar  *host,
0148                                      gint          port,
0149                                      const gchar  *path,
0150                                      const gchar  *query,
0151                                      const gchar  *fragment);
0152
0153 GLIB_AVAILABLE_IN_2_66
0154 GUri *       g_uri_parse            (const gchar  *uri_string,
0155                                      GUriFlags     flags,
0156                                      GError      **error);
0157 GLIB_AVAILABLE_IN_2_66
0158 GUri *       g_uri_parse_relative   (GUri         *base_uri,
0159                                      const gchar  *uri_ref,
0160                                      GUriFlags     flags,
0161                                      GError      **error);
0162
0163 GLIB_AVAILABLE_IN_2_66
0164 gchar *      g_uri_resolve_relative (const gchar  *base_uri_string,
0165                                      const gchar  *uri_ref,
0166                                      GUriFlags     flags,
0167                                      GError      **error);
0168
0169 GLIB_AVAILABLE_IN_2_66
0170 GUri *       g_uri_build            (GUriFlags     flags,
0171                                      const gchar  *scheme,
0172                                      const gchar  *userinfo,
0173                                      const gchar  *host,
0174                                      gint          port,
0175                                      const gchar  *path,
0176                                      const gchar  *query,
0177                                      const gchar  *fragment);
0178 GLIB_AVAILABLE_IN_2_66
0179 GUri *       g_uri_build_with_user  (GUriFlags     flags,
0180                                      const gchar  *scheme,
0181                                      const gchar  *user,
0182                                      const gchar  *password,
0183                                      const gchar  *auth_params,
0184                                      const gchar  *host,
0185                                      gint          port,
0186                                      const gchar  *path,
0187                                      const gchar  *query,
0188                                      const gchar  *fragment);
0189
0190 /**
0191  * GUriHideFlags:
0192  * @G_URI_HIDE_NONE: No flags set.
0193  * @G_URI_HIDE_USERINFO: Hide the userinfo.
0194  * @G_URI_HIDE_PASSWORD: Hide the password.
0195  * @G_URI_HIDE_AUTH_PARAMS: Hide the auth_params.
0196  * @G_URI_HIDE_QUERY: Hide the query.
0197  * @G_URI_HIDE_FRAGMENT: Hide the fragment.
0198  *
0199  * Flags describing what parts of the URI to hide in
0200  * g_uri_to_string_partial(). Note that %G_URI_HIDE_PASSWORD and
0201  * %G_URI_HIDE_AUTH_PARAMS will only work if the #GUri was parsed with
0202  * the corresponding flags.
0203  *
0204  * Since: 2.66
0205  */
0206 GLIB_AVAILABLE_TYPE_IN_2_66
0207 typedef enum {
0208   G_URI_HIDE_NONE        = 0,
0209   G_URI_HIDE_USERINFO    = 1 << 0,
0210   G_URI_HIDE_PASSWORD    = 1 << 1,
0211   G_URI_HIDE_AUTH_PARAMS = 1 << 2,
0212   G_URI_HIDE_QUERY       = 1 << 3,
0213   G_URI_HIDE_FRAGMENT    = 1 << 4,
0214 } GUriHideFlags;
0215
0216 GLIB_AVAILABLE_IN_2_66
0217 char *       g_uri_to_string         (GUri          *uri);
0218 GLIB_AVAILABLE_IN_2_66
0219 char *       g_uri_to_string_partial (GUri          *uri,
0220                                       GUriHideFlags  flags);
0221
0222 GLIB_AVAILABLE_IN_2_66
0223 const gchar *g_uri_get_scheme        (GUri          *uri);
0224 GLIB_AVAILABLE_IN_2_66
0225 const gchar *g_uri_get_userinfo      (GUri          *uri);
0226 GLIB_AVAILABLE_IN_2_66
0227 const gchar *g_uri_get_user          (GUri          *uri);
0228 GLIB_AVAILABLE_IN_2_66
0229 const gchar *g_uri_get_password      (GUri          *uri);
0230 GLIB_AVAILABLE_IN_2_66
0231 const gchar *g_uri_get_auth_params   (GUri          *uri);
0232 GLIB_AVAILABLE_IN_2_66
0233 const gchar *g_uri_get_host          (GUri          *uri);
0234 GLIB_AVAILABLE_IN_2_66
0235 gint         g_uri_get_port          (GUri          *uri);
0236 GLIB_AVAILABLE_IN_2_66
0237 const gchar *g_uri_get_path          (GUri          *uri);
0238 GLIB_AVAILABLE_IN_2_66
0239 const gchar *g_uri_get_query         (GUri          *uri);
0240 GLIB_AVAILABLE_IN_2_66
0241 const gchar *g_uri_get_fragment      (GUri          *uri);
0242 GLIB_AVAILABLE_IN_2_66
0243 GUriFlags    g_uri_get_flags         (GUri          *uri);
0244
0245 /**
0246  * GUriParamsFlags:
0247  * @G_URI_PARAMS_NONE: No flags set.
0248  * @G_URI_PARAMS_CASE_INSENSITIVE: Parameter names are case insensitive.
0249  * @G_URI_PARAMS_WWW_FORM: Replace `+` with space character. Only useful for
0250  *     URLs on the web, using the `https` or `http` schemas.
0251  * @G_URI_PARAMS_PARSE_RELAXED: See %G_URI_FLAGS_PARSE_RELAXED.
0252  *
0253  * Flags modifying the way parameters are handled by g_uri_parse_params() and
0254  * #GUriParamsIter.
0255  *
0256  * Since: 2.66
0257  */
0258 GLIB_AVAILABLE_TYPE_IN_2_66
0259 typedef enum {
0260   G_URI_PARAMS_NONE             = 0,
0261   G_URI_PARAMS_CASE_INSENSITIVE = 1 << 0,
0262   G_URI_PARAMS_WWW_FORM         = 1 << 1,
0263   G_URI_PARAMS_PARSE_RELAXED    = 1 << 2,
0264 } GUriParamsFlags;
0265
0266 GLIB_AVAILABLE_IN_2_66
0267 GHashTable *g_uri_parse_params       (const gchar    *params,
0268                                       gssize          length,
0269                                       const gchar    *separators,
0270                                       GUriParamsFlags flags,
0271                                       GError        **error);
0272
0273 typedef struct _GUriParamsIter GUriParamsIter;
0274
0275 struct _GUriParamsIter
0276 {
0277   /*< private >*/
0278   gint     dummy0;
0279   gpointer dummy1;
0280   gpointer dummy2;
0281   guint8   dummy3[256];
0282 };
0283
0284 GLIB_AVAILABLE_IN_2_66
0285 void        g_uri_params_iter_init   (GUriParamsIter *iter,
0286                                       const gchar    *params,
0287                                       gssize          length,
0288                                       const gchar    *separators,
0289                                       GUriParamsFlags flags);
0290
0291 GLIB_AVAILABLE_IN_2_66
0292 gboolean    g_uri_params_iter_next   (GUriParamsIter *iter,
0293                                       gchar         **attribute,
0294                                       gchar         **value,
0295                                       GError        **error);
0296
0297 /**
0298  * G_URI_ERROR:
0299  *
0300  * Error domain for URI methods. Errors in this domain will be from
0301  * the #GUriError enumeration. See #GError for information on error
0302  * domains.
0303  *
0304  * Since: 2.66
0305  */
0306 #define G_URI_ERROR (g_uri_error_quark ()) GLIB_AVAILABLE_MACRO_IN_2_66
0307 GLIB_AVAILABLE_IN_2_66
0308 GQuark g_uri_error_quark (void);
0309
0310 /**
0311  * GUriError:
0312  * @G_URI_ERROR_FAILED: Generic error if no more specific error is available.
0313  *     See the error message for details.
0314  * @G_URI_ERROR_BAD_SCHEME: The scheme of a URI could not be parsed.
0315  * @G_URI_ERROR_BAD_USER: The user/userinfo of a URI could not be parsed.
0316  * @G_URI_ERROR_BAD_PASSWORD: The password of a URI could not be parsed.
0317  * @G_URI_ERROR_BAD_AUTH_PARAMS: The authentication parameters of a URI could not be parsed.
0318  * @G_URI_ERROR_BAD_HOST: The host of a URI could not be parsed.
0319  * @G_URI_ERROR_BAD_PORT: The port of a URI could not be parsed.
0320  * @G_URI_ERROR_BAD_PATH: The path of a URI could not be parsed.
0321  * @G_URI_ERROR_BAD_QUERY: The query of a URI could not be parsed.
0322  * @G_URI_ERROR_BAD_FRAGMENT: The fragment of a URI could not be parsed.
0323  *
0324  * Error codes returned by #GUri methods.
0325  *
0326  * Since: 2.66
0327  */
0328 typedef enum {
0329   G_URI_ERROR_FAILED,
0330   G_URI_ERROR_BAD_SCHEME,
0331   G_URI_ERROR_BAD_USER,
0332   G_URI_ERROR_BAD_PASSWORD,
0333   G_URI_ERROR_BAD_AUTH_PARAMS,
0334   G_URI_ERROR_BAD_HOST,
0335   G_URI_ERROR_BAD_PORT,
0336   G_URI_ERROR_BAD_PATH,
0337   G_URI_ERROR_BAD_QUERY,
0338   G_URI_ERROR_BAD_FRAGMENT,
0339 } GUriError;
0340
0341 /**
0342  * G_URI_RESERVED_CHARS_GENERIC_DELIMITERS:
0343  *
0344  * Generic delimiters characters as defined in
0345  * [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `:/?#[]@`.
0346  *
0347  * Since: 2.16
0348  **/
0349 #define G_URI_RESERVED_CHARS_GENERIC_DELIMITERS ":/?#[]@"
0350
0351 /**
0352  * G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS:
0353  *
0354  * Subcomponent delimiter characters as defined in
0355  * [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=`.
0356  *
0357  * Since: 2.16
0358  **/
0359 #define G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS "!$&'()*+,;="
0360
0361 /**
0362  * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT:
0363  *
0364  * Allowed characters in path elements. Includes `!$&'()*+,;=:@`.
0365  *
0366  * Since: 2.16
0367  **/
0368 #define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":@"
0369
0370 /**
0371  * G_URI_RESERVED_CHARS_ALLOWED_IN_PATH:
0372  *
0373  * Allowed characters in a path. Includes `!$&'()*+,;=:@/`.
0374  *
0375  * Since: 2.16
0376  **/
0377 #define G_URI_RESERVED_CHARS_ALLOWED_IN_PATH G_URI_RESERVED_CHARS_ALLOWED_IN_PATH_ELEMENT "/"
0378
0379 /**
0380  * G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO:
0381  *
0382  * Allowed characters in userinfo as defined in
0383  * [RFC 3986](https://tools.ietf.org/html/rfc3986). Includes `!$&'()*+,;=:`.
0384  *
0385  * Since: 2.16
0386  **/
0387 #define G_URI_RESERVED_CHARS_ALLOWED_IN_USERINFO G_URI_RESERVED_CHARS_SUBCOMPONENT_DELIMITERS ":"
0388
0389 GLIB_AVAILABLE_IN_ALL
0390 char *      g_uri_unescape_string  (const char *escaped_string,
0391                                     const char *illegal_characters);
0392 GLIB_AVAILABLE_IN_ALL
0393 char *      g_uri_unescape_segment (const char *escaped_string,
0394                                     const char *escaped_string_end,
0395                                     const char *illegal_characters);
0396
0397 GLIB_AVAILABLE_IN_ALL
0398 char *      g_uri_parse_scheme     (const char *uri);
0399 GLIB_AVAILABLE_IN_2_66
0400 const char *g_uri_peek_scheme      (const char *uri);
0401
0402 GLIB_AVAILABLE_IN_ALL
0403 char *      g_uri_escape_string    (const char *unescaped,
0404                                     const char *reserved_chars_allowed,
0405                                     gboolean    allow_utf8);
0406
0407 GLIB_AVAILABLE_IN_2_66
0408 GBytes *    g_uri_unescape_bytes   (const char *escaped_string,
0409                                     gssize      length,
0410                                     const char *illegal_characters,
0411                                     GError    **error);
0412
0413 GLIB_AVAILABLE_IN_2_66
0414 char *      g_uri_escape_bytes     (const guint8 *unescaped,
0415                                     gsize         length,
0416                                     const char   *reserved_chars_allowed);
0417
0418 G_GNUC_END_IGNORE_DEPRECATIONS
0419
0420 G_END_DECLS