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 {}