glib/auto/
uri.rs

1// This file was generated by gir (https://github.com/gtk-rs/gir)
2// from gir-files (https://github.com/gtk-rs/gir-files)
3// DO NOT EDIT
4
5use crate::{ffi, translate::*, Bytes, Error, UriFlags, UriHideFlags};
6
7crate::wrapper! {
8    /// The `GUri` type and related functions can be used to parse URIs into
9    /// their components, and build valid URIs from individual components.
10    ///
11    /// Since `GUri` only represents absolute URIs, all `GUri`s will have a
12    /// URI scheme, so [`scheme()`][Self::scheme()] will always return a non-`NULL`
13    /// answer. Likewise, by definition, all URIs have a path component, so
14    /// [`path()`][Self::path()] will always return a non-`NULL` string (which may
15    /// be empty).
16    ///
17    /// If the URI string has an
18    /// [‘authority’ component](https://tools.ietf.org/html/rfc3986#section-3) (that
19    /// is, if the scheme is followed by `://` rather than just `:`), then the
20    /// `GUri` will contain a hostname, and possibly a port and ‘userinfo’.
21    /// Additionally, depending on how the `GUri` was constructed/parsed (for example,
22    /// using the `G_URI_FLAGS_HAS_PASSWORD` and `G_URI_FLAGS_HAS_AUTH_PARAMS` flags),
23    /// the userinfo may be split out into a username, password, and
24    /// additional authorization-related parameters.
25    ///
26    /// Normally, the components of a `GUri` will have all `%`-encoded
27    /// characters decoded. However, if you construct/parse a `GUri` with
28    /// `G_URI_FLAGS_ENCODED`, then the `%`-encoding will be preserved instead in
29    /// the userinfo, path, and query fields (and in the host field if also
30    /// created with `G_URI_FLAGS_NON_DNS`). In particular, this is necessary if
31    /// the URI may contain binary data or non-UTF-8 text, or if decoding
32    /// the components might change the interpretation of the URI.
33    ///
34    /// For example, with the encoded flag:
35    ///
36    /// **⚠️ The following code is in c ⚠️**
37    ///
38    /// ```c
39    /// g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_ENCODED, &err);
40    /// g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue");
41    /// ```
42    ///
43    /// While the default `%`-decoding behaviour would give:
44    ///
45    /// **⚠️ The following code is in c ⚠️**
46    ///
47    /// ```c
48    /// g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_NONE, &err);
49    /// g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http://host/path?param=value");
50    /// ```
51    ///
52    /// During decoding, if an invalid UTF-8 string is encountered, parsing will fail
53    /// with an error indicating the bad string location:
54    ///
55    /// **⚠️ The following code is in c ⚠️**
56    ///
57    /// ```c
58    /// g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fbad%3D%00alue", G_URI_FLAGS_NONE, &err);
59    /// g_assert_error (err, G_URI_ERROR, G_URI_ERROR_BAD_QUERY);
60    /// ```
61    ///
62    /// You should pass `G_URI_FLAGS_ENCODED` or `G_URI_FLAGS_ENCODED_QUERY` if you
63    /// need to handle that case manually. In particular, if the query string
64    /// contains `=` characters that are `%`-encoded, you should let
65    /// `GLib::Uri::parse_params()` do the decoding once of the query.
66    ///
67    /// `GUri` is immutable once constructed, and can safely be accessed from
68    /// multiple threads. Its reference counting is atomic.
69    ///
70    /// Note that the scope of `GUri` is to help manipulate URIs in various applications,
71    /// following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular,
72    /// it doesn't intend to cover web browser needs, and doesn’t implement the
73    /// [WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to
74    /// help prevent
75    /// [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so
76    /// `GUri` is not suitable for formatting URIs for display to the user for making
77    /// security-sensitive decisions.
78    ///
79    /// ## Relative and absolute URIs
80    ///
81    /// As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the
82    /// hierarchical nature of URIs means that they can either be ‘relative
83    /// references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for
84    /// clarity, ‘URIs’ are referred to in this documentation as
85    /// ‘absolute URIs’ — although
86    /// [in contrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3),
87    /// fragment identifiers are always allowed).
88    ///
89    /// Relative references have one or more components of the URI missing. In
90    /// particular, they have no scheme. Any other component, such as hostname,
91    /// query, etc. may be missing, apart from a path, which has to be specified (but
92    /// may be empty). The path may be relative, starting with `./` rather than `/`.
93    ///
94    /// For example, a valid relative reference is `./path?query`,
95    /// `/?query#fragment` or `//example.com`.
96    ///
97    /// Absolute URIs have a scheme specified. Any other components of the URI which
98    /// are missing are specified as explicitly unset in the URI, rather than being
99    /// resolved relative to a base URI using [`parse_relative()`][Self::parse_relative()].
100    ///
101    /// For example, a valid absolute URI is `file:///home/bob` or
102    /// `https://search.com?query=string`.
103    ///
104    /// A `GUri` instance is always an absolute URI. A string may be an absolute URI
105    /// or a relative reference; see the documentation for individual functions as to
106    /// what forms they accept.
107    ///
108    /// ## Parsing URIs
109    ///
110    /// The most minimalist APIs for parsing URIs are [`split()`][Self::split()] and
111    /// [`split_with_user()`][Self::split_with_user()]. These split a URI into its component
112    /// parts, and return the parts; the difference between the two is that
113    /// [`split()`][Self::split()] treats the ‘userinfo’ component of the URI as a
114    /// single element, while [`split_with_user()`][Self::split_with_user()] can (depending on the
115    /// [`UriFlags`][crate::UriFlags] you pass) treat it as containing a username, password,
116    /// and authentication parameters. Alternatively, [`split_network()`][Self::split_network()]
117    /// can be used when you are only interested in the components that are
118    /// needed to initiate a network connection to the service (scheme,
119    /// host, and port).
120    ///
121    /// [`parse()`][Self::parse()] is similar to [`split()`][Self::split()], but instead of
122    /// returning individual strings, it returns a `GUri` structure (and it requires
123    /// that the URI be an absolute URI).
124    ///
125    /// [`resolve_relative()`][Self::resolve_relative()] and [`parse_relative()`][Self::parse_relative()] allow
126    /// you to resolve a relative URI relative to a base URI.
127    /// [`resolve_relative()`][Self::resolve_relative()] takes two strings and returns a string,
128    /// and [`parse_relative()`][Self::parse_relative()] takes a `GUri` and a string and returns a
129    /// `GUri`.
130    ///
131    /// All of the parsing functions take a [`UriFlags`][crate::UriFlags] argument describing
132    /// exactly how to parse the URI; see the documentation for that type
133    /// for more details on the specific flags that you can pass. If you
134    /// need to choose different flags based on the type of URI, you can
135    /// use [`peek_scheme()`][Self::peek_scheme()] on the URI string to check the scheme
136    /// first, and use that to decide what flags to parse it with.
137    ///
138    /// For example, you might want to use `G_URI_PARAMS_WWW_FORM` when parsing the
139    /// params for a web URI, so compare the result of [`peek_scheme()`][Self::peek_scheme()]
140    /// against `http` and `https`.
141    ///
142    /// ## Building URIs
143    ///
144    /// [`join()`][Self::join()] and [`join_with_user()`][Self::join_with_user()] can be used to construct
145    /// valid URI strings from a set of component strings. They are the
146    /// inverse of [`split()`][Self::split()] and [`split_with_user()`][Self::split_with_user()].
147    ///
148    /// Similarly, [`build()`][Self::build()] and [`build_with_user()`][Self::build_with_user()] can be
149    /// used to construct a `GUri` from a set of component strings.
150    ///
151    /// As with the parsing functions, the building functions take a
152    /// [`UriFlags`][crate::UriFlags] argument. In particular, it is important to keep in mind
153    /// whether the URI components you are using are already `%`-encoded. If so,
154    /// you must pass the `G_URI_FLAGS_ENCODED` flag.
155    ///
156    /// ## `file://` URIs
157    ///
158    /// Note that Windows and Unix both define special rules for parsing
159    /// `file://` URIs (involving non-UTF-8 character sets on Unix, and the
160    /// interpretation of path separators on Windows). `GUri` does not
161    /// implement these rules. Use [`filename_from_uri()`][crate::filename_from_uri()] and
162    /// [`filename_to_uri()`][crate::filename_to_uri()] if you want to properly convert between
163    /// `file://` URIs and local filenames.
164    ///
165    /// ## URI Equality
166    ///
167    /// Note that there is no `g_uri_equal ()` function, because comparing
168    /// URIs usefully requires scheme-specific knowledge that `GUri` does
169    /// not have. `GUri` can help with normalization if you use the various
170    /// encoded [`UriFlags`][crate::UriFlags] as well as `G_URI_FLAGS_SCHEME_NORMALIZE`
171    /// however it is not comprehensive.
172    /// For example, `data:,foo` and `data:;base64,Zm9v` resolve to the same
173    /// thing according to the `data:` URI specification which GLib does not
174    /// handle.
175    // rustdoc-stripper-ignore-next-stop
176    /// The `GUri` type and related functions can be used to parse URIs into
177    /// their components, and build valid URIs from individual components.
178    ///
179    /// Since `GUri` only represents absolute URIs, all `GUri`s will have a
180    /// URI scheme, so [`scheme()`][Self::scheme()] will always return a non-`NULL`
181    /// answer. Likewise, by definition, all URIs have a path component, so
182    /// [`path()`][Self::path()] will always return a non-`NULL` string (which may
183    /// be empty).
184    ///
185    /// If the URI string has an
186    /// [‘authority’ component](https://tools.ietf.org/html/rfc3986#section-3) (that
187    /// is, if the scheme is followed by `://` rather than just `:`), then the
188    /// `GUri` will contain a hostname, and possibly a port and ‘userinfo’.
189    /// Additionally, depending on how the `GUri` was constructed/parsed (for example,
190    /// using the `G_URI_FLAGS_HAS_PASSWORD` and `G_URI_FLAGS_HAS_AUTH_PARAMS` flags),
191    /// the userinfo may be split out into a username, password, and
192    /// additional authorization-related parameters.
193    ///
194    /// Normally, the components of a `GUri` will have all `%`-encoded
195    /// characters decoded. However, if you construct/parse a `GUri` with
196    /// `G_URI_FLAGS_ENCODED`, then the `%`-encoding will be preserved instead in
197    /// the userinfo, path, and query fields (and in the host field if also
198    /// created with `G_URI_FLAGS_NON_DNS`). In particular, this is necessary if
199    /// the URI may contain binary data or non-UTF-8 text, or if decoding
200    /// the components might change the interpretation of the URI.
201    ///
202    /// For example, with the encoded flag:
203    ///
204    /// **⚠️ The following code is in c ⚠️**
205    ///
206    /// ```c
207    /// g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_ENCODED, &err);
208    /// g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue");
209    /// ```
210    ///
211    /// While the default `%`-decoding behaviour would give:
212    ///
213    /// **⚠️ The following code is in c ⚠️**
214    ///
215    /// ```c
216    /// g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fparam%3Dvalue", G_URI_FLAGS_NONE, &err);
217    /// g_assert_cmpstr (g_uri_get_query (uri), ==, "query=http://host/path?param=value");
218    /// ```
219    ///
220    /// During decoding, if an invalid UTF-8 string is encountered, parsing will fail
221    /// with an error indicating the bad string location:
222    ///
223    /// **⚠️ The following code is in c ⚠️**
224    ///
225    /// ```c
226    /// g_autoptr(GUri) uri = g_uri_parse ("http://host/path?query=http%3A%2F%2Fhost%2Fpath%3Fbad%3D%00alue", G_URI_FLAGS_NONE, &err);
227    /// g_assert_error (err, G_URI_ERROR, G_URI_ERROR_BAD_QUERY);
228    /// ```
229    ///
230    /// You should pass `G_URI_FLAGS_ENCODED` or `G_URI_FLAGS_ENCODED_QUERY` if you
231    /// need to handle that case manually. In particular, if the query string
232    /// contains `=` characters that are `%`-encoded, you should let
233    /// `GLib::Uri::parse_params()` do the decoding once of the query.
234    ///
235    /// `GUri` is immutable once constructed, and can safely be accessed from
236    /// multiple threads. Its reference counting is atomic.
237    ///
238    /// Note that the scope of `GUri` is to help manipulate URIs in various applications,
239    /// following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular,
240    /// it doesn't intend to cover web browser needs, and doesn’t implement the
241    /// [WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to
242    /// help prevent
243    /// [homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so
244    /// `GUri` is not suitable for formatting URIs for display to the user for making
245    /// security-sensitive decisions.
246    ///
247    /// ## Relative and absolute URIs
248    ///
249    /// As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the
250    /// hierarchical nature of URIs means that they can either be ‘relative
251    /// references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for
252    /// clarity, ‘URIs’ are referred to in this documentation as
253    /// ‘absolute URIs’ — although
254    /// [in contrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3),
255    /// fragment identifiers are always allowed).
256    ///
257    /// Relative references have one or more components of the URI missing. In
258    /// particular, they have no scheme. Any other component, such as hostname,
259    /// query, etc. may be missing, apart from a path, which has to be specified (but
260    /// may be empty). The path may be relative, starting with `./` rather than `/`.
261    ///
262    /// For example, a valid relative reference is `./path?query`,
263    /// `/?query#fragment` or `//example.com`.
264    ///
265    /// Absolute URIs have a scheme specified. Any other components of the URI which
266    /// are missing are specified as explicitly unset in the URI, rather than being
267    /// resolved relative to a base URI using [`parse_relative()`][Self::parse_relative()].
268    ///
269    /// For example, a valid absolute URI is `file:///home/bob` or
270    /// `https://search.com?query=string`.
271    ///
272    /// A `GUri` instance is always an absolute URI. A string may be an absolute URI
273    /// or a relative reference; see the documentation for individual functions as to
274    /// what forms they accept.
275    ///
276    /// ## Parsing URIs
277    ///
278    /// The most minimalist APIs for parsing URIs are [`split()`][Self::split()] and
279    /// [`split_with_user()`][Self::split_with_user()]. These split a URI into its component
280    /// parts, and return the parts; the difference between the two is that
281    /// [`split()`][Self::split()] treats the ‘userinfo’ component of the URI as a
282    /// single element, while [`split_with_user()`][Self::split_with_user()] can (depending on the
283    /// [`UriFlags`][crate::UriFlags] you pass) treat it as containing a username, password,
284    /// and authentication parameters. Alternatively, [`split_network()`][Self::split_network()]
285    /// can be used when you are only interested in the components that are
286    /// needed to initiate a network connection to the service (scheme,
287    /// host, and port).
288    ///
289    /// [`parse()`][Self::parse()] is similar to [`split()`][Self::split()], but instead of
290    /// returning individual strings, it returns a `GUri` structure (and it requires
291    /// that the URI be an absolute URI).
292    ///
293    /// [`resolve_relative()`][Self::resolve_relative()] and [`parse_relative()`][Self::parse_relative()] allow
294    /// you to resolve a relative URI relative to a base URI.
295    /// [`resolve_relative()`][Self::resolve_relative()] takes two strings and returns a string,
296    /// and [`parse_relative()`][Self::parse_relative()] takes a `GUri` and a string and returns a
297    /// `GUri`.
298    ///
299    /// All of the parsing functions take a [`UriFlags`][crate::UriFlags] argument describing
300    /// exactly how to parse the URI; see the documentation for that type
301    /// for more details on the specific flags that you can pass. If you
302    /// need to choose different flags based on the type of URI, you can
303    /// use [`peek_scheme()`][Self::peek_scheme()] on the URI string to check the scheme
304    /// first, and use that to decide what flags to parse it with.
305    ///
306    /// For example, you might want to use `G_URI_PARAMS_WWW_FORM` when parsing the
307    /// params for a web URI, so compare the result of [`peek_scheme()`][Self::peek_scheme()]
308    /// against `http` and `https`.
309    ///
310    /// ## Building URIs
311    ///
312    /// [`join()`][Self::join()] and [`join_with_user()`][Self::join_with_user()] can be used to construct
313    /// valid URI strings from a set of component strings. They are the
314    /// inverse of [`split()`][Self::split()] and [`split_with_user()`][Self::split_with_user()].
315    ///
316    /// Similarly, [`build()`][Self::build()] and [`build_with_user()`][Self::build_with_user()] can be
317    /// used to construct a `GUri` from a set of component strings.
318    ///
319    /// As with the parsing functions, the building functions take a
320    /// [`UriFlags`][crate::UriFlags] argument. In particular, it is important to keep in mind
321    /// whether the URI components you are using are already `%`-encoded. If so,
322    /// you must pass the `G_URI_FLAGS_ENCODED` flag.
323    ///
324    /// ## `file://` URIs
325    ///
326    /// Note that Windows and Unix both define special rules for parsing
327    /// `file://` URIs (involving non-UTF-8 character sets on Unix, and the
328    /// interpretation of path separators on Windows). `GUri` does not
329    /// implement these rules. Use [`filename_from_uri()`][crate::filename_from_uri()] and
330    /// [`filename_to_uri()`][crate::filename_to_uri()] if you want to properly convert between
331    /// `file://` URIs and local filenames.
332    ///
333    /// ## URI Equality
334    ///
335    /// Note that there is no `g_uri_equal ()` function, because comparing
336    /// URIs usefully requires scheme-specific knowledge that `GUri` does
337    /// not have. `GUri` can help with normalization if you use the various
338    /// encoded [`UriFlags`][crate::UriFlags] as well as `G_URI_FLAGS_SCHEME_NORMALIZE`
339    /// however it is not comprehensive.
340    /// For example, `data:,foo` and `data:;base64,Zm9v` resolve to the same
341    /// thing according to the `data:` URI specification which GLib does not
342    /// handle.
343    #[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
344    pub struct Uri(Shared<ffi::GUri>);
345
346    match fn {
347        ref => |ptr| ffi::g_uri_ref(ptr),
348        unref => |ptr| ffi::g_uri_unref(ptr),
349        type_ => || ffi::g_uri_get_type(),
350    }
351}
352
353impl Uri {
354    /// Gets @self's authentication parameters, which may contain
355    /// `%`-encoding, depending on the flags with which @self was created.
356    /// (If @self was not created with [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] then this will
357    /// be [`None`].)
358    ///
359    /// Depending on the URI scheme, g_uri_parse_params() may be useful for
360    /// further parsing this information.
361    ///
362    /// # Returns
363    ///
364    /// @self's authentication parameters.
365    // rustdoc-stripper-ignore-next-stop
366    /// Gets @self's authentication parameters, which may contain
367    /// `%`-encoding, depending on the flags with which @self was created.
368    /// (If @self was not created with [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] then this will
369    /// be [`None`].)
370    ///
371    /// Depending on the URI scheme, g_uri_parse_params() may be useful for
372    /// further parsing this information.
373    ///
374    /// # Returns
375    ///
376    /// @self's authentication parameters.
377    #[doc(alias = "g_uri_get_auth_params")]
378    #[doc(alias = "get_auth_params")]
379    pub fn auth_params(&self) -> Option<crate::GString> {
380        unsafe { from_glib_none(ffi::g_uri_get_auth_params(self.to_glib_none().0)) }
381    }
382
383    /// Gets @self's flags set upon construction.
384    ///
385    /// # Returns
386    ///
387    /// @self's flags.
388    // rustdoc-stripper-ignore-next-stop
389    /// Gets @self's flags set upon construction.
390    ///
391    /// # Returns
392    ///
393    /// @self's flags.
394    #[doc(alias = "g_uri_get_flags")]
395    #[doc(alias = "get_flags")]
396    pub fn flags(&self) -> UriFlags {
397        unsafe { from_glib(ffi::g_uri_get_flags(self.to_glib_none().0)) }
398    }
399
400    /// Gets @self's fragment, which may contain `%`-encoding, depending on
401    /// the flags with which @self was created.
402    ///
403    /// # Returns
404    ///
405    /// @self's fragment.
406    // rustdoc-stripper-ignore-next-stop
407    /// Gets @self's fragment, which may contain `%`-encoding, depending on
408    /// the flags with which @self was created.
409    ///
410    /// # Returns
411    ///
412    /// @self's fragment.
413    #[doc(alias = "g_uri_get_fragment")]
414    #[doc(alias = "get_fragment")]
415    pub fn fragment(&self) -> Option<crate::GString> {
416        unsafe { from_glib_none(ffi::g_uri_get_fragment(self.to_glib_none().0)) }
417    }
418
419    /// Gets @self's host. This will never have `%`-encoded characters,
420    /// unless it is non-UTF-8 (which can only be the case if @self was
421    /// created with [`UriFlags::NON_DNS`][crate::UriFlags::NON_DNS]).
422    ///
423    /// If @self contained an IPv6 address literal, this value will be just
424    /// that address, without the brackets around it that are necessary in
425    /// the string form of the URI. Note that in this case there may also
426    /// be a scope ID attached to the address. Eg, `fe80::1234%``em1` (or
427    /// `fe80::1234%``25em1` if the string is still encoded).
428    ///
429    /// # Returns
430    ///
431    /// @self's host.
432    // rustdoc-stripper-ignore-next-stop
433    /// Gets @self's host. This will never have `%`-encoded characters,
434    /// unless it is non-UTF-8 (which can only be the case if @self was
435    /// created with [`UriFlags::NON_DNS`][crate::UriFlags::NON_DNS]).
436    ///
437    /// If @self contained an IPv6 address literal, this value will be just
438    /// that address, without the brackets around it that are necessary in
439    /// the string form of the URI. Note that in this case there may also
440    /// be a scope ID attached to the address. Eg, `fe80::1234%``em1` (or
441    /// `fe80::1234%``25em1` if the string is still encoded).
442    ///
443    /// # Returns
444    ///
445    /// @self's host.
446    #[doc(alias = "g_uri_get_host")]
447    #[doc(alias = "get_host")]
448    pub fn host(&self) -> Option<crate::GString> {
449        unsafe { from_glib_none(ffi::g_uri_get_host(self.to_glib_none().0)) }
450    }
451
452    /// Gets @self's password, which may contain `%`-encoding, depending on
453    /// the flags with which @self was created. (If @self was not created
454    /// with [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] then this will be [`None`].)
455    ///
456    /// # Returns
457    ///
458    /// @self's password.
459    // rustdoc-stripper-ignore-next-stop
460    /// Gets @self's password, which may contain `%`-encoding, depending on
461    /// the flags with which @self was created. (If @self was not created
462    /// with [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] then this will be [`None`].)
463    ///
464    /// # Returns
465    ///
466    /// @self's password.
467    #[doc(alias = "g_uri_get_password")]
468    #[doc(alias = "get_password")]
469    pub fn password(&self) -> Option<crate::GString> {
470        unsafe { from_glib_none(ffi::g_uri_get_password(self.to_glib_none().0)) }
471    }
472
473    /// Gets @self's path, which may contain `%`-encoding, depending on the
474    /// flags with which @self was created.
475    ///
476    /// # Returns
477    ///
478    /// @self's path.
479    // rustdoc-stripper-ignore-next-stop
480    /// Gets @self's path, which may contain `%`-encoding, depending on the
481    /// flags with which @self was created.
482    ///
483    /// # Returns
484    ///
485    /// @self's path.
486    #[doc(alias = "g_uri_get_path")]
487    #[doc(alias = "get_path")]
488    pub fn path(&self) -> crate::GString {
489        unsafe { from_glib_none(ffi::g_uri_get_path(self.to_glib_none().0)) }
490    }
491
492    /// Gets @self's port.
493    ///
494    /// # Returns
495    ///
496    /// @self's port, or `-1` if no port was specified.
497    // rustdoc-stripper-ignore-next-stop
498    /// Gets @self's port.
499    ///
500    /// # Returns
501    ///
502    /// @self's port, or `-1` if no port was specified.
503    #[doc(alias = "g_uri_get_port")]
504    #[doc(alias = "get_port")]
505    pub fn port(&self) -> i32 {
506        unsafe { ffi::g_uri_get_port(self.to_glib_none().0) }
507    }
508
509    /// Gets @self's query, which may contain `%`-encoding, depending on the
510    /// flags with which @self was created.
511    ///
512    /// For queries consisting of a series of `name=value` parameters,
513    /// #GUriParamsIter or g_uri_parse_params() may be useful.
514    ///
515    /// # Returns
516    ///
517    /// @self's query.
518    // rustdoc-stripper-ignore-next-stop
519    /// Gets @self's query, which may contain `%`-encoding, depending on the
520    /// flags with which @self was created.
521    ///
522    /// For queries consisting of a series of `name=value` parameters,
523    /// #GUriParamsIter or g_uri_parse_params() may be useful.
524    ///
525    /// # Returns
526    ///
527    /// @self's query.
528    #[doc(alias = "g_uri_get_query")]
529    #[doc(alias = "get_query")]
530    pub fn query(&self) -> Option<crate::GString> {
531        unsafe { from_glib_none(ffi::g_uri_get_query(self.to_glib_none().0)) }
532    }
533
534    /// Gets @self's scheme. Note that this will always be all-lowercase,
535    /// regardless of the string or strings that @self was created from.
536    ///
537    /// # Returns
538    ///
539    /// @self's scheme.
540    // rustdoc-stripper-ignore-next-stop
541    /// Gets @self's scheme. Note that this will always be all-lowercase,
542    /// regardless of the string or strings that @self was created from.
543    ///
544    /// # Returns
545    ///
546    /// @self's scheme.
547    #[doc(alias = "g_uri_get_scheme")]
548    #[doc(alias = "get_scheme")]
549    pub fn scheme(&self) -> crate::GString {
550        unsafe { from_glib_none(ffi::g_uri_get_scheme(self.to_glib_none().0)) }
551    }
552
553    /// Gets the ‘username’ component of @self's userinfo, which may contain
554    /// `%`-encoding, depending on the flags with which @self was created.
555    /// If @self was not created with [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] or
556    /// [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS], this is the same as g_uri_get_userinfo().
557    ///
558    /// # Returns
559    ///
560    /// @self's user.
561    // rustdoc-stripper-ignore-next-stop
562    /// Gets the ‘username’ component of @self's userinfo, which may contain
563    /// `%`-encoding, depending on the flags with which @self was created.
564    /// If @self was not created with [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] or
565    /// [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS], this is the same as g_uri_get_userinfo().
566    ///
567    /// # Returns
568    ///
569    /// @self's user.
570    #[doc(alias = "g_uri_get_user")]
571    #[doc(alias = "get_user")]
572    pub fn user(&self) -> Option<crate::GString> {
573        unsafe { from_glib_none(ffi::g_uri_get_user(self.to_glib_none().0)) }
574    }
575
576    /// Gets @self's userinfo, which may contain `%`-encoding, depending on
577    /// the flags with which @self was created.
578    ///
579    /// # Returns
580    ///
581    /// @self's userinfo.
582    // rustdoc-stripper-ignore-next-stop
583    /// Gets @self's userinfo, which may contain `%`-encoding, depending on
584    /// the flags with which @self was created.
585    ///
586    /// # Returns
587    ///
588    /// @self's userinfo.
589    #[doc(alias = "g_uri_get_userinfo")]
590    #[doc(alias = "get_userinfo")]
591    pub fn userinfo(&self) -> Option<crate::GString> {
592        unsafe { from_glib_none(ffi::g_uri_get_userinfo(self.to_glib_none().0)) }
593    }
594
595    /// Parses @uri_ref according to @flags and, if it is a
596    /// [relative URI](#relative-and-absolute-uris), resolves it relative to @self.
597    /// If the result is not a valid absolute URI, it will be discarded, and an error
598    /// returned.
599    /// ## `uri_ref`
600    /// a string representing a relative or absolute URI
601    /// ## `flags`
602    /// flags describing how to parse @uri_ref
603    ///
604    /// # Returns
605    ///
606    /// a new #GUri, or NULL on error.
607    // rustdoc-stripper-ignore-next-stop
608    /// Parses @uri_ref according to @flags and, if it is a
609    /// [relative URI](#relative-and-absolute-uris), resolves it relative to @self.
610    /// If the result is not a valid absolute URI, it will be discarded, and an error
611    /// returned.
612    /// ## `uri_ref`
613    /// a string representing a relative or absolute URI
614    /// ## `flags`
615    /// flags describing how to parse @uri_ref
616    ///
617    /// # Returns
618    ///
619    /// a new #GUri, or NULL on error.
620    #[doc(alias = "g_uri_parse_relative")]
621    pub fn parse_relative(&self, uri_ref: &str, flags: UriFlags) -> Result<Uri, crate::Error> {
622        unsafe {
623            let mut error = std::ptr::null_mut();
624            let ret = ffi::g_uri_parse_relative(
625                self.to_glib_none().0,
626                uri_ref.to_glib_none().0,
627                flags.into_glib(),
628                &mut error,
629            );
630            if error.is_null() {
631                Ok(from_glib_full(ret))
632            } else {
633                Err(from_glib_full(error))
634            }
635        }
636    }
637
638    /// Returns a string representing @self.
639    ///
640    /// This is not guaranteed to return a string which is identical to the
641    /// string that @self was parsed from. However, if the source URI was
642    /// syntactically correct (according to RFC 3986), and it was parsed
643    /// with [`UriFlags::ENCODED`][crate::UriFlags::ENCODED], then g_uri_to_string() is guaranteed to return
644    /// a string which is at least semantically equivalent to the source
645    /// URI (according to RFC 3986).
646    ///
647    /// If @self might contain sensitive details, such as authentication parameters,
648    /// or private data in its query string, and the returned string is going to be
649    /// logged, then consider using g_uri_to_string_partial() to redact parts.
650    ///
651    /// # Returns
652    ///
653    /// a string representing @self,
654    ///     which the caller must free.
655    // rustdoc-stripper-ignore-next-stop
656    /// Returns a string representing @self.
657    ///
658    /// This is not guaranteed to return a string which is identical to the
659    /// string that @self was parsed from. However, if the source URI was
660    /// syntactically correct (according to RFC 3986), and it was parsed
661    /// with [`UriFlags::ENCODED`][crate::UriFlags::ENCODED], then g_uri_to_string() is guaranteed to return
662    /// a string which is at least semantically equivalent to the source
663    /// URI (according to RFC 3986).
664    ///
665    /// If @self might contain sensitive details, such as authentication parameters,
666    /// or private data in its query string, and the returned string is going to be
667    /// logged, then consider using g_uri_to_string_partial() to redact parts.
668    ///
669    /// # Returns
670    ///
671    /// a string representing @self,
672    ///     which the caller must free.
673    #[doc(alias = "g_uri_to_string")]
674    #[doc(alias = "to_string")]
675    pub fn to_str(&self) -> crate::GString {
676        unsafe { from_glib_full(ffi::g_uri_to_string(self.to_glib_none().0)) }
677    }
678
679    /// Returns a string representing @self, subject to the options in
680    /// @flags. See g_uri_to_string() and #GUriHideFlags for more details.
681    /// ## `flags`
682    /// flags describing what parts of @self to hide
683    ///
684    /// # Returns
685    ///
686    /// a string representing
687    ///     @self, which the caller must free.
688    // rustdoc-stripper-ignore-next-stop
689    /// Returns a string representing @self, subject to the options in
690    /// @flags. See g_uri_to_string() and #GUriHideFlags for more details.
691    /// ## `flags`
692    /// flags describing what parts of @self to hide
693    ///
694    /// # Returns
695    ///
696    /// a string representing
697    ///     @self, which the caller must free.
698    #[doc(alias = "g_uri_to_string_partial")]
699    pub fn to_string_partial(&self, flags: UriHideFlags) -> crate::GString {
700        unsafe {
701            from_glib_full(ffi::g_uri_to_string_partial(
702                self.to_glib_none().0,
703                flags.into_glib(),
704            ))
705        }
706    }
707
708    /// Creates a new #GUri from the given components according to @flags.
709    ///
710    /// See also g_uri_build_with_user(), which allows specifying the
711    /// components of the "userinfo" separately.
712    /// ## `flags`
713    /// flags describing how to build the #GUri
714    /// ## `scheme`
715    /// the URI scheme
716    /// ## `userinfo`
717    /// the userinfo component, or [`None`]
718    /// ## `host`
719    /// the host component, or [`None`]
720    /// ## `port`
721    /// the port, or `-1`
722    /// ## `path`
723    /// the path component
724    /// ## `query`
725    /// the query component, or [`None`]
726    /// ## `fragment`
727    /// the fragment, or [`None`]
728    ///
729    /// # Returns
730    ///
731    /// a new #GUri
732    // rustdoc-stripper-ignore-next-stop
733    /// Creates a new #GUri from the given components according to @flags.
734    ///
735    /// See also g_uri_build_with_user(), which allows specifying the
736    /// components of the "userinfo" separately.
737    /// ## `flags`
738    /// flags describing how to build the #GUri
739    /// ## `scheme`
740    /// the URI scheme
741    /// ## `userinfo`
742    /// the userinfo component, or [`None`]
743    /// ## `host`
744    /// the host component, or [`None`]
745    /// ## `port`
746    /// the port, or `-1`
747    /// ## `path`
748    /// the path component
749    /// ## `query`
750    /// the query component, or [`None`]
751    /// ## `fragment`
752    /// the fragment, or [`None`]
753    ///
754    /// # Returns
755    ///
756    /// a new #GUri
757    #[doc(alias = "g_uri_build")]
758    pub fn build(
759        flags: UriFlags,
760        scheme: &str,
761        userinfo: Option<&str>,
762        host: Option<&str>,
763        port: i32,
764        path: &str,
765        query: Option<&str>,
766        fragment: Option<&str>,
767    ) -> Uri {
768        unsafe {
769            from_glib_full(ffi::g_uri_build(
770                flags.into_glib(),
771                scheme.to_glib_none().0,
772                userinfo.to_glib_none().0,
773                host.to_glib_none().0,
774                port,
775                path.to_glib_none().0,
776                query.to_glib_none().0,
777                fragment.to_glib_none().0,
778            ))
779        }
780    }
781
782    /// Creates a new #GUri from the given components according to @flags
783    /// ([`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] is added unconditionally). The @flags must be
784    /// coherent with the passed values, in particular use `%`-encoded values with
785    /// [`UriFlags::ENCODED`][crate::UriFlags::ENCODED].
786    ///
787    /// In contrast to g_uri_build(), this allows specifying the components
788    /// of the ‘userinfo’ field separately. Note that @user must be non-[`None`]
789    /// if either @password or @auth_params is non-[`None`].
790    /// ## `flags`
791    /// flags describing how to build the #GUri
792    /// ## `scheme`
793    /// the URI scheme
794    /// ## `user`
795    /// the user component of the userinfo, or [`None`]
796    /// ## `password`
797    /// the password component of the userinfo, or [`None`]
798    /// ## `auth_params`
799    /// the auth params of the userinfo, or [`None`]
800    /// ## `host`
801    /// the host component, or [`None`]
802    /// ## `port`
803    /// the port, or `-1`
804    /// ## `path`
805    /// the path component
806    /// ## `query`
807    /// the query component, or [`None`]
808    /// ## `fragment`
809    /// the fragment, or [`None`]
810    ///
811    /// # Returns
812    ///
813    /// a new #GUri
814    // rustdoc-stripper-ignore-next-stop
815    /// Creates a new #GUri from the given components according to @flags
816    /// ([`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] is added unconditionally). The @flags must be
817    /// coherent with the passed values, in particular use `%`-encoded values with
818    /// [`UriFlags::ENCODED`][crate::UriFlags::ENCODED].
819    ///
820    /// In contrast to g_uri_build(), this allows specifying the components
821    /// of the ‘userinfo’ field separately. Note that @user must be non-[`None`]
822    /// if either @password or @auth_params is non-[`None`].
823    /// ## `flags`
824    /// flags describing how to build the #GUri
825    /// ## `scheme`
826    /// the URI scheme
827    /// ## `user`
828    /// the user component of the userinfo, or [`None`]
829    /// ## `password`
830    /// the password component of the userinfo, or [`None`]
831    /// ## `auth_params`
832    /// the auth params of the userinfo, or [`None`]
833    /// ## `host`
834    /// the host component, or [`None`]
835    /// ## `port`
836    /// the port, or `-1`
837    /// ## `path`
838    /// the path component
839    /// ## `query`
840    /// the query component, or [`None`]
841    /// ## `fragment`
842    /// the fragment, or [`None`]
843    ///
844    /// # Returns
845    ///
846    /// a new #GUri
847    #[doc(alias = "g_uri_build_with_user")]
848    pub fn build_with_user(
849        flags: UriFlags,
850        scheme: &str,
851        user: Option<&str>,
852        password: Option<&str>,
853        auth_params: Option<&str>,
854        host: Option<&str>,
855        port: i32,
856        path: &str,
857        query: Option<&str>,
858        fragment: Option<&str>,
859    ) -> Uri {
860        unsafe {
861            from_glib_full(ffi::g_uri_build_with_user(
862                flags.into_glib(),
863                scheme.to_glib_none().0,
864                user.to_glib_none().0,
865                password.to_glib_none().0,
866                auth_params.to_glib_none().0,
867                host.to_glib_none().0,
868                port,
869                path.to_glib_none().0,
870                query.to_glib_none().0,
871                fragment.to_glib_none().0,
872            ))
873        }
874    }
875
876    /// Escapes arbitrary data for use in a URI.
877    ///
878    /// Normally all characters that are not ‘unreserved’ (i.e. ASCII
879    /// alphanumerical characters plus dash, dot, underscore and tilde) are
880    /// escaped. But if you specify characters in @reserved_chars_allowed
881    /// they are not escaped. This is useful for the ‘reserved’ characters
882    /// in the URI specification, since those are allowed unescaped in some
883    /// portions of a URI.
884    ///
885    /// Though technically incorrect, this will also allow escaping nul
886    /// bytes as `%``00`.
887    /// ## `unescaped`
888    /// the unescaped input data.
889    /// ## `reserved_chars_allowed`
890    /// a string of reserved
891    ///   characters that are allowed to be used, or [`None`].
892    ///
893    /// # Returns
894    ///
895    /// an escaped version of @unescaped.
896    ///     The returned string should be freed when no longer needed.
897    // rustdoc-stripper-ignore-next-stop
898    /// Escapes arbitrary data for use in a URI.
899    ///
900    /// Normally all characters that are not ‘unreserved’ (i.e. ASCII
901    /// alphanumerical characters plus dash, dot, underscore and tilde) are
902    /// escaped. But if you specify characters in @reserved_chars_allowed
903    /// they are not escaped. This is useful for the ‘reserved’ characters
904    /// in the URI specification, since those are allowed unescaped in some
905    /// portions of a URI.
906    ///
907    /// Though technically incorrect, this will also allow escaping nul
908    /// bytes as `%``00`.
909    /// ## `unescaped`
910    /// the unescaped input data.
911    /// ## `reserved_chars_allowed`
912    /// a string of reserved
913    ///   characters that are allowed to be used, or [`None`].
914    ///
915    /// # Returns
916    ///
917    /// an escaped version of @unescaped.
918    ///     The returned string should be freed when no longer needed.
919    #[doc(alias = "g_uri_escape_bytes")]
920    pub fn escape_bytes(unescaped: &[u8], reserved_chars_allowed: Option<&str>) -> crate::GString {
921        let length = unescaped.len() as _;
922        unsafe {
923            from_glib_full(ffi::g_uri_escape_bytes(
924                unescaped.to_glib_none().0,
925                length,
926                reserved_chars_allowed.to_glib_none().0,
927            ))
928        }
929    }
930
931    /// Escapes a string for use in a URI.
932    ///
933    /// Normally all characters that are not "unreserved" (i.e. ASCII
934    /// alphanumerical characters plus dash, dot, underscore and tilde) are
935    /// escaped. But if you specify characters in @reserved_chars_allowed
936    /// they are not escaped. This is useful for the "reserved" characters
937    /// in the URI specification, since those are allowed unescaped in some
938    /// portions of a URI.
939    /// ## `unescaped`
940    /// the unescaped input string.
941    /// ## `reserved_chars_allowed`
942    /// a string of reserved
943    ///   characters that are allowed to be used, or [`None`].
944    /// ## `allow_utf8`
945    /// [`true`] if the result can include UTF-8 characters.
946    ///
947    /// # Returns
948    ///
949    /// an escaped version of @unescaped. The
950    /// returned string should be freed when no longer needed.
951    // rustdoc-stripper-ignore-next-stop
952    /// Escapes a string for use in a URI.
953    ///
954    /// Normally all characters that are not "unreserved" (i.e. ASCII
955    /// alphanumerical characters plus dash, dot, underscore and tilde) are
956    /// escaped. But if you specify characters in @reserved_chars_allowed
957    /// they are not escaped. This is useful for the "reserved" characters
958    /// in the URI specification, since those are allowed unescaped in some
959    /// portions of a URI.
960    /// ## `unescaped`
961    /// the unescaped input string.
962    /// ## `reserved_chars_allowed`
963    /// a string of reserved
964    ///   characters that are allowed to be used, or [`None`].
965    /// ## `allow_utf8`
966    /// [`true`] if the result can include UTF-8 characters.
967    ///
968    /// # Returns
969    ///
970    /// an escaped version of @unescaped. The
971    /// returned string should be freed when no longer needed.
972    #[doc(alias = "g_uri_escape_string")]
973    pub fn escape_string(
974        unescaped: &str,
975        reserved_chars_allowed: Option<&str>,
976        allow_utf8: bool,
977    ) -> crate::GString {
978        unsafe {
979            from_glib_full(ffi::g_uri_escape_string(
980                unescaped.to_glib_none().0,
981                reserved_chars_allowed.to_glib_none().0,
982                allow_utf8.into_glib(),
983            ))
984        }
985    }
986
987    /// Parses @uri_string according to @flags, to determine whether it is a valid
988    /// [absolute URI](#relative-and-absolute-uris), i.e. it does not need to be resolved
989    /// relative to another URI using g_uri_parse_relative().
990    ///
991    /// If it’s not a valid URI, an error is returned explaining how it’s invalid.
992    ///
993    /// See g_uri_split(), and the definition of #GUriFlags, for more
994    /// information on the effect of @flags.
995    /// ## `uri_string`
996    /// a string containing an absolute URI
997    /// ## `flags`
998    /// flags for parsing @uri_string
999    ///
1000    /// # Returns
1001    ///
1002    /// [`true`] if @uri_string is a valid absolute URI, [`false`] on error.
1003    // rustdoc-stripper-ignore-next-stop
1004    /// Parses @uri_string according to @flags, to determine whether it is a valid
1005    /// [absolute URI](#relative-and-absolute-uris), i.e. it does not need to be resolved
1006    /// relative to another URI using g_uri_parse_relative().
1007    ///
1008    /// If it’s not a valid URI, an error is returned explaining how it’s invalid.
1009    ///
1010    /// See g_uri_split(), and the definition of #GUriFlags, for more
1011    /// information on the effect of @flags.
1012    /// ## `uri_string`
1013    /// a string containing an absolute URI
1014    /// ## `flags`
1015    /// flags for parsing @uri_string
1016    ///
1017    /// # Returns
1018    ///
1019    /// [`true`] if @uri_string is a valid absolute URI, [`false`] on error.
1020    #[doc(alias = "g_uri_is_valid")]
1021    pub fn is_valid(uri_string: &str, flags: UriFlags) -> Result<(), crate::Error> {
1022        unsafe {
1023            let mut error = std::ptr::null_mut();
1024            let is_ok =
1025                ffi::g_uri_is_valid(uri_string.to_glib_none().0, flags.into_glib(), &mut error);
1026            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
1027            if error.is_null() {
1028                Ok(())
1029            } else {
1030                Err(from_glib_full(error))
1031            }
1032        }
1033    }
1034
1035    /// Joins the given components together according to @flags to create
1036    /// an absolute URI string. @path may not be [`None`] (though it may be the empty
1037    /// string).
1038    ///
1039    /// When @host is present, @path must either be empty or begin with a slash (`/`)
1040    /// character. When @host is not present, @path cannot begin with two slash
1041    /// characters (`//`). See
1042    /// [RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
1043    ///
1044    /// See also g_uri_join_with_user(), which allows specifying the
1045    /// components of the ‘userinfo’ separately.
1046    ///
1047    /// [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] and [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] are ignored if set
1048    /// in @flags.
1049    /// ## `flags`
1050    /// flags describing how to build the URI string
1051    /// ## `scheme`
1052    /// the URI scheme, or [`None`]
1053    /// ## `userinfo`
1054    /// the userinfo component, or [`None`]
1055    /// ## `host`
1056    /// the host component, or [`None`]
1057    /// ## `port`
1058    /// the port, or `-1`
1059    /// ## `path`
1060    /// the path component
1061    /// ## `query`
1062    /// the query component, or [`None`]
1063    /// ## `fragment`
1064    /// the fragment, or [`None`]
1065    ///
1066    /// # Returns
1067    ///
1068    /// an absolute URI string
1069    // rustdoc-stripper-ignore-next-stop
1070    /// Joins the given components together according to @flags to create
1071    /// an absolute URI string. @path may not be [`None`] (though it may be the empty
1072    /// string).
1073    ///
1074    /// When @host is present, @path must either be empty or begin with a slash (`/`)
1075    /// character. When @host is not present, @path cannot begin with two slash
1076    /// characters (`//`). See
1077    /// [RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
1078    ///
1079    /// See also g_uri_join_with_user(), which allows specifying the
1080    /// components of the ‘userinfo’ separately.
1081    ///
1082    /// [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] and [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] are ignored if set
1083    /// in @flags.
1084    /// ## `flags`
1085    /// flags describing how to build the URI string
1086    /// ## `scheme`
1087    /// the URI scheme, or [`None`]
1088    /// ## `userinfo`
1089    /// the userinfo component, or [`None`]
1090    /// ## `host`
1091    /// the host component, or [`None`]
1092    /// ## `port`
1093    /// the port, or `-1`
1094    /// ## `path`
1095    /// the path component
1096    /// ## `query`
1097    /// the query component, or [`None`]
1098    /// ## `fragment`
1099    /// the fragment, or [`None`]
1100    ///
1101    /// # Returns
1102    ///
1103    /// an absolute URI string
1104    #[doc(alias = "g_uri_join")]
1105    pub fn join(
1106        flags: UriFlags,
1107        scheme: Option<&str>,
1108        userinfo: Option<&str>,
1109        host: Option<&str>,
1110        port: i32,
1111        path: &str,
1112        query: Option<&str>,
1113        fragment: Option<&str>,
1114    ) -> crate::GString {
1115        unsafe {
1116            from_glib_full(ffi::g_uri_join(
1117                flags.into_glib(),
1118                scheme.to_glib_none().0,
1119                userinfo.to_glib_none().0,
1120                host.to_glib_none().0,
1121                port,
1122                path.to_glib_none().0,
1123                query.to_glib_none().0,
1124                fragment.to_glib_none().0,
1125            ))
1126        }
1127    }
1128
1129    /// Joins the given components together according to @flags to create
1130    /// an absolute URI string. @path may not be [`None`] (though it may be the empty
1131    /// string).
1132    ///
1133    /// In contrast to g_uri_join(), this allows specifying the components
1134    /// of the ‘userinfo’ separately. It otherwise behaves the same.
1135    ///
1136    /// [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] and [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] are ignored if set
1137    /// in @flags.
1138    /// ## `flags`
1139    /// flags describing how to build the URI string
1140    /// ## `scheme`
1141    /// the URI scheme, or [`None`]
1142    /// ## `user`
1143    /// the user component of the userinfo, or [`None`]
1144    /// ## `password`
1145    /// the password component of the userinfo, or
1146    ///   [`None`]
1147    /// ## `auth_params`
1148    /// the auth params of the userinfo, or
1149    ///   [`None`]
1150    /// ## `host`
1151    /// the host component, or [`None`]
1152    /// ## `port`
1153    /// the port, or `-1`
1154    /// ## `path`
1155    /// the path component
1156    /// ## `query`
1157    /// the query component, or [`None`]
1158    /// ## `fragment`
1159    /// the fragment, or [`None`]
1160    ///
1161    /// # Returns
1162    ///
1163    /// an absolute URI string
1164    // rustdoc-stripper-ignore-next-stop
1165    /// Joins the given components together according to @flags to create
1166    /// an absolute URI string. @path may not be [`None`] (though it may be the empty
1167    /// string).
1168    ///
1169    /// In contrast to g_uri_join(), this allows specifying the components
1170    /// of the ‘userinfo’ separately. It otherwise behaves the same.
1171    ///
1172    /// [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] and [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] are ignored if set
1173    /// in @flags.
1174    /// ## `flags`
1175    /// flags describing how to build the URI string
1176    /// ## `scheme`
1177    /// the URI scheme, or [`None`]
1178    /// ## `user`
1179    /// the user component of the userinfo, or [`None`]
1180    /// ## `password`
1181    /// the password component of the userinfo, or
1182    ///   [`None`]
1183    /// ## `auth_params`
1184    /// the auth params of the userinfo, or
1185    ///   [`None`]
1186    /// ## `host`
1187    /// the host component, or [`None`]
1188    /// ## `port`
1189    /// the port, or `-1`
1190    /// ## `path`
1191    /// the path component
1192    /// ## `query`
1193    /// the query component, or [`None`]
1194    /// ## `fragment`
1195    /// the fragment, or [`None`]
1196    ///
1197    /// # Returns
1198    ///
1199    /// an absolute URI string
1200    #[doc(alias = "g_uri_join_with_user")]
1201    pub fn join_with_user(
1202        flags: UriFlags,
1203        scheme: Option<&str>,
1204        user: Option<&str>,
1205        password: Option<&str>,
1206        auth_params: Option<&str>,
1207        host: Option<&str>,
1208        port: i32,
1209        path: &str,
1210        query: Option<&str>,
1211        fragment: Option<&str>,
1212    ) -> crate::GString {
1213        unsafe {
1214            from_glib_full(ffi::g_uri_join_with_user(
1215                flags.into_glib(),
1216                scheme.to_glib_none().0,
1217                user.to_glib_none().0,
1218                password.to_glib_none().0,
1219                auth_params.to_glib_none().0,
1220                host.to_glib_none().0,
1221                port,
1222                path.to_glib_none().0,
1223                query.to_glib_none().0,
1224                fragment.to_glib_none().0,
1225            ))
1226        }
1227    }
1228
1229    /// Splits an URI list conforming to the text/uri-list
1230    /// mime type defined in RFC 2483 into individual URIs,
1231    /// discarding any comments. The URIs are not validated.
1232    /// ## `uri_list`
1233    /// an URI list
1234    ///
1235    /// # Returns
1236    ///
1237    /// a newly allocated [`None`]-terminated list
1238    ///   of strings holding the individual URIs. The array should be freed
1239    ///   with g_strfreev().
1240    // rustdoc-stripper-ignore-next-stop
1241    /// Splits an URI list conforming to the text/uri-list
1242    /// mime type defined in RFC 2483 into individual URIs,
1243    /// discarding any comments. The URIs are not validated.
1244    /// ## `uri_list`
1245    /// an URI list
1246    ///
1247    /// # Returns
1248    ///
1249    /// a newly allocated [`None`]-terminated list
1250    ///   of strings holding the individual URIs. The array should be freed
1251    ///   with g_strfreev().
1252    #[doc(alias = "g_uri_list_extract_uris")]
1253    pub fn list_extract_uris(uri_list: &str) -> Vec<crate::GString> {
1254        unsafe {
1255            FromGlibPtrContainer::from_glib_full(ffi::g_uri_list_extract_uris(
1256                uri_list.to_glib_none().0,
1257            ))
1258        }
1259    }
1260
1261    /// Parses @uri_string according to @flags. If the result is not a
1262    /// valid [absolute URI](#relative-and-absolute-uris), it will be discarded, and an
1263    /// error returned.
1264    /// ## `uri_string`
1265    /// a string representing an absolute URI
1266    /// ## `flags`
1267    /// flags describing how to parse @uri_string
1268    ///
1269    /// # Returns
1270    ///
1271    /// a new #GUri, or NULL on error.
1272    // rustdoc-stripper-ignore-next-stop
1273    /// Parses @uri_string according to @flags. If the result is not a
1274    /// valid [absolute URI](#relative-and-absolute-uris), it will be discarded, and an
1275    /// error returned.
1276    /// ## `uri_string`
1277    /// a string representing an absolute URI
1278    /// ## `flags`
1279    /// flags describing how to parse @uri_string
1280    ///
1281    /// # Returns
1282    ///
1283    /// a new #GUri, or NULL on error.
1284    #[doc(alias = "g_uri_parse")]
1285    pub fn parse(uri_string: &str, flags: UriFlags) -> Result<Uri, crate::Error> {
1286        unsafe {
1287            let mut error = std::ptr::null_mut();
1288            let ret = ffi::g_uri_parse(uri_string.to_glib_none().0, flags.into_glib(), &mut error);
1289            if error.is_null() {
1290                Ok(from_glib_full(ret))
1291            } else {
1292                Err(from_glib_full(error))
1293            }
1294        }
1295    }
1296
1297    //#[doc(alias = "g_uri_parse_params")]
1298    //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> {
1299    //    unsafe { TODO: call ffi:g_uri_parse_params() }
1300    //}
1301
1302    /// Gets the scheme portion of a URI string.
1303    /// [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
1304    /// as:
1305    ///
1306    /// ```text
1307    /// URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
1308    /// ```
1309    /// Common schemes include `file`, `https`, `svn+ssh`, etc.
1310    /// ## `uri`
1311    /// a valid URI.
1312    ///
1313    /// # Returns
1314    ///
1315    /// The ‘scheme’ component of the URI, or
1316    ///     [`None`] on error. The returned string should be freed when no longer needed.
1317    // rustdoc-stripper-ignore-next-stop
1318    /// Gets the scheme portion of a URI string.
1319    /// [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
1320    /// as:
1321    ///
1322    /// ```text
1323    /// URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
1324    /// ```
1325    /// Common schemes include `file`, `https`, `svn+ssh`, etc.
1326    /// ## `uri`
1327    /// a valid URI.
1328    ///
1329    /// # Returns
1330    ///
1331    /// The ‘scheme’ component of the URI, or
1332    ///     [`None`] on error. The returned string should be freed when no longer needed.
1333    #[doc(alias = "g_uri_parse_scheme")]
1334    pub fn parse_scheme(uri: &str) -> Option<crate::GString> {
1335        unsafe { from_glib_full(ffi::g_uri_parse_scheme(uri.to_glib_none().0)) }
1336    }
1337
1338    /// Gets the scheme portion of a URI string.
1339    /// [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
1340    /// as:
1341    ///
1342    /// ```text
1343    /// URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
1344    /// ```
1345    /// Common schemes include `file`, `https`, `svn+ssh`, etc.
1346    ///
1347    /// Unlike g_uri_parse_scheme(), the returned scheme is normalized to
1348    /// all-lowercase and does not need to be freed.
1349    /// ## `uri`
1350    /// a valid URI.
1351    ///
1352    /// # Returns
1353    ///
1354    /// The ‘scheme’ component of the URI, or
1355    ///     [`None`] on error. The returned string is normalized to all-lowercase, and
1356    ///     interned via g_intern_string(), so it does not need to be freed.
1357    // rustdoc-stripper-ignore-next-stop
1358    /// Gets the scheme portion of a URI string.
1359    /// [RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
1360    /// as:
1361    ///
1362    /// ```text
1363    /// URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
1364    /// ```
1365    /// Common schemes include `file`, `https`, `svn+ssh`, etc.
1366    ///
1367    /// Unlike g_uri_parse_scheme(), the returned scheme is normalized to
1368    /// all-lowercase and does not need to be freed.
1369    /// ## `uri`
1370    /// a valid URI.
1371    ///
1372    /// # Returns
1373    ///
1374    /// The ‘scheme’ component of the URI, or
1375    ///     [`None`] on error. The returned string is normalized to all-lowercase, and
1376    ///     interned via g_intern_string(), so it does not need to be freed.
1377    #[doc(alias = "g_uri_peek_scheme")]
1378    pub fn peek_scheme(uri: &str) -> Option<crate::GString> {
1379        unsafe { from_glib_none(ffi::g_uri_peek_scheme(uri.to_glib_none().0)) }
1380    }
1381
1382    /// Parses @uri_ref according to @flags and, if it is a
1383    /// [relative URI](#relative-and-absolute-uris), resolves it relative to
1384    /// @base_uri_string. If the result is not a valid absolute URI, it will be
1385    /// discarded, and an error returned.
1386    ///
1387    /// (If @base_uri_string is [`None`], this just returns @uri_ref, or
1388    /// [`None`] if @uri_ref is invalid or not absolute.)
1389    /// ## `base_uri_string`
1390    /// a string representing a base URI
1391    /// ## `uri_ref`
1392    /// a string representing a relative or absolute URI
1393    /// ## `flags`
1394    /// flags describing how to parse @uri_ref
1395    ///
1396    /// # Returns
1397    ///
1398    /// the resolved URI string,
1399    /// or NULL on error.
1400    // rustdoc-stripper-ignore-next-stop
1401    /// Parses @uri_ref according to @flags and, if it is a
1402    /// [relative URI](#relative-and-absolute-uris), resolves it relative to
1403    /// @base_uri_string. If the result is not a valid absolute URI, it will be
1404    /// discarded, and an error returned.
1405    ///
1406    /// (If @base_uri_string is [`None`], this just returns @uri_ref, or
1407    /// [`None`] if @uri_ref is invalid or not absolute.)
1408    /// ## `base_uri_string`
1409    /// a string representing a base URI
1410    /// ## `uri_ref`
1411    /// a string representing a relative or absolute URI
1412    /// ## `flags`
1413    /// flags describing how to parse @uri_ref
1414    ///
1415    /// # Returns
1416    ///
1417    /// the resolved URI string,
1418    /// or NULL on error.
1419    #[doc(alias = "g_uri_resolve_relative")]
1420    pub fn resolve_relative(
1421        base_uri_string: Option<&str>,
1422        uri_ref: &str,
1423        flags: UriFlags,
1424    ) -> Result<crate::GString, crate::Error> {
1425        unsafe {
1426            let mut error = std::ptr::null_mut();
1427            let ret = ffi::g_uri_resolve_relative(
1428                base_uri_string.to_glib_none().0,
1429                uri_ref.to_glib_none().0,
1430                flags.into_glib(),
1431                &mut error,
1432            );
1433            if error.is_null() {
1434                Ok(from_glib_full(ret))
1435            } else {
1436                Err(from_glib_full(error))
1437            }
1438        }
1439    }
1440
1441    /// Parses @uri_ref (which can be an
1442    /// [absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and
1443    /// returns the pieces. Any component that doesn't appear in @uri_ref will be
1444    /// returned as [`None`] (but note that all URIs always have a path component,
1445    /// though it may be the empty string).
1446    ///
1447    /// If @flags contains [`UriFlags::ENCODED`][crate::UriFlags::ENCODED], then `%`-encoded characters in
1448    /// @uri_ref will remain encoded in the output strings. (If not,
1449    /// then all such characters will be decoded.) Note that decoding will
1450    /// only work if the URI components are ASCII or UTF-8, so you will
1451    /// need to use [`UriFlags::ENCODED`][crate::UriFlags::ENCODED] if they are not.
1452    ///
1453    /// Note that the [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] and
1454    /// [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] @flags are ignored by g_uri_split(),
1455    /// since it always returns only the full userinfo; use
1456    /// g_uri_split_with_user() if you want it split up.
1457    /// ## `uri_ref`
1458    /// a string containing a relative or absolute URI
1459    /// ## `flags`
1460    /// flags for parsing @uri_ref
1461    ///
1462    /// # Returns
1463    ///
1464    /// [`true`] if @uri_ref parsed successfully, [`false`]
1465    ///   on error.
1466    ///
1467    /// ## `scheme`
1468    /// on return, contains
1469    ///    the scheme (converted to lowercase), or [`None`]
1470    ///
1471    /// ## `userinfo`
1472    /// on return, contains
1473    ///    the userinfo, or [`None`]
1474    ///
1475    /// ## `host`
1476    /// on return, contains the
1477    ///    host, or [`None`]
1478    ///
1479    /// ## `port`
1480    /// on return, contains the
1481    ///    port, or `-1`
1482    ///
1483    /// ## `path`
1484    /// on return, contains the
1485    ///    path
1486    ///
1487    /// ## `query`
1488    /// on return, contains the
1489    ///    query, or [`None`]
1490    ///
1491    /// ## `fragment`
1492    /// on return, contains
1493    ///    the fragment, or [`None`]
1494    // rustdoc-stripper-ignore-next-stop
1495    /// Parses @uri_ref (which can be an
1496    /// [absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and
1497    /// returns the pieces. Any component that doesn't appear in @uri_ref will be
1498    /// returned as [`None`] (but note that all URIs always have a path component,
1499    /// though it may be the empty string).
1500    ///
1501    /// If @flags contains [`UriFlags::ENCODED`][crate::UriFlags::ENCODED], then `%`-encoded characters in
1502    /// @uri_ref will remain encoded in the output strings. (If not,
1503    /// then all such characters will be decoded.) Note that decoding will
1504    /// only work if the URI components are ASCII or UTF-8, so you will
1505    /// need to use [`UriFlags::ENCODED`][crate::UriFlags::ENCODED] if they are not.
1506    ///
1507    /// Note that the [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD] and
1508    /// [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS] @flags are ignored by g_uri_split(),
1509    /// since it always returns only the full userinfo; use
1510    /// g_uri_split_with_user() if you want it split up.
1511    /// ## `uri_ref`
1512    /// a string containing a relative or absolute URI
1513    /// ## `flags`
1514    /// flags for parsing @uri_ref
1515    ///
1516    /// # Returns
1517    ///
1518    /// [`true`] if @uri_ref parsed successfully, [`false`]
1519    ///   on error.
1520    ///
1521    /// ## `scheme`
1522    /// on return, contains
1523    ///    the scheme (converted to lowercase), or [`None`]
1524    ///
1525    /// ## `userinfo`
1526    /// on return, contains
1527    ///    the userinfo, or [`None`]
1528    ///
1529    /// ## `host`
1530    /// on return, contains the
1531    ///    host, or [`None`]
1532    ///
1533    /// ## `port`
1534    /// on return, contains the
1535    ///    port, or `-1`
1536    ///
1537    /// ## `path`
1538    /// on return, contains the
1539    ///    path
1540    ///
1541    /// ## `query`
1542    /// on return, contains the
1543    ///    query, or [`None`]
1544    ///
1545    /// ## `fragment`
1546    /// on return, contains
1547    ///    the fragment, or [`None`]
1548    #[doc(alias = "g_uri_split")]
1549    pub fn split(
1550        uri_ref: &str,
1551        flags: UriFlags,
1552    ) -> Result<
1553        (
1554            Option<crate::GString>,
1555            Option<crate::GString>,
1556            Option<crate::GString>,
1557            i32,
1558            crate::GString,
1559            Option<crate::GString>,
1560            Option<crate::GString>,
1561        ),
1562        crate::Error,
1563    > {
1564        unsafe {
1565            let mut scheme = std::ptr::null_mut();
1566            let mut userinfo = std::ptr::null_mut();
1567            let mut host = std::ptr::null_mut();
1568            let mut port = std::mem::MaybeUninit::uninit();
1569            let mut path = std::ptr::null_mut();
1570            let mut query = std::ptr::null_mut();
1571            let mut fragment = std::ptr::null_mut();
1572            let mut error = std::ptr::null_mut();
1573            let is_ok = ffi::g_uri_split(
1574                uri_ref.to_glib_none().0,
1575                flags.into_glib(),
1576                &mut scheme,
1577                &mut userinfo,
1578                &mut host,
1579                port.as_mut_ptr(),
1580                &mut path,
1581                &mut query,
1582                &mut fragment,
1583                &mut error,
1584            );
1585            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
1586            if error.is_null() {
1587                Ok((
1588                    from_glib_full(scheme),
1589                    from_glib_full(userinfo),
1590                    from_glib_full(host),
1591                    port.assume_init(),
1592                    from_glib_full(path),
1593                    from_glib_full(query),
1594                    from_glib_full(fragment),
1595                ))
1596            } else {
1597                Err(from_glib_full(error))
1598            }
1599        }
1600    }
1601
1602    /// Parses @uri_string (which must be an [absolute URI](#relative-and-absolute-uris))
1603    /// according to @flags, and returns the pieces relevant to connecting to a host.
1604    /// See the documentation for g_uri_split() for more details; this is
1605    /// mostly a wrapper around that function with simpler arguments.
1606    /// However, it will return an error if @uri_string is a relative URI,
1607    /// or does not contain a hostname component.
1608    /// ## `uri_string`
1609    /// a string containing an absolute URI
1610    /// ## `flags`
1611    /// flags for parsing @uri_string
1612    ///
1613    /// # Returns
1614    ///
1615    /// [`true`] if @uri_string parsed successfully,
1616    ///   [`false`] on error.
1617    ///
1618    /// ## `scheme`
1619    /// on return, contains
1620    ///    the scheme (converted to lowercase), or [`None`]
1621    ///
1622    /// ## `host`
1623    /// on return, contains the
1624    ///    host, or [`None`]
1625    ///
1626    /// ## `port`
1627    /// on return, contains the
1628    ///    port, or `-1`
1629    // rustdoc-stripper-ignore-next-stop
1630    /// Parses @uri_string (which must be an [absolute URI](#relative-and-absolute-uris))
1631    /// according to @flags, and returns the pieces relevant to connecting to a host.
1632    /// See the documentation for g_uri_split() for more details; this is
1633    /// mostly a wrapper around that function with simpler arguments.
1634    /// However, it will return an error if @uri_string is a relative URI,
1635    /// or does not contain a hostname component.
1636    /// ## `uri_string`
1637    /// a string containing an absolute URI
1638    /// ## `flags`
1639    /// flags for parsing @uri_string
1640    ///
1641    /// # Returns
1642    ///
1643    /// [`true`] if @uri_string parsed successfully,
1644    ///   [`false`] on error.
1645    ///
1646    /// ## `scheme`
1647    /// on return, contains
1648    ///    the scheme (converted to lowercase), or [`None`]
1649    ///
1650    /// ## `host`
1651    /// on return, contains the
1652    ///    host, or [`None`]
1653    ///
1654    /// ## `port`
1655    /// on return, contains the
1656    ///    port, or `-1`
1657    #[doc(alias = "g_uri_split_network")]
1658    pub fn split_network(
1659        uri_string: &str,
1660        flags: UriFlags,
1661    ) -> Result<(Option<crate::GString>, Option<crate::GString>, i32), crate::Error> {
1662        unsafe {
1663            let mut scheme = std::ptr::null_mut();
1664            let mut host = std::ptr::null_mut();
1665            let mut port = std::mem::MaybeUninit::uninit();
1666            let mut error = std::ptr::null_mut();
1667            let is_ok = ffi::g_uri_split_network(
1668                uri_string.to_glib_none().0,
1669                flags.into_glib(),
1670                &mut scheme,
1671                &mut host,
1672                port.as_mut_ptr(),
1673                &mut error,
1674            );
1675            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
1676            if error.is_null() {
1677                Ok((
1678                    from_glib_full(scheme),
1679                    from_glib_full(host),
1680                    port.assume_init(),
1681                ))
1682            } else {
1683                Err(from_glib_full(error))
1684            }
1685        }
1686    }
1687
1688    /// Parses @uri_ref (which can be an
1689    /// [absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and
1690    /// returns the pieces. Any component that doesn't appear in @uri_ref will be
1691    /// returned as [`None`] (but note that all URIs always have a path component,
1692    /// though it may be the empty string).
1693    ///
1694    /// See g_uri_split(), and the definition of #GUriFlags, for more
1695    /// information on the effect of @flags. Note that @password will only
1696    /// be parsed out if @flags contains [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD], and
1697    /// @auth_params will only be parsed out if @flags contains
1698    /// [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS].
1699    /// ## `uri_ref`
1700    /// a string containing a relative or absolute URI
1701    /// ## `flags`
1702    /// flags for parsing @uri_ref
1703    ///
1704    /// # Returns
1705    ///
1706    /// [`true`] if @uri_ref parsed successfully, [`false`]
1707    ///   on error.
1708    ///
1709    /// ## `scheme`
1710    /// on return, contains
1711    ///    the scheme (converted to lowercase), or [`None`]
1712    ///
1713    /// ## `user`
1714    /// on return, contains
1715    ///    the user, or [`None`]
1716    ///
1717    /// ## `password`
1718    /// on return, contains
1719    ///    the password, or [`None`]
1720    ///
1721    /// ## `auth_params`
1722    /// on return, contains
1723    ///    the auth_params, or [`None`]
1724    ///
1725    /// ## `host`
1726    /// on return, contains the
1727    ///    host, or [`None`]
1728    ///
1729    /// ## `port`
1730    /// on return, contains the
1731    ///    port, or `-1`
1732    ///
1733    /// ## `path`
1734    /// on return, contains the
1735    ///    path
1736    ///
1737    /// ## `query`
1738    /// on return, contains the
1739    ///    query, or [`None`]
1740    ///
1741    /// ## `fragment`
1742    /// on return, contains
1743    ///    the fragment, or [`None`]
1744    // rustdoc-stripper-ignore-next-stop
1745    /// Parses @uri_ref (which can be an
1746    /// [absolute or relative URI](#relative-and-absolute-uris)) according to @flags, and
1747    /// returns the pieces. Any component that doesn't appear in @uri_ref will be
1748    /// returned as [`None`] (but note that all URIs always have a path component,
1749    /// though it may be the empty string).
1750    ///
1751    /// See g_uri_split(), and the definition of #GUriFlags, for more
1752    /// information on the effect of @flags. Note that @password will only
1753    /// be parsed out if @flags contains [`UriFlags::HAS_PASSWORD`][crate::UriFlags::HAS_PASSWORD], and
1754    /// @auth_params will only be parsed out if @flags contains
1755    /// [`UriFlags::HAS_AUTH_PARAMS`][crate::UriFlags::HAS_AUTH_PARAMS].
1756    /// ## `uri_ref`
1757    /// a string containing a relative or absolute URI
1758    /// ## `flags`
1759    /// flags for parsing @uri_ref
1760    ///
1761    /// # Returns
1762    ///
1763    /// [`true`] if @uri_ref parsed successfully, [`false`]
1764    ///   on error.
1765    ///
1766    /// ## `scheme`
1767    /// on return, contains
1768    ///    the scheme (converted to lowercase), or [`None`]
1769    ///
1770    /// ## `user`
1771    /// on return, contains
1772    ///    the user, or [`None`]
1773    ///
1774    /// ## `password`
1775    /// on return, contains
1776    ///    the password, or [`None`]
1777    ///
1778    /// ## `auth_params`
1779    /// on return, contains
1780    ///    the auth_params, or [`None`]
1781    ///
1782    /// ## `host`
1783    /// on return, contains the
1784    ///    host, or [`None`]
1785    ///
1786    /// ## `port`
1787    /// on return, contains the
1788    ///    port, or `-1`
1789    ///
1790    /// ## `path`
1791    /// on return, contains the
1792    ///    path
1793    ///
1794    /// ## `query`
1795    /// on return, contains the
1796    ///    query, or [`None`]
1797    ///
1798    /// ## `fragment`
1799    /// on return, contains
1800    ///    the fragment, or [`None`]
1801    #[doc(alias = "g_uri_split_with_user")]
1802    pub fn split_with_user(
1803        uri_ref: &str,
1804        flags: UriFlags,
1805    ) -> Result<
1806        (
1807            Option<crate::GString>,
1808            Option<crate::GString>,
1809            Option<crate::GString>,
1810            Option<crate::GString>,
1811            Option<crate::GString>,
1812            i32,
1813            crate::GString,
1814            Option<crate::GString>,
1815            Option<crate::GString>,
1816        ),
1817        crate::Error,
1818    > {
1819        unsafe {
1820            let mut scheme = std::ptr::null_mut();
1821            let mut user = std::ptr::null_mut();
1822            let mut password = std::ptr::null_mut();
1823            let mut auth_params = std::ptr::null_mut();
1824            let mut host = std::ptr::null_mut();
1825            let mut port = std::mem::MaybeUninit::uninit();
1826            let mut path = std::ptr::null_mut();
1827            let mut query = std::ptr::null_mut();
1828            let mut fragment = std::ptr::null_mut();
1829            let mut error = std::ptr::null_mut();
1830            let is_ok = ffi::g_uri_split_with_user(
1831                uri_ref.to_glib_none().0,
1832                flags.into_glib(),
1833                &mut scheme,
1834                &mut user,
1835                &mut password,
1836                &mut auth_params,
1837                &mut host,
1838                port.as_mut_ptr(),
1839                &mut path,
1840                &mut query,
1841                &mut fragment,
1842                &mut error,
1843            );
1844            debug_assert_eq!(is_ok == crate::ffi::GFALSE, !error.is_null());
1845            if error.is_null() {
1846                Ok((
1847                    from_glib_full(scheme),
1848                    from_glib_full(user),
1849                    from_glib_full(password),
1850                    from_glib_full(auth_params),
1851                    from_glib_full(host),
1852                    port.assume_init(),
1853                    from_glib_full(path),
1854                    from_glib_full(query),
1855                    from_glib_full(fragment),
1856                ))
1857            } else {
1858                Err(from_glib_full(error))
1859            }
1860        }
1861    }
1862
1863    /// Unescapes a segment of an escaped string as binary data.
1864    ///
1865    /// Note that in contrast to g_uri_unescape_string(), this does allow
1866    /// nul bytes to appear in the output.
1867    ///
1868    /// If any of the characters in @illegal_characters appears as an escaped
1869    /// character in @escaped_string, then that is an error and [`None`] will be
1870    /// returned. This is useful if you want to avoid for instance having a slash
1871    /// being expanded in an escaped path element, which might confuse pathname
1872    /// handling.
1873    /// ## `escaped_string`
1874    /// A URI-escaped string
1875    /// ## `length`
1876    /// the length (in bytes) of @escaped_string to escape, or `-1` if it
1877    ///   is nul-terminated.
1878    /// ## `illegal_characters`
1879    /// a string of illegal characters
1880    ///   not to be allowed, or [`None`].
1881    ///
1882    /// # Returns
1883    ///
1884    /// an unescaped version of @escaped_string
1885    ///     or [`None`] on error (if decoding failed, using [`UriError::Failed`][crate::UriError::Failed] error
1886    ///     code). The returned #GBytes should be unreffed when no longer needed.
1887    // rustdoc-stripper-ignore-next-stop
1888    /// Unescapes a segment of an escaped string as binary data.
1889    ///
1890    /// Note that in contrast to g_uri_unescape_string(), this does allow
1891    /// nul bytes to appear in the output.
1892    ///
1893    /// If any of the characters in @illegal_characters appears as an escaped
1894    /// character in @escaped_string, then that is an error and [`None`] will be
1895    /// returned. This is useful if you want to avoid for instance having a slash
1896    /// being expanded in an escaped path element, which might confuse pathname
1897    /// handling.
1898    /// ## `escaped_string`
1899    /// A URI-escaped string
1900    /// ## `length`
1901    /// the length (in bytes) of @escaped_string to escape, or `-1` if it
1902    ///   is nul-terminated.
1903    /// ## `illegal_characters`
1904    /// a string of illegal characters
1905    ///   not to be allowed, or [`None`].
1906    ///
1907    /// # Returns
1908    ///
1909    /// an unescaped version of @escaped_string
1910    ///     or [`None`] on error (if decoding failed, using [`UriError::Failed`][crate::UriError::Failed] error
1911    ///     code). The returned #GBytes should be unreffed when no longer needed.
1912    #[doc(alias = "g_uri_unescape_bytes")]
1913    pub fn unescape_bytes(
1914        escaped_string: &str,
1915        illegal_characters: Option<&str>,
1916    ) -> Result<Bytes, crate::Error> {
1917        let length = escaped_string.len() as _;
1918        unsafe {
1919            let mut error = std::ptr::null_mut();
1920            let ret = ffi::g_uri_unescape_bytes(
1921                escaped_string.to_glib_none().0,
1922                length,
1923                illegal_characters.to_glib_none().0,
1924                &mut error,
1925            );
1926            if error.is_null() {
1927                Ok(from_glib_full(ret))
1928            } else {
1929                Err(from_glib_full(error))
1930            }
1931        }
1932    }
1933
1934    /// Unescapes a segment of an escaped string.
1935    ///
1936    /// If any of the characters in @illegal_characters or the NUL
1937    /// character appears as an escaped character in @escaped_string, then
1938    /// that is an error and [`None`] will be returned. This is useful if you
1939    /// want to avoid for instance having a slash being expanded in an
1940    /// escaped path element, which might confuse pathname handling.
1941    ///
1942    /// Note: `NUL` byte is not accepted in the output, in contrast to
1943    /// g_uri_unescape_bytes().
1944    /// ## `escaped_string`
1945    /// A string, may be [`None`]
1946    /// ## `escaped_string_end`
1947    /// Pointer to end of @escaped_string,
1948    ///   may be [`None`]
1949    /// ## `illegal_characters`
1950    /// An optional string of illegal
1951    ///   characters not to be allowed, may be [`None`]
1952    ///
1953    /// # Returns
1954    ///
1955    /// an unescaped version of @escaped_string,
1956    /// or [`None`] on error. The returned string should be freed when no longer
1957    /// needed.  As a special case if [`None`] is given for @escaped_string, this
1958    /// function will return [`None`].
1959    // rustdoc-stripper-ignore-next-stop
1960    /// Unescapes a segment of an escaped string.
1961    ///
1962    /// If any of the characters in @illegal_characters or the NUL
1963    /// character appears as an escaped character in @escaped_string, then
1964    /// that is an error and [`None`] will be returned. This is useful if you
1965    /// want to avoid for instance having a slash being expanded in an
1966    /// escaped path element, which might confuse pathname handling.
1967    ///
1968    /// Note: `NUL` byte is not accepted in the output, in contrast to
1969    /// g_uri_unescape_bytes().
1970    /// ## `escaped_string`
1971    /// A string, may be [`None`]
1972    /// ## `escaped_string_end`
1973    /// Pointer to end of @escaped_string,
1974    ///   may be [`None`]
1975    /// ## `illegal_characters`
1976    /// An optional string of illegal
1977    ///   characters not to be allowed, may be [`None`]
1978    ///
1979    /// # Returns
1980    ///
1981    /// an unescaped version of @escaped_string,
1982    /// or [`None`] on error. The returned string should be freed when no longer
1983    /// needed.  As a special case if [`None`] is given for @escaped_string, this
1984    /// function will return [`None`].
1985    #[doc(alias = "g_uri_unescape_segment")]
1986    pub fn unescape_segment(
1987        escaped_string: Option<&str>,
1988        escaped_string_end: Option<&str>,
1989        illegal_characters: Option<&str>,
1990    ) -> Option<crate::GString> {
1991        unsafe {
1992            from_glib_full(ffi::g_uri_unescape_segment(
1993                escaped_string.to_glib_none().0,
1994                escaped_string_end.to_glib_none().0,
1995                illegal_characters.to_glib_none().0,
1996            ))
1997        }
1998    }
1999
2000    /// Unescapes a whole escaped string.
2001    ///
2002    /// If any of the characters in @illegal_characters or the NUL
2003    /// character appears as an escaped character in @escaped_string, then
2004    /// that is an error and [`None`] will be returned. This is useful if you
2005    /// want to avoid for instance having a slash being expanded in an
2006    /// escaped path element, which might confuse pathname handling.
2007    /// ## `escaped_string`
2008    /// an escaped string to be unescaped.
2009    /// ## `illegal_characters`
2010    /// a string of illegal characters
2011    ///   not to be allowed, or [`None`].
2012    ///
2013    /// # Returns
2014    ///
2015    /// an unescaped version of @escaped_string.
2016    /// The returned string should be freed when no longer needed.
2017    // rustdoc-stripper-ignore-next-stop
2018    /// Unescapes a whole escaped string.
2019    ///
2020    /// If any of the characters in @illegal_characters or the NUL
2021    /// character appears as an escaped character in @escaped_string, then
2022    /// that is an error and [`None`] will be returned. This is useful if you
2023    /// want to avoid for instance having a slash being expanded in an
2024    /// escaped path element, which might confuse pathname handling.
2025    /// ## `escaped_string`
2026    /// an escaped string to be unescaped.
2027    /// ## `illegal_characters`
2028    /// a string of illegal characters
2029    ///   not to be allowed, or [`None`].
2030    ///
2031    /// # Returns
2032    ///
2033    /// an unescaped version of @escaped_string.
2034    /// The returned string should be freed when no longer needed.
2035    #[doc(alias = "g_uri_unescape_string")]
2036    pub fn unescape_string(
2037        escaped_string: &str,
2038        illegal_characters: Option<&str>,
2039    ) -> Option<crate::GString> {
2040        unsafe {
2041            from_glib_full(ffi::g_uri_unescape_string(
2042                escaped_string.to_glib_none().0,
2043                illegal_characters.to_glib_none().0,
2044            ))
2045        }
2046    }
2047}
2048
2049impl std::fmt::Display for Uri {
2050    #[inline]
2051    fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
2052        f.write_str(&self.to_str())
2053    }
2054}
2055
2056unsafe impl Send for Uri {}
2057unsafe impl Sync for Uri {}