glib/auto/

uri.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{Bytes, Error, UriFlags, UriHideFlags, ffi, translate::*};

crate::wrapper! {
    /// err);
    /// g_assert_error (err, G_URI_ERROR, G_URI_ERROR_BAD_QUERY);
    /// ```text
    ///
    /// You should pass `G_URI_FLAGS_ENCODED` or `G_URI_FLAGS_ENCODED_QUERY` if you
    /// need to handle that case manually. In particular, if the query string
    /// contains `=` characters that are `%`-encoded, you should let
    /// `GLib::Uri::parse_params()` do the decoding once of the query.
    ///
    /// `GUri` is immutable once constructed, and can safely be accessed from
    /// multiple threads. Its reference counting is atomic.
    ///
    /// Note that the scope of `GUri` is to help manipulate URIs in various applications,
    /// following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular,
    /// it doesn't intend to cover web browser needs, and doesn’t implement the
    /// [WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to
    /// help prevent
    /// [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so
    /// `GUri` is not suitable for formatting URIs for display to the user for making
    /// security-sensitive decisions.
    ///
    /// ## Relative and absolute URIs
    ///
    /// As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the
    /// hierarchical nature of URIs means that they can either be ‘relative
    /// references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for
    /// clarity, ‘URIs’ are referred to in this documentation as
    /// ‘absolute URIs’ — although
    /// [in contrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3),
    /// fragment identifiers are always allowed).
    ///
    /// Relative references have one or more components of the URI missing. In
    /// particular, they have no scheme. Any other component, such as hostname,
    /// query, etc. may be missing, apart from a path, which has to be specified (but
    /// may be empty). The path may be relative, starting with `./` rather than `/`.
    ///
    /// For example, a valid relative reference is `./path?query`,
    /// `/?query#fragment` or `//example.com`.
    ///
    /// Absolute URIs have a scheme specified. Any other components of the URI which
    /// are missing are specified as explicitly unset in the URI, rather than being
    /// resolved relative to a base URI using [`parse_relative()`][Self::parse_relative()].
    ///
    /// For example, a valid absolute URI is `file:///home/bob` or
    /// `https://search.com?query=string`.
    ///
    /// A `GUri` instance is always an absolute URI. A string may be an absolute URI
    /// or a relative reference; see the documentation for individual functions as to
    /// what forms they accept.
    ///
    /// ## Parsing URIs
    ///
    /// The most minimalist APIs for parsing URIs are [`split()`][Self::split()] and
    /// [`split_with_user()`][Self::split_with_user()]. These split a URI into its component
    /// parts, and return the parts; the difference between the two is that
    /// [`split()`][Self::split()] treats the ‘userinfo’ component of the URI as a
    /// single element, while [`split_with_user()`][Self::split_with_user()] can (depending on the
    /// [`UriFlags`][crate::UriFlags] you pass) treat it as containing a username, password,
    /// and authentication parameters. Alternatively, [`split_network()`][Self::split_network()]
    /// can be used when you are only interested in the components that are
    /// needed to initiate a network connection to the service (scheme,
    /// host, and port).
    ///
    /// [`parse()`][Self::parse()] is similar to [`split()`][Self::split()], but instead of
    /// returning individual strings, it returns a `GUri` structure (and it requires
    /// that the URI be an absolute URI).
    ///
    /// [`resolve_relative()`][Self::resolve_relative()] and [`parse_relative()`][Self::parse_relative()] allow
    /// you to resolve a relative URI relative to a base URI.
    /// [`resolve_relative()`][Self::resolve_relative()] takes two strings and returns a string,
    /// and [`parse_relative()`][Self::parse_relative()] takes a `GUri` and a string and returns a
    /// `GUri`.
    ///
    /// All of the parsing functions take a [`UriFlags`][crate::UriFlags] argument describing
    /// exactly how to parse the URI; see the documentation for that type
    /// for more details on the specific flags that you can pass. If you
    /// need to choose different flags based on the type of URI, you can
    /// use [`peek_scheme()`][Self::peek_scheme()] on the URI string to check the scheme
    /// first, and use that to decide what flags to parse it with.
    ///
    /// For example, you might want to use `G_URI_PARAMS_WWW_FORM` when parsing the
    /// params for a web URI, so compare the result of [`peek_scheme()`][Self::peek_scheme()]
    /// against `http` and `https`.
    ///
    /// ## Building URIs
    ///
    /// [`join()`][Self::join()] and [`join_with_user()`][Self::join_with_user()] can be used to construct
    /// valid URI strings from a set of component strings. They are the
    /// inverse of [`split()`][Self::split()] and [`split_with_user()`][Self::split_with_user()].
    ///
    /// Similarly, [`build()`][Self::build()] and [`build_with_user()`][Self::build_with_user()] can be
    /// used to construct a `GUri` from a set of component strings.
    ///
    /// As with the parsing functions, the building functions take a
    /// [`UriFlags`][crate::UriFlags] argument. In particular, it is important to keep in mind
    /// whether the URI components you are using are already `%`-encoded. If so,
    /// you must pass the `G_URI_FLAGS_ENCODED` flag.
    ///
    /// ## `file://` URIs
    ///
    /// Note that Windows and Unix both define special rules for parsing
    /// `file://` URIs (involving non-UTF-8 character sets on Unix, and the
    /// interpretation of path separators on Windows). `GUri` does not
    /// implement these rules. Use [`filename_from_uri()`][crate::filename_from_uri()] and
    /// [`filename_to_uri()`][crate::filename_to_uri()] if you want to properly convert between
    /// `file://` URIs and local filenames.
    ///
    /// ## URI Equality
    ///
    /// Note that there is no `g_uri_equal ()` function, because comparing
    /// URIs usefully requires scheme-specific knowledge that `GUri` does
    /// not have. `GUri` can help with normalization if you use the various
    /// encoded [`UriFlags`][crate::UriFlags] as well as `G_URI_FLAGS_SCHEME_NORMALIZE`
    /// however it is not comprehensive.
    /// For example, `data:,foo` and `data:;base64,Zm9v` resolve to the same
    /// thing according to the `data:` URI specification which GLib does not
    /// handle.
    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
    pub struct Uri(Shared<ffi::GUri>);

    match fn {
        ref => |ptr| ffi::g_uri_ref(ptr),
        unref => |ptr| ffi::g_uri_unref(ptr),
        type_ => || ffi::g_uri_get_type(),
    }
}

impl Uri {
    /// Gets @self's authentication parameters, which may contain
    /// `%`-encoding, depending on the flags with which @self was created.
    /// (If @self was not created with [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] then this will
    /// be [`None`].)
    ///
    /// Depending on the URI scheme, g_uri_parse_params() may be useful for
    /// further parsing this information.
    ///
    /// # Returns
    ///
    /// @self's authentication parameters.
    #[doc(alias = "g_uri_get_auth_params")]
    #[doc(alias = "get_auth_params")]
    pub fn auth_params(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_auth_params(self.to_glib_none().0)) }
    }

    /// Gets @self's flags set upon construction.
    ///
    /// # Returns
    ///
    /// @self's flags.
    #[doc(alias = "g_uri_get_flags")]
    #[doc(alias = "get_flags")]
    pub fn flags(&self) -> UriFlags {
        unsafe { from_glib(ffi::g_uri_get_flags(self.to_glib_none().0)) }
    }

    /// Gets @self's fragment, which may contain `%`-encoding, depending on
    /// the flags with which @self was created.
    ///
    /// # Returns
    ///
    /// @self's fragment.
    #[doc(alias = "g_uri_get_fragment")]
    #[doc(alias = "get_fragment")]
    pub fn fragment(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_fragment(self.to_glib_none().0)) }
    }

    /// Gets @self's host. This will never have `%`-encoded characters,
    /// unless it is non-UTF-8 (which can only be the case if @self was
    /// created with [`UriFlags::NON_DNS`][crate::UriFlags::NON_DNS]).
    ///
    /// If @self contained an IPv6 address literal, this value will be just
    /// that address, without the brackets around it that are necessary in
    /// the string form of the URI. Note that in this case there may also
    /// be a scope ID attached to the address. Eg, `fe80::1234%``em1` (or
    /// `fe80::1234%``25em1` if the string is still encoded).
    ///
    /// # Returns
    ///
    /// @self's host.
    #[doc(alias = "g_uri_get_host")]
    #[doc(alias = "get_host")]
    pub fn host(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_host(self.to_glib_none().0)) }
    }

    /// Gets @self's password, which may contain `%`-encoding, depending on
    /// the flags with which @self was created. (If @self was not created
    /// with [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] then this will be [`None`].)
    ///
    /// # Returns
    ///
    /// @self's password.
    #[doc(alias = "g_uri_get_password")]
    #[doc(alias = "get_password")]
    pub fn password(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_password(self.to_glib_none().0)) }
    }

    /// Gets @self's path, which may contain `%`-encoding, depending on the
    /// flags with which @self was created.
    ///
    /// # Returns
    ///
    /// @self's path.
    #[doc(alias = "g_uri_get_path")]
    #[doc(alias = "get_path")]
    pub fn path(&self) -> crate::GString {
        unsafe { from_glib_none(ffi::g_uri_get_path(self.to_glib_none().0)) }
    }

    /// Gets @self's port.
    ///
    /// # Returns
    ///
    /// @self's port, or `-1` if no port was specified.
    #[doc(alias = "g_uri_get_port")]
    #[doc(alias = "get_port")]
    pub fn port(&self) -> i32 {
        unsafe { ffi::g_uri_get_port(self.to_glib_none().0) }
    }

    /// Gets @self's query, which may contain `%`-encoding, depending on the
    /// flags with which @self was created.
    ///
    /// For queries consisting of a series of `name=value` parameters,
    /// #GUriParamsIter or g_uri_parse_params() may be useful.
    ///
    /// # Returns
    ///
    /// @self's query.
    #[doc(alias = "g_uri_get_query")]
    #[doc(alias = "get_query")]
    pub fn query(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_query(self.to_glib_none().0)) }
    }

    /// Gets @self's scheme. Note that this will always be all-lowercase,
    /// regardless of the string or strings that @self was created from.
    ///
    /// # Returns
    ///
    /// @self's scheme.
    #[doc(alias = "g_uri_get_scheme")]
    #[doc(alias = "get_scheme")]
    pub fn scheme(&self) -> crate::GString {
        unsafe { from_glib_none(ffi::g_uri_get_scheme(self.to_glib_none().0)) }
    }

    /// Gets the ‘username’ component of @self's userinfo, which may contain
    /// `%`-encoding, depending on the flags with which @self was created.
    /// If @self was not created with [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] or
    /// [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS], this is the same as g_uri_get_userinfo().
    ///
    /// # Returns
    ///
    /// @self's user.
    #[doc(alias = "g_uri_get_user")]
    #[doc(alias = "get_user")]
    pub fn user(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_user(self.to_glib_none().0)) }
    }

    /// Gets @self's userinfo, which may contain `%`-encoding, depending on
    /// the flags with which @self was created.
    ///
    /// # Returns
    ///
    /// @self's userinfo.
    #[doc(alias = "g_uri_get_userinfo")]
    #[doc(alias = "get_userinfo")]
    pub fn userinfo(&self) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_get_userinfo(self.to_glib_none().0)) }
    }

    /// Parses @uri_ref according to @flags and, if it is a
    /// [relative URI](#relative-and-absolute-uris), resolves it relative to @self.
    /// If the result is not a valid absolute URI, it will be discarded, and an error
    /// returned.
    /// ## `uri_ref`
    /// a string representing a relative or absolute URI
    /// ## `flags`
    /// flags describing how to parse @uri_ref
    ///
    /// # Returns
    ///
    /// a new #GUri, or NULL on error.
    #[doc(alias = "g_uri_parse_relative")]
    pub fn parse_relative(&self, uri_ref: &str, flags: UriFlags) -> Result<Uri, crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_uri_parse_relative(
                self.to_glib_none().0,
                uri_ref.to_glib_none().0,
                flags.into_glib(),
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns a string representing @self.
    ///
    /// This is not guaranteed to return a string which is identical to the
    /// string that @self was parsed from. However, if the source URI was
    /// syntactically correct (according to RFC 3986), and it was parsed
    /// with [`UriFlags::ENCODED`][crate::UriFlags::ENCODED], then g_uri_to_string() is guaranteed to return
    /// a string which is at least semantically equivalent to the source
    /// URI (according to RFC 3986).
    ///
    /// If @self might contain sensitive details, such as authentication parameters,
    /// or private data in its query string, and the returned string is going to be
    /// logged, then consider using g_uri_to_string_partial() to redact parts.
    ///
    /// # Returns
    ///
    /// a string representing @self,
    ///     which the caller must free.
    #[doc(alias = "g_uri_to_string")]
    #[doc(alias = "to_string")]
    pub fn to_str(&self) -> crate::GString {
        unsafe { from_glib_full(ffi::g_uri_to_string(self.to_glib_none().0)) }
    }

    /// Returns a string representing @self, subject to the options in
    /// @flags. See g_uri_to_string() and #GUriHideFlags for more details.
    /// ## `flags`
    /// flags describing what parts of @self to hide
    ///
    /// # Returns
    ///
    /// a string representing
    ///     @self, which the caller must free.
    #[doc(alias = "g_uri_to_string_partial")]
    pub fn to_string_partial(&self, flags: UriHideFlags) -> crate::GString {
        unsafe {
            from_glib_full(ffi::g_uri_to_string_partial(
                self.to_glib_none().0,
                flags.into_glib(),
            ))
        }
    }

    /// Creates a new #GUri from the given components according to @flags.
    ///
    /// See also g_uri_build_with_user(), which allows specifying the
    /// components of the "userinfo" separately.
    /// ## `flags`
    /// flags describing how to build the #GUri
    /// ## `scheme`
    /// the URI scheme
    /// ## `userinfo`
    /// the userinfo component, or [`None`]
    /// ## `host`
    /// the host component, or [`None`]
    /// ## `port`
    /// the port, or `-1`
    /// ## `path`
    /// the path component
    /// ## `query`
    /// the query component, or [`None`]
    /// ## `fragment`
    /// the fragment, or [`None`]
    ///
    /// # Returns
    ///
    /// a new #GUri
    #[doc(alias = "g_uri_build")]
    pub fn build(
        flags: UriFlags,
        scheme: &str,
        userinfo: Option<&str>,
        host: Option<&str>,
        port: i32,
        path: &str,
        query: Option<&str>,
        fragment: Option<&str>,
    ) -> Uri {
        unsafe {
            from_glib_full(ffi::g_uri_build(
                flags.into_glib(),
                scheme.to_glib_none().0,
                userinfo.to_glib_none().0,
                host.to_glib_none().0,
                port,
                path.to_glib_none().0,
                query.to_glib_none().0,
                fragment.to_glib_none().0,
            ))
        }
    }

    /// Creates a new #GUri from the given components according to @flags
    /// ([`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] is added unconditionally). The @flags must be
    /// coherent with the passed values, in particular use `%`-encoded values with
    /// [`UriFlags::ENCODED`][crate::UriFlags::ENCODED].
    ///
    /// In contrast to g_uri_build(), this allows specifying the components
    /// of the ‘userinfo’ field separately. Note that @user must be non-[`None`]
    /// if either @password or @auth_params is non-[`None`].
    /// ## `flags`
    /// flags describing how to build the #GUri
    /// ## `scheme`
    /// the URI scheme
    /// ## `user`
    /// the user component of the userinfo, or [`None`]
    /// ## `password`
    /// the password component of the userinfo, or [`None`]
    /// ## `auth_params`
    /// the auth params of the userinfo, or [`None`]
    /// ## `host`
    /// the host component, or [`None`]
    /// ## `port`
    /// the port, or `-1`
    /// ## `path`
    /// the path component
    /// ## `query`
    /// the query component, or [`None`]
    /// ## `fragment`
    /// the fragment, or [`None`]
    ///
    /// # Returns
    ///
    /// a new #GUri
    #[doc(alias = "g_uri_build_with_user")]
    pub fn build_with_user(
        flags: UriFlags,
        scheme: &str,
        user: Option<&str>,
        password: Option<&str>,
        auth_params: Option<&str>,
        host: Option<&str>,
        port: i32,
        path: &str,
        query: Option<&str>,
        fragment: Option<&str>,
    ) -> Uri {
        unsafe {
            from_glib_full(ffi::g_uri_build_with_user(
                flags.into_glib(),
                scheme.to_glib_none().0,
                user.to_glib_none().0,
                password.to_glib_none().0,
                auth_params.to_glib_none().0,
                host.to_glib_none().0,
                port,
                path.to_glib_none().0,
                query.to_glib_none().0,
                fragment.to_glib_none().0,
            ))
        }
    }

    /// Escapes arbitrary data for use in a URI.
    ///
    /// Normally all characters that are not ‘unreserved’ (i.e. ASCII
    /// alphanumerical characters plus dash, dot, underscore and tilde) are
    /// escaped. But if you specify characters in @reserved_chars_allowed
    /// they are not escaped. This is useful for the ‘reserved’ characters
    /// in the URI specification, since those are allowed unescaped in some
    /// portions of a URI.
    ///
    /// Though technically incorrect, this will also allow escaping nul
    /// bytes as `%``00`.
    /// ## `unescaped`
    /// the unescaped input data.
    /// ## `reserved_chars_allowed`
    /// a string of reserved
    ///   characters that are allowed to be used, or [`None`].
    ///
    /// # Returns
    ///
    /// an escaped version of @unescaped.
    ///     The returned string should be freed when no longer needed.
    #[doc(alias = "g_uri_escape_bytes")]
    pub fn escape_bytes(unescaped: &[u8], reserved_chars_allowed: Option<&str>) -> crate::GString {
        let length = unescaped.len() as _;
        unsafe {
            from_glib_full(ffi::g_uri_escape_bytes(
                unescaped.to_glib_none().0,
                length,
                reserved_chars_allowed.to_glib_none().0,
            ))
        }
    }

    /// Escapes a string for use in a URI.
    ///
    /// Normally all characters that are not "unreserved" (i.e. ASCII
    /// alphanumerical characters plus dash, dot, underscore and tilde) are
    /// escaped. But if you specify characters in @reserved_chars_allowed
    /// they are not escaped. This is useful for the "reserved" characters
    /// in the URI specification, since those are allowed unescaped in some
    /// portions of a URI.
    /// ## `unescaped`
    /// the unescaped input string.
    /// ## `reserved_chars_allowed`
    /// a string of reserved
    ///   characters that are allowed to be used, or [`None`].
    /// ## `allow_utf8`
    /// [`true`] if the result can include UTF-8 characters.
    ///
    /// # Returns
    ///
    /// an escaped version of @unescaped. The
    /// returned string should be freed when no longer needed.
    #[doc(alias = "g_uri_escape_string")]
    pub fn escape_string(
        unescaped: &str,
        reserved_chars_allowed: Option<&str>,
        allow_utf8: bool,
    ) -> crate::GString {
        unsafe {
            from_glib_full(ffi::g_uri_escape_string(
                unescaped.to_glib_none().0,
                reserved_chars_allowed.to_glib_none().0,
                allow_utf8.into_glib(),
            ))
        }
    }

    /// Parses @uri_string according to @flags, to determine whether it is a valid
    /// [absolute URI](#relative-and-absolute-uris), i.e. it does not need to be resolved
    /// relative to another URI using g_uri_parse_relative().
    ///
    /// If it’s not a valid URI, an error is returned explaining how it’s invalid.
    ///
    /// See g_uri_split(), and the definition of #GUriFlags, for more
    /// information on the effect of @flags.
    /// ## `uri_string`
    /// a string containing an absolute URI
    /// ## `flags`
    /// flags for parsing @uri_string
    ///
    /// # Returns
    ///
    /// [`true`] if @uri_string is a valid absolute URI, [`false`] on error.
    #[doc(alias = "g_uri_is_valid")]
    pub fn is_valid(uri_string: &str, flags: UriFlags) -> Result<(), crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let is_ok =
                ffi::g_uri_is_valid(uri_string.to_glib_none().0, flags.into_glib(), &mut error);
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Joins the given components together according to @flags to create
    /// an absolute URI string. @path may not be [`None`] (though it may be the empty
    /// string).
    ///
    /// When @host is present, @path must either be empty or begin with a slash (`/`)
    /// character. When @host is not present, @path cannot begin with two slash
    /// characters (`//`). See
    /// [RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
    ///
    /// See also g_uri_join_with_user(), which allows specifying the
    /// components of the ‘userinfo’ separately.
    ///
    /// [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] and [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] are ignored if set
    /// in @flags.
    /// ## `flags`
    /// flags describing how to build the URI string
    /// ## `scheme`
    /// the URI scheme, or [`None`]
    /// ## `userinfo`
    /// the userinfo component, or [`None`]
    /// ## `host`
    /// the host component, or [`None`]
    /// ## `port`
    /// the port, or `-1`
    /// ## `path`
    /// the path component
    /// ## `query`
    /// the query component, or [`None`]
    /// ## `fragment`
    /// the fragment, or [`None`]
    ///
    /// # Returns
    ///
    /// an absolute URI string
    #[doc(alias = "g_uri_join")]
    pub fn join(
        flags: UriFlags,
        scheme: Option<&str>,
        userinfo: Option<&str>,
        host: Option<&str>,
        port: i32,
        path: &str,
        query: Option<&str>,
        fragment: Option<&str>,
    ) -> crate::GString {
        unsafe {
            from_glib_full(ffi::g_uri_join(
                flags.into_glib(),
                scheme.to_glib_none().0,
                userinfo.to_glib_none().0,
                host.to_glib_none().0,
                port,
                path.to_glib_none().0,
                query.to_glib_none().0,
                fragment.to_glib_none().0,
            ))
        }
    }

    /// Joins the given components together according to @flags to create
    /// an absolute URI string. @path may not be [`None`] (though it may be the empty
    /// string).
    ///
    /// In contrast to g_uri_join(), this allows specifying the components
    /// of the ‘userinfo’ separately. It otherwise behaves the same.
    ///
    /// [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] and [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] are ignored if set
    /// in @flags.
    /// ## `flags`
    /// flags describing how to build the URI string
    /// ## `scheme`
    /// the URI scheme, or [`None`]
    /// ## `user`
    /// the user component of the userinfo, or [`None`]
    /// ## `password`
    /// the password component of the userinfo, or
    ///   [`None`]
    /// ## `auth_params`
    /// the auth params of the userinfo, or
    ///   [`None`]
    /// ## `host`
    /// the host component, or [`None`]
    /// ## `port`
    /// the port, or `-1`
    /// ## `path`
    /// the path component
    /// ## `query`
    /// the query component, or [`None`]
    /// ## `fragment`
    /// the fragment, or [`None`]
    ///
    /// # Returns
    ///
    /// an absolute URI string
    #[doc(alias = "g_uri_join_with_user")]
    pub fn join_with_user(
        flags: UriFlags,
        scheme: Option<&str>,
        user: Option<&str>,
        password: Option<&str>,
        auth_params: Option<&str>,
        host: Option<&str>,
        port: i32,
        path: &str,
        query: Option<&str>,
        fragment: Option<&str>,
    ) -> crate::GString {
        unsafe {
            from_glib_full(ffi::g_uri_join_with_user(
                flags.into_glib(),
                scheme.to_glib_none().0,
                user.to_glib_none().0,
                password.to_glib_none().0,
                auth_params.to_glib_none().0,
                host.to_glib_none().0,
                port,
                path.to_glib_none().0,
                query.to_glib_none().0,
                fragment.to_glib_none().0,
            ))
        }
    }

    /// Splits an URI list conforming to the text/uri-list
    /// mime type defined in RFC 2483 into individual URIs,
    /// discarding any comments. The URIs are not validated.
    /// ## `uri_list`
    /// an URI list
    ///
    /// # Returns
    ///
    /// a newly allocated [`None`]-terminated list
    ///   of strings holding the individual URIs. The array should be freed
    ///   with g_strfreev().
    #[doc(alias = "g_uri_list_extract_uris")]
    pub fn list_extract_uris(uri_list: &str) -> Vec<crate::GString> {
        unsafe {
            FromGlibPtrContainer::from_glib_full(ffi::g_uri_list_extract_uris(
                uri_list.to_glib_none().0,
            ))
        }
    }

    /// Parses @uri_string according to @flags. If the result is not a
    /// valid [absolute URI](#relative-and-absolute-uris), it will be discarded, and an
    /// error returned.
    /// ## `uri_string`
    /// a string representing an absolute URI
    /// ## `flags`
    /// flags describing how to parse @uri_string
    ///
    /// # Returns
    ///
    /// a new #GUri, or NULL on error.
    #[doc(alias = "g_uri_parse")]
    pub fn parse(uri_string: &str, flags: UriFlags) -> Result<Uri, crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_uri_parse(uri_string.to_glib_none().0, flags.into_glib(), &mut error);
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    //#[doc(alias = "g_uri_parse_params")]
    //pub fn parse_params(params: &str, separators: &str, flags: UriParamsFlags) -> Result</*Unknown conversion*//*Unimplemented*/HashTable TypeId { ns_id: 0, id: 28 }/TypeId { ns_id: 0, id: 28 }, crate::Error> {
    //    unsafe { TODO: call ffi:g_uri_parse_params() }
    //}

    /// Gets the scheme portion of a URI string.
    /// [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
    /// as:
    ///
    /// ```text
    /// URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
    /// ```
    /// Common schemes include `file`, `https`, `svn+ssh`, etc.
    /// ## `uri`
    /// a valid URI.
    ///
    /// # Returns
    ///
    /// The ‘scheme’ component of the URI, or
    ///     [`None`] on error. The returned string should be freed when no longer needed.
    #[doc(alias = "g_uri_parse_scheme")]
    pub fn parse_scheme(uri: &str) -> Option<crate::GString> {
        unsafe { from_glib_full(ffi::g_uri_parse_scheme(uri.to_glib_none().0)) }
    }

    /// Gets the scheme portion of a URI string.
    /// [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
    /// as:
    ///
    /// ```text
    /// URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
    /// ```
    /// Common schemes include `file`, `https`, `svn+ssh`, etc.
    ///
    /// Unlike g_uri_parse_scheme(), the returned scheme is normalized to
    /// all-lowercase and does not need to be freed.
    /// ## `uri`
    /// a valid URI.
    ///
    /// # Returns
    ///
    /// The ‘scheme’ component of the URI, or
    ///     [`None`] on error. The returned string is normalized to all-lowercase, and
    ///     interned via g_intern_string(), so it does not need to be freed.
    #[doc(alias = "g_uri_peek_scheme")]
    pub fn peek_scheme(uri: &str) -> Option<crate::GString> {
        unsafe { from_glib_none(ffi::g_uri_peek_scheme(uri.to_glib_none().0)) }
    }

    /// Parses @uri_ref according to @flags and, if it is a
    /// [relative URI](#relative-and-absolute-uris), resolves it relative to
    /// @base_uri_string. If the result is not a valid absolute URI, it will be
    /// discarded, and an error returned.
    ///
    /// (If @base_uri_string is [`None`], this just returns @uri_ref, or
    /// [`None`] if @uri_ref is invalid or not absolute.)
    /// ## `base_uri_string`
    /// a string representing a base URI
    /// ## `uri_ref`
    /// a string representing a relative or absolute URI
    /// ## `flags`
    /// flags describing how to parse @uri_ref
    ///
    /// # Returns
    ///
    /// the resolved URI string,
    /// or NULL on error.
    #[doc(alias = "g_uri_resolve_relative")]
    pub fn resolve_relative(
        base_uri_string: Option<&str>,
        uri_ref: &str,
        flags: UriFlags,
    ) -> Result<crate::GString, crate::Error> {
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_uri_resolve_relative(
                base_uri_string.to_glib_none().0,
                uri_ref.to_glib_none().0,
                flags.into_glib(),
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Parses @uri_ref (which can be an
    /// [absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and
    /// returns the pieces. Any component that doesn't appear in @uri_ref will be
    /// returned as [`None`] (but note that all URIs always have a path component,
    /// though it may be the empty string).
    ///
    /// If @flags contains [`UriFlags::ENCODED`][crate::UriFlags::ENCODED], then `%`-encoded characters in
    /// @uri_ref will remain encoded in the output strings. (If not,
    /// then all such characters will be decoded.) Note that decoding will
    /// only work if the URI components are ASCII or UTF-8, so you will
    /// need to use [`UriFlags::ENCODED`][crate::UriFlags::ENCODED] if they are not.
    ///
    /// Note that the [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] and
    /// [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] @flags are ignored by g_uri_split(),
    /// since it always returns only the full userinfo; use
    /// g_uri_split_with_user() if you want it split up.
    /// ## `uri_ref`
    /// a string containing a relative or absolute URI
    /// ## `flags`
    /// flags for parsing @uri_ref
    ///
    /// # Returns
    ///
    /// [`true`] if @uri_ref parsed successfully, [`false`]
    ///   on error.
    ///
    /// ## `scheme`
    /// on return, contains
    ///    the scheme (converted to lowercase), or [`None`]
    ///
    /// ## `userinfo`
    /// on return, contains
    ///    the userinfo, or [`None`]
    ///
    /// ## `host`
    /// on return, contains the
    ///    host, or [`None`]
    ///
    /// ## `port`
    /// on return, contains the
    ///    port, or `-1`
    ///
    /// ## `path`
    /// on return, contains the
    ///    path
    ///
    /// ## `query`
    /// on return, contains the
    ///    query, or [`None`]
    ///
    /// ## `fragment`
    /// on return, contains
    ///    the fragment, or [`None`]
    #[doc(alias = "g_uri_split")]
    pub fn split(
        uri_ref: &str,
        flags: UriFlags,
    ) -> Result<
        (
            Option<crate::GString>,
            Option<crate::GString>,
            Option<crate::GString>,
            i32,
            crate::GString,
            Option<crate::GString>,
            Option<crate::GString>,
        ),
        crate::Error,
    > {
        unsafe {
            let mut scheme = std::ptr::null_mut();
            let mut userinfo = std::ptr::null_mut();
            let mut host = std::ptr::null_mut();
            let mut port = std::mem::MaybeUninit::uninit();
            let mut path = std::ptr::null_mut();
            let mut query = std::ptr::null_mut();
            let mut fragment = std::ptr::null_mut();
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_uri_split(
                uri_ref.to_glib_none().0,
                flags.into_glib(),
                &mut scheme,
                &mut userinfo,
                &mut host,
                port.as_mut_ptr(),
                &mut path,
                &mut query,
                &mut fragment,
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok((
                    from_glib_full(scheme),
                    from_glib_full(userinfo),
                    from_glib_full(host),
                    port.assume_init(),
                    from_glib_full(path),
                    from_glib_full(query),
                    from_glib_full(fragment),
                ))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Parses @uri_string (which must be an [absolute URI](#relative-and-absolute-uris))
    /// according to @flags, and returns the pieces relevant to connecting to a host.
    /// See the documentation for g_uri_split() for more details; this is
    /// mostly a wrapper around that function with simpler arguments.
    /// However, it will return an error if @uri_string is a relative URI,
    /// or does not contain a hostname component.
    /// ## `uri_string`
    /// a string containing an absolute URI
    /// ## `flags`
    /// flags for parsing @uri_string
    ///
    /// # Returns
    ///
    /// [`true`] if @uri_string parsed successfully,
    ///   [`false`] on error.
    ///
    /// ## `scheme`
    /// on return, contains
    ///    the scheme (converted to lowercase), or [`None`]
    ///
    /// ## `host`
    /// on return, contains the
    ///    host, or [`None`]
    ///
    /// ## `port`
    /// on return, contains the
    ///    port, or `-1`
    #[doc(alias = "g_uri_split_network")]
    pub fn split_network(
        uri_string: &str,
        flags: UriFlags,
    ) -> Result<(Option<crate::GString>, Option<crate::GString>, i32), crate::Error> {
        unsafe {
            let mut scheme = std::ptr::null_mut();
            let mut host = std::ptr::null_mut();
            let mut port = std::mem::MaybeUninit::uninit();
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_uri_split_network(
                uri_string.to_glib_none().0,
                flags.into_glib(),
                &mut scheme,
                &mut host,
                port.as_mut_ptr(),
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok((
                    from_glib_full(scheme),
                    from_glib_full(host),
                    port.assume_init(),
                ))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Parses @uri_ref (which can be an
    /// [absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and
    /// returns the pieces. Any component that doesn't appear in @uri_ref will be
    /// returned as [`None`] (but note that all URIs always have a path component,
    /// though it may be the empty string).
    ///
    /// See g_uri_split(), and the definition of #GUriFlags, for more
    /// information on the effect of @flags. Note that @password will only
    /// be parsed out if @flags contains [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD], and
    /// @auth_params will only be parsed out if @flags contains
    /// [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS].
    /// ## `uri_ref`
    /// a string containing a relative or absolute URI
    /// ## `flags`
    /// flags for parsing @uri_ref
    ///
    /// # Returns
    ///
    /// [`true`] if @uri_ref parsed successfully, [`false`]
    ///   on error.
    ///
    /// ## `scheme`
    /// on return, contains
    ///    the scheme (converted to lowercase), or [`None`]
    ///
    /// ## `user`
    /// on return, contains
    ///    the user, or [`None`]
    ///
    /// ## `password`
    /// on return, contains
    ///    the password, or [`None`]
    ///
    /// ## `auth_params`
    /// on return, contains
    ///    the auth_params, or [`None`]
    ///
    /// ## `host`
    /// on return, contains the
    ///    host, or [`None`]
    ///
    /// ## `port`
    /// on return, contains the
    ///    port, or `-1`
    ///
    /// ## `path`
    /// on return, contains the
    ///    path
    ///
    /// ## `query`
    /// on return, contains the
    ///    query, or [`None`]
    ///
    /// ## `fragment`
    /// on return, contains
    ///    the fragment, or [`None`]
    #[doc(alias = "g_uri_split_with_user")]
    pub fn split_with_user(
        uri_ref: &str,
        flags: UriFlags,
    ) -> Result<
        (
            Option<crate::GString>,
            Option<crate::GString>,
            Option<crate::GString>,
            Option<crate::GString>,
            Option<crate::GString>,
            i32,
            crate::GString,
            Option<crate::GString>,
            Option<crate::GString>,
        ),
        crate::Error,
    > {
        unsafe {
            let mut scheme = std::ptr::null_mut();
            let mut user = std::ptr::null_mut();
            let mut password = std::ptr::null_mut();
            let mut auth_params = std::ptr::null_mut();
            let mut host = std::ptr::null_mut();
            let mut port = std::mem::MaybeUninit::uninit();
            let mut path = std::ptr::null_mut();
            let mut query = std::ptr::null_mut();
            let mut fragment = std::ptr::null_mut();
            let mut error = std::ptr::null_mut();
            let is_ok = ffi::g_uri_split_with_user(
                uri_ref.to_glib_none().0,
                flags.into_glib(),
                &mut scheme,
                &mut user,
                &mut password,
                &mut auth_params,
                &mut host,
                port.as_mut_ptr(),
                &mut path,
                &mut query,
                &mut fragment,
                &mut error,
            );
            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok((
                    from_glib_full(scheme),
                    from_glib_full(user),
                    from_glib_full(password),
                    from_glib_full(auth_params),
                    from_glib_full(host),
                    port.assume_init(),
                    from_glib_full(path),
                    from_glib_full(query),
                    from_glib_full(fragment),
                ))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Unescapes a segment of an escaped string as binary data.
    ///
    /// Note that in contrast to g_uri_unescape_string(), this does allow
    /// nul bytes to appear in the output.
    ///
    /// If any of the characters in @illegal_characters appears as an escaped
    /// character in @escaped_string, then that is an error and [`None`] will be
    /// returned. This is useful if you want to avoid for instance having a slash
    /// being expanded in an escaped path element, which might confuse pathname
    /// handling.
    /// ## `escaped_string`
    /// A URI-escaped string
    /// ## `length`
    /// the length (in bytes) of @escaped_string to escape, or `-1` if it
    ///   is nul-terminated.
    /// ## `illegal_characters`
    /// a string of illegal characters
    ///   not to be allowed, or [`None`].
    ///
    /// # Returns
    ///
    /// an unescaped version of @escaped_string
    ///     or [`None`] on error (if decoding failed, using [`UriError::Failed`][crate::UriError::Failed] error
    ///     code). The returned #GBytes should be unreffed when no longer needed.
    #[doc(alias = "g_uri_unescape_bytes")]
    pub fn unescape_bytes(
        escaped_string: &str,
        illegal_characters: Option<&str>,
    ) -> Result<Bytes, crate::Error> {
        let length = escaped_string.len() as _;
        unsafe {
            let mut error = std::ptr::null_mut();
            let ret = ffi::g_uri_unescape_bytes(
                escaped_string.to_glib_none().0,
                length,
                illegal_characters.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Unescapes a segment of an escaped string.
    ///
    /// If any of the characters in @illegal_characters or the NUL
    /// character appears as an escaped character in @escaped_string, then
    /// that is an error and [`None`] will be returned. This is useful if you
    /// want to avoid for instance having a slash being expanded in an
    /// escaped path element, which might confuse pathname handling.
    ///
    /// Note: `NUL` byte is not accepted in the output, in contrast to
    /// g_uri_unescape_bytes().
    /// ## `escaped_string`
    /// A string, may be [`None`]
    /// ## `escaped_string_end`
    /// Pointer to end of @escaped_string,
    ///   may be [`None`]
    /// ## `illegal_characters`
    /// An optional string of illegal
    ///   characters not to be allowed, may be [`None`]
    ///
    /// # Returns
    ///
    /// an unescaped version of @escaped_string,
    /// or [`None`] on error. The returned string should be freed when no longer
    /// needed.  As a special case if [`None`] is given for @escaped_string, this
    /// function will return [`None`].
    #[doc(alias = "g_uri_unescape_segment")]
    pub fn unescape_segment(
        escaped_string: Option<&str>,
        escaped_string_end: Option<&str>,
        illegal_characters: Option<&str>,
    ) -> Option<crate::GString> {
        unsafe {
            from_glib_full(ffi::g_uri_unescape_segment(
                escaped_string.to_glib_none().0,
                escaped_string_end.to_glib_none().0,
                illegal_characters.to_glib_none().0,
            ))
        }
    }

    /// Unescapes a whole escaped string.
    ///
    /// If any of the characters in @illegal_characters or the NUL
    /// character appears as an escaped character in @escaped_string, then
    /// that is an error and [`None`] will be returned. This is useful if you
    /// want to avoid for instance having a slash being expanded in an
    /// escaped path element, which might confuse pathname handling.
    /// ## `escaped_string`
    /// an escaped string to be unescaped.
    /// ## `illegal_characters`
    /// a string of illegal characters
    ///   not to be allowed, or [`None`].
    ///
    /// # Returns
    ///
    /// an unescaped version of @escaped_string.
    /// The returned string should be freed when no longer needed.
    #[doc(alias = "g_uri_unescape_string")]
    pub fn unescape_string(
        escaped_string: &str,
        illegal_characters: Option<&str>,
    ) -> Option<crate::GString> {
        unsafe {
            from_glib_full(ffi::g_uri_unescape_string(
                escaped_string.to_glib_none().0,
                illegal_characters.to_glib_none().0,
            ))
        }
    }
}

impl std::fmt::Display for Uri {
    #[inline]
    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
        f.write_str(&self.to_str())
    }
}

unsafe impl Send for Uri {}
unsafe impl Sync for Uri {}