ZelphirKaltstahl
/
guile-examples


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509
							<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>&lt;GUri&gt;: </title>
<meta name="generator" content="DocBook XSL Stylesheets V1.79.2">
<link rel="home" href="index.html" title="">
<link rel="up" href="ch01.html" title="GLib">
<link rel="prev" href="re76.html" title="&lt;%GLibUnicodeType&gt;">
<link rel="next" href="re78.html" title="&lt;%GLibUriError&gt;">
<meta name="generator" content="GTK-Doc V1.33.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><img src="up-insensitive.png" width="16" height="16" border="0"></td>
<td><a accesskey="p" href="re76.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="re78.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="refentry">
<a name="id-1.1.78"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>&lt;GUri&gt;</h2>
<p>&lt;GUri&gt;</p>
</div>
<div class="refsect1">
<a name="id-1.1.78.2"></a><h2>Description</h2>
<p>The <span class="type">GUri</span> type and related functions can be used to parse URIs into
their components, and build valid URIs from individual components.
</p>
<p>Note that <span class="type">GUri</span> scope is to help manipulate URIs in various applications,
following [RFC 3986](https://tools.ietf.org/html/rfc3986). In particular,
it doesn't intend to cover web browser needs, and doesn't implement the
[WHATWG URL](https://url.spec.whatwg.org/) standard. No APIs are provided to
help prevent
[homograph attacks](https://en.wikipedia.org/wiki/IDN_homograph_attack), so
<span class="type">GUri</span> is not suitable for formatting URIs for display to the user for making
security-sensitive decisions.
</p>
<div class="refsect2">
<a name="id-1.1.78.2.4"></a><h3>Relative and absolute URIs <a name="relative-absolute-uris"></a>
</h3>
<p>As defined in [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4), the
hierarchical nature of URIs means that they can either be ‘relative
references’ (sometimes referred to as ‘relative URIs’) or ‘URIs’ (for
clarity, ‘URIs’ are referred to in this documentation as
‘absolute URIs’ — although
[in constrast to RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.3),
fragment identifiers are always allowed).
</p>
<p>Relative references have one or more components of the URI missing. In
particular, they have no scheme. Any other component, such as hostname,
query, etc. may be missing, apart from a path, which has to be specified (but
may be empty). The path may be relative, starting with <code class="code">./</code> rather than <code class="code">/</code>.
</p>
<p>For example, a valid relative reference is <code class="code">./path?query</code>,
<code class="code">/?query#fragment</code> or <code class="code">//example.com</code>.
</p>
<p>Absolute URIs have a scheme specified. Any other components of the URI which
are missing are specified as explicitly unset in the URI, rather than being
resolved relative to a base URI using <code class="function">g_uri_parse_relative()</code>.
</p>
<p>For example, a valid absolute URI is <code class="code">file:///home/bob</code> or
<code class="code">https://search.com?query=string</code>.
</p>
<p>A <span class="type">GUri</span> instance is always an absolute URI. A string may be an absolute URI
or a relative reference; see the documentation for individual functions as to
what forms they accept.
</p>
</div>
<div class="refsect2">
<a name="id-1.1.78.2.5"></a><h3>Parsing URIs</h3>
<p>The most minimalist APIs for parsing URIs are <code class="function">g_uri_split()</code> and
<code class="function">g_uri_split_with_user()</code>. These split a URI into its component
parts, and return the parts; the difference between the two is that
<code class="function">g_uri_split()</code> treats the ‘userinfo’ component of the URI as a
single element, while <code class="function">g_uri_split_with_user()</code> can (depending on the
<span class="type">GUriFlags</span> you pass) treat it as containing a username, password,
and authentication parameters. Alternatively, <code class="function">g_uri_split_network()</code>
can be used when you are only interested in the components that are
needed to initiate a network connection to the service (scheme,
host, and port).
</p>
<p><code class="function">g_uri_parse()</code> is similar to <code class="function">g_uri_split()</code>, but instead of returning
individual strings, it returns a <span class="type">GUri</span> structure (and it requires
that the URI be an absolute URI).
</p>
<p><code class="function">g_uri_resolve_relative()</code> and <code class="function">g_uri_parse_relative()</code> allow you to
resolve a relative URI relative to a base URI.
<code class="function">g_uri_resolve_relative()</code> takes two strings and returns a string,
and <code class="function">g_uri_parse_relative()</code> takes a <span class="type">GUri</span> and a string and returns a
<span class="type">GUri</span>.
</p>
<p>All of the parsing functions take a <span class="type">GUriFlags</span> argument describing
exactly how to parse the URI; see the documentation for that type
for more details on the specific flags that you can pass. If you
need to choose different flags based on the type of URI, you can
use <code class="function">g_uri_peek_scheme()</code> on the URI string to check the scheme
first, and use that to decide what flags to parse it with.
</p>
<p>For example, you might want to use <code class="constant">G_URI_PARAMS_WWW_FORM</code> when parsing the
params for a web URI, so compare the result of <code class="function">g_uri_peek_scheme()</code> against
<code class="code">http</code> and <code class="code">https</code>.
</p>
</div>
<div class="refsect2">
<a name="id-1.1.78.2.6"></a><h3>Building URIs</h3>
<p><code class="function">g_uri_join()</code> and <code class="function">g_uri_join_with_user()</code> can be used to construct
valid URI strings from a set of component strings. They are the
inverse of <code class="function">g_uri_split()</code> and <code class="function">g_uri_split_with_user()</code>.
</p>
<p>Similarly, <code class="function">g_uri_build()</code> and <code class="function">g_uri_build_with_user()</code> can be used to
construct a <span class="type">GUri</span> from a set of component strings.
</p>
<p>As with the parsing functions, the building functions take a
<span class="type">GUriFlags</span> argument. In particular, it is important to keep in mind
whether the URI components you are using are already <code class="code">%</code>-encoded. If so,
you must pass the <code class="constant">G_URI_FLAGS_ENCODED</code> flag.
</p>
</div>
<div class="refsect2">
<a name="id-1.1.78.2.7"></a><h3>`file://` URIs</h3>
<p>Note that Windows and Unix both define special rules for parsing
<code class="code">file://</code> URIs (involving non-UTF-8 character sets on Unix, and the
interpretation of path separators on Windows). <span class="type">GUri</span> does not
implement these rules. Use <code class="function">g_filename_from_uri()</code> and
<code class="function">g_filename_to_uri()</code> if you want to properly convert between
<code class="code">file://</code> URIs and local filenames.
</p>
</div>
<div class="refsect2">
<a name="id-1.1.78.2.8"></a><h3>URI Equality</h3>
<p>Note that there is no <code class="code">g_uri_equal ()</code> function, because comparing
URIs usefully requires scheme-specific knowledge that <span class="type">GUri</span> does
not have. For example, <code class="code">http://example.com/</code> and
<code class="code">http://EXAMPLE.COM:80</code> have exactly the same meaning according
to the HTTP specification, and <code class="code">data:,foo</code> and
<code class="code">data:;base64,Zm9v</code> resolve to the same thing according to the
<code class="code">data:</code> URI specification.</p>
</div>
</div>
<div class="refsect1">
<a name="id-1.1.78.3"></a><h2>Functions</h2>
<div class="refsect2">
<a name="id-1.1.78.3.2"></a><h3>get-auth-params</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:get-auth-params self))
</pre></div>
<p>Gets <em class="parameter"><code>uri</code></em>'s authentication parameters, which may contain
<code class="code">%</code>-encoding, depending on the flags with which <em class="parameter"><code>uri</code></em> was created.
(If <em class="parameter"><code>uri</code></em> was not created with <code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code> then this will
be <code class="constant">NULL</code>.)
</p>
<p>Depending on the URI scheme, <code class="function">g_uri_parse_params()</code> may be useful for
further parsing this information.</p>
<div class="refsect3">
<a name="id-1.1.78.3.2.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a <span class="type">GUri</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.3"></a><h3>get-flags</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:get-flags self))
</pre></div>
<p>Gets <em class="parameter"><code>uri</code></em>'s flags set upon construction.</p>
<div class="refsect3">
<a name="id-1.1.78.3.3.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a <span class="type">GUri</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.4"></a><h3>get-fragment</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:get-fragment self))
</pre></div>
<p>Gets <em class="parameter"><code>uri</code></em>'s fragment, which may contain <code class="code">%</code>-encoding, depending on
the flags with which <em class="parameter"><code>uri</code></em> was created.</p>
<div class="refsect3">
<a name="id-1.1.78.3.4.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a <span class="type">GUri</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.5"></a><h3>get-host</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:get-host self))
</pre></div>
<p>Gets <em class="parameter"><code>uri</code></em>'s host. This will never have <code class="code">%</code>-encoded characters,
unless it is non-UTF-8 (which can only be the case if <em class="parameter"><code>uri</code></em> was
created with <code class="constant">G_URI_FLAGS_NON_DNS</code>).
</p>
<p>If <em class="parameter"><code>uri</code></em> contained an IPv6 address literal, this value will be just
that address, without the brackets around it that are necessary in
the string form of the URI. Note that in this case there may also
be a scope ID attached to the address. Eg, <code class="code">fe80::1234%</code><code class="code">em1</code> (or
<code class="code">fe80::1234%</code><code class="code">25em1</code> if the string is still encoded).</p>
<div class="refsect3">
<a name="id-1.1.78.3.5.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a <span class="type">GUri</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.6"></a><h3>get-password</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:get-password self))
</pre></div>
<p>Gets <em class="parameter"><code>uri</code></em>'s password, which may contain <code class="code">%</code>-encoding, depending on
the flags with which <em class="parameter"><code>uri</code></em> was created. (If <em class="parameter"><code>uri</code></em> was not created
with <code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> then this will be <code class="constant">NULL</code>.)</p>
<div class="refsect3">
<a name="id-1.1.78.3.6.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a <span class="type">GUri</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.7"></a><h3>get-path</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:get-path self))
</pre></div>
<p>Gets <em class="parameter"><code>uri</code></em>'s path, which may contain <code class="code">%</code>-encoding, depending on the
flags with which <em class="parameter"><code>uri</code></em> was created.</p>
<div class="refsect3">
<a name="id-1.1.78.3.7.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a <span class="type">GUri</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.8"></a><h3>get-port</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:get-port self))
</pre></div>
<p>Gets <em class="parameter"><code>uri</code></em>'s port.</p>
<div class="refsect3">
<a name="id-1.1.78.3.8.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a <span class="type">GUri</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.9"></a><h3>get-query</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:get-query self))
</pre></div>
<p>Gets <em class="parameter"><code>uri</code></em>'s query, which may contain <code class="code">%</code>-encoding, depending on the
flags with which <em class="parameter"><code>uri</code></em> was created.
</p>
<p>For queries consisting of a series of <code class="code">name=value</code> parameters,
<span class="type">GUriParamsIter</span> or <code class="function">g_uri_parse_params()</code> may be useful.</p>
<div class="refsect3">
<a name="id-1.1.78.3.9.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a <span class="type">GUri</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.10"></a><h3>get-scheme</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:get-scheme self))
</pre></div>
<p>Gets <em class="parameter"><code>uri</code></em>'s scheme. Note that this will always be all-lowercase,
regardless of the string or strings that <em class="parameter"><code>uri</code></em> was created from.</p>
<div class="refsect3">
<a name="id-1.1.78.3.10.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a <span class="type">GUri</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.11"></a><h3>get-user</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:get-user self))
</pre></div>
<p>Gets the ‘username’ component of <em class="parameter"><code>uri</code></em>'s userinfo, which may contain
<code class="code">%</code>-encoding, depending on the flags with which <em class="parameter"><code>uri</code></em> was created.
If <em class="parameter"><code>uri</code></em> was not created with <code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> or
<code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code>, this is the same as <code class="function">g_uri_get_userinfo()</code>.</p>
<div class="refsect3">
<a name="id-1.1.78.3.11.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a <span class="type">GUri</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.12"></a><h3>get-userinfo</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:get-userinfo self))
</pre></div>
<p>Gets <em class="parameter"><code>uri</code></em>'s userinfo, which may contain <code class="code">%</code>-encoding, depending on
the flags with which <em class="parameter"><code>uri</code></em> was created.</p>
<div class="refsect3">
<a name="id-1.1.78.3.12.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a <span class="type">GUri</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.13"></a><h3>parse-relative</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:parse-relative self uri-ref flags))
</pre></div>
<p>Parses <em class="parameter"><code>uri_ref</code></em> according to <em class="parameter"><code>flags</code></em> and, if it is a
[relative URI][relative-absolute-uris], resolves it relative to <em class="parameter"><code>base_uri</code></em>.
If the result is not a valid absolute URI, it will be discarded, and an error
returned.</p>
<div class="refsect3">
<a name="id-1.1.78.3.13.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>base_uri</p></td>
<td class="parameter_description">
<p>a base absolute URI</p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>uri_ref</p></td>
<td class="parameter_description">
<p>a string representing a relative or absolute URI</p>
<p>Passed as <code class="code">uri-ref</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing how to parse <em class="parameter"><code>uri_ref</code></em></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.14"></a><h3>to-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:to-string self))
</pre></div>
<p>Returns a string representing <em class="parameter"><code>uri</code></em>.
</p>
<p>This is not guaranteed to return a string which is identical to the
string that <em class="parameter"><code>uri</code></em> was parsed from. However, if the source URI was
syntactically correct (according to RFC 3986), and it was parsed
with <code class="constant">G_URI_FLAGS_ENCODED</code>, then <code class="function">g_uri_to_string()</code> is guaranteed to return
a string which is at least semantically equivalent to the source
URI (according to RFC 3986).
</p>
<p>If <em class="parameter"><code>uri</code></em> might contain sensitive details, such as authentication parameters,
or private data in its query string, and the returned string is going to be
logged, then consider using <code class="function">g_uri_to_string_partial()</code> to redact parts.</p>
<div class="refsect3">
<a name="id-1.1.78.3.14.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a <span class="type">GUri</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.15"></a><h3>to-string-partial</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:to-string-partial self flags))
</pre></div>
<p>Returns a string representing <em class="parameter"><code>uri</code></em>, subject to the options in
<em class="parameter"><code>flags</code></em>. See <code class="function">g_uri_to_string()</code> and <span class="type">GUriHideFlags</span> for more details.</p>
<div class="refsect3">
<a name="id-1.1.78.3.15.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a <span class="type">GUri</span></p>
<p>Passed as <code class="code">self</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing what parts of <em class="parameter"><code>uri</code></em> to hide</p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.16"></a><h3>uri:build</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri:build flags scheme userinfo host port path query fragment))
</pre></div>
<p>Creates a new <span class="type">GUri</span> from the given components according to <em class="parameter"><code>flags</code></em>.
</p>
<p>See also <code class="function">g_uri_build_with_user()</code>, which allows specifying the
components of the "userinfo" separately.</p>
<div class="refsect3">
<a name="id-1.1.78.3.16.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing how to build the <span class="type">GUri</span></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>the URI scheme</p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>userinfo</p></td>
<td class="parameter_description">
<p>the userinfo component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">userinfo</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>the host component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>the port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>path</p></td>
<td class="parameter_description">
<p>the path component</p>
<p>Passed as <code class="code">path</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>query</p></td>
<td class="parameter_description">
<p>the query component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">query</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fragment</p></td>
<td class="parameter_description">
<p>the fragment, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">fragment</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.17"></a><h3>uri:build-with-user</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri:build-with-user
    flags
    scheme
    user
    password
    auth-params
    host
    port
    path
    query
    fragment))
</pre></div>
<p>Creates a new <span class="type">GUri</span> from the given components according to <em class="parameter"><code>flags</code></em>
(<code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> is added unconditionally). The <em class="parameter"><code>flags</code></em> must be
coherent with the passed values, in particular use <code class="code">%</code>-encoded values with
<code class="constant">G_URI_FLAGS_ENCODED</code>.
</p>
<p>In contrast to <code class="function">g_uri_build()</code>, this allows specifying the components
of the ‘userinfo’ field separately. Note that <em class="parameter"><code>user</code></em> must be non-<code class="constant">NULL</code>
if either <em class="parameter"><code>password</code></em> or <em class="parameter"><code>auth_params</code></em> is non-<code class="constant">NULL</code>.</p>
<div class="refsect3">
<a name="id-1.1.78.3.17.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing how to build the <span class="type">GUri</span></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>the URI scheme</p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user</p></td>
<td class="parameter_description">
<p>the user component of the userinfo, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">user</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>password</p></td>
<td class="parameter_description">
<p>the password component of the userinfo, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">password</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>auth_params</p></td>
<td class="parameter_description">
<p>the auth params of the userinfo, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">auth-params</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>the host component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>the port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>path</p></td>
<td class="parameter_description">
<p>the path component</p>
<p>Passed as <code class="code">path</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>query</p></td>
<td class="parameter_description">
<p>the query component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">query</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fragment</p></td>
<td class="parameter_description">
<p>the fragment, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">fragment</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.18"></a><h3>uri:error-quark</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:error-quark))
</pre></div>
<p>Undocumented</p>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.19"></a><h3>uri:escape-bytes</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:escape-bytes unescaped reserved-chars-allowed))
</pre></div>
<p>Escapes arbitrary data for use in a URI.
</p>
<p>Normally all characters that are not ‘unreserved’ (i.e. ASCII
alphanumerical characters plus dash, dot, underscore and tilde) are
escaped. But if you specify characters in <em class="parameter"><code>reserved_chars_allowed</code></em>
they are not escaped. This is useful for the ‘reserved’ characters
in the URI specification, since those are allowed unescaped in some
portions of a URI.
</p>
<p>Though technically incorrect, this will also allow escaping nul
bytes as <code class="code">%</code><code class="code">00</code>.</p>
<div class="refsect3">
<a name="id-1.1.78.3.19.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>unescaped</p></td>
<td class="parameter_description">
<p>the unescaped input data.</p>
<p>Passed as <code class="code">unescaped</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>the length of <em class="parameter"><code>unescaped</code></em></p>
<p>Inferred from <code class="code">unescaped</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>reserved_chars_allowed</p></td>
<td class="parameter_description">
<p>a string of reserved
  characters that are allowed to be used, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">reserved-chars-allowed</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.20"></a><h3>uri:escape-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri:escape-string unescaped reserved-chars-allowed allow-utf8))
</pre></div>
<p>Escapes a string for use in a URI.
</p>
<p>Normally all characters that are not "unreserved" (i.e. ASCII
alphanumerical characters plus dash, dot, underscore and tilde) are
escaped. But if you specify characters in <em class="parameter"><code>reserved_chars_allowed</code></em>
they are not escaped. This is useful for the "reserved" characters
in the URI specification, since those are allowed unescaped in some
portions of a URI.</p>
<div class="refsect3">
<a name="id-1.1.78.3.20.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>unescaped</p></td>
<td class="parameter_description">
<p>the unescaped input string.</p>
<p>Passed as <code class="code">unescaped</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>reserved_chars_allowed</p></td>
<td class="parameter_description">
<p>a string of reserved
  characters that are allowed to be used, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">reserved-chars-allowed</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>allow_utf8</p></td>
<td class="parameter_description">
<p><code class="constant">TRUE</code> if the result can include UTF-8 characters.</p>
<p>Passed as <code class="code">allow-utf8</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.21"></a><h3>uri:is-valid?</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:is-valid? uri-string flags))
</pre></div>
<p>Parses <em class="parameter"><code>uri_string</code></em> according to <em class="parameter"><code>flags</code></em>, to determine whether it is a valid
[absolute URI][relative-absolute-uris], i.e. it does not need to be resolved
relative to another URI using <code class="function">g_uri_parse_relative()</code>.
</p>
<p>If it’s not a valid URI, an error is returned explaining how it’s invalid.
</p>
<p>See <code class="function">g_uri_split()</code>, and the definition of <span class="type">GUriFlags</span>, for more
information on the effect of <em class="parameter"><code>flags</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.78.3.21.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>uri_string</p></td>
<td class="parameter_description">
<p>a string containing an absolute URI</p>
<p>Passed as <code class="code">uri-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags for parsing <em class="parameter"><code>uri_string</code></em></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.22"></a><h3>uri:join</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri:join flags scheme userinfo host port path query fragment))
</pre></div>
<p>Joins the given components together according to <em class="parameter"><code>flags</code></em> to create
an absolute URI string. <em class="parameter"><code>path</code></em> may not be <code class="constant">NULL</code> (though it may be the empty
string).
</p>
<p>When <em class="parameter"><code>host</code></em> is present, <em class="parameter"><code>path</code></em> must either be empty or begin with a slash (<code class="code">/</code>)
character. When <em class="parameter"><code>host</code></em> is not present, <em class="parameter"><code>path</code></em> cannot begin with two slash
   characters (<code class="code">//</code>). See
[RFC 3986, section 3](https://tools.ietf.org/html/rfc3986#section-3).
</p>
<p>See also <code class="function">g_uri_join_with_user()</code>, which allows specifying the
components of the ‘userinfo’ separately.
</p>
<p><code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> and <code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code> are ignored if set
in <em class="parameter"><code>flags</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.78.3.22.7"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing how to build the URI string</p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>the URI scheme, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>userinfo</p></td>
<td class="parameter_description">
<p>the userinfo component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">userinfo</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>the host component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>the port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>path</p></td>
<td class="parameter_description">
<p>the path component</p>
<p>Passed as <code class="code">path</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>query</p></td>
<td class="parameter_description">
<p>the query component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">query</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fragment</p></td>
<td class="parameter_description">
<p>the fragment, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">fragment</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.23"></a><h3>uri:join-with-user</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri:join-with-user
    flags
    scheme
    user
    password
    auth-params
    host
    port
    path
    query
    fragment))
</pre></div>
<p>Joins the given components together according to <em class="parameter"><code>flags</code></em> to create
an absolute URI string. <em class="parameter"><code>path</code></em> may not be <code class="constant">NULL</code> (though it may be the empty
string).
</p>
<p>In contrast to <code class="function">g_uri_join()</code>, this allows specifying the components
of the ‘userinfo’ separately. It otherwise behaves the same.
</p>
<p><code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> and <code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code> are ignored if set
in <em class="parameter"><code>flags</code></em>.</p>
<div class="refsect3">
<a name="id-1.1.78.3.23.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing how to build the URI string</p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>the URI scheme, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user</p></td>
<td class="parameter_description">
<p>the user component of the userinfo, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">user</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>password</p></td>
<td class="parameter_description">
<p>the password component of the userinfo, or
  <code class="constant">NULL</code></p>
<p>Passed as <code class="code">password</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>auth_params</p></td>
<td class="parameter_description">
<p>the auth params of the userinfo, or
  <code class="constant">NULL</code></p>
<p>Passed as <code class="code">auth-params</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>the host component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>the port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>path</p></td>
<td class="parameter_description">
<p>the path component</p>
<p>Passed as <code class="code">path</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>query</p></td>
<td class="parameter_description">
<p>the query component, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">query</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fragment</p></td>
<td class="parameter_description">
<p>the fragment, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">fragment</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.24"></a><h3>uri:list-extract-uris</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:list-extract-uris uri-list))
</pre></div>
<p>Splits an URI list conforming to the text/uri-list
mime type defined in RFC 2483 into individual URIs,
discarding any comments. The URIs are not validated.</p>
<div class="refsect3">
<a name="id-1.1.78.3.24.4"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri_list</p></td>
<td class="parameter_description">
<p>an URI list</p>
<p>Passed as <code class="code">uri-list</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.25"></a><h3>uri:parse</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:parse uri-string flags))
</pre></div>
<p>Parses <em class="parameter"><code>uri_string</code></em> according to <em class="parameter"><code>flags</code></em>. If the result is not a
valid [absolute URI][relative-absolute-uris], it will be discarded, and an
error returned.</p>
<div class="refsect3">
<a name="id-1.1.78.3.25.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>uri_string</p></td>
<td class="parameter_description">
<p>a string representing an absolute URI</p>
<p>Passed as <code class="code">uri-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing how to parse <em class="parameter"><code>uri_string</code></em></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.26"></a><h3>uri:parse-params</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:parse-params params length separators flags))
</pre></div>
<p>Many URI schemes include one or more attribute/value pairs as part of the URI
value. This method can be used to parse them into a hash table. When an
attribute has multiple occurrences, the last value is the final returned
value. If you need to handle repeated attributes differently, use
<span class="type">GUriParamsIter</span>.
</p>
<p>The <em class="parameter"><code>params</code></em> string is assumed to still be <code class="code">%</code>-encoded, but the returned
values will be fully decoded. (Thus it is possible that the returned values
may contain <code class="code">=</code> or <em class="parameter"><code>separators</code></em>, if the value was encoded in the input.)
Invalid <code class="code">%</code>-encoding is treated as with the <code class="constant">G_URI_FLAGS_PARSE_RELAXED</code>
rules for <code class="function">g_uri_parse()</code>. (However, if <em class="parameter"><code>params</code></em> is the path or query string
from a <span class="type">GUri</span> that was parsed without <code class="constant">G_URI_FLAGS_PARSE_RELAXED</code> and
<code class="constant">G_URI_FLAGS_ENCODED</code>, then you already know that it does not contain any
invalid encoding.)
</p>
<p><code class="constant">G_URI_PARAMS_WWW_FORM</code> is handled as documented for <code class="function">g_uri_params_iter_init()</code>.
</p>
<p>If <code class="constant">G_URI_PARAMS_CASE_INSENSITIVE</code> is passed to <em class="parameter"><code>flags</code></em>, attributes will be
compared case-insensitively, so a params string <code class="code">attr=123&amp;Attr=456</code> will only
return a single attribute–value pair, <code class="code">Attr=456</code>. Case will be preserved in
the returned attributes.
</p>
<p>If <em class="parameter"><code>params</code></em> cannot be parsed (for example, it contains two <em class="parameter"><code>separators</code></em>
characters in a row), then <em class="parameter"><code>error</code></em> is set and <code class="constant">NULL</code> is returned.</p>
<div class="refsect3">
<a name="id-1.1.78.3.26.8"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>params</p></td>
<td class="parameter_description">
<p>a <code class="code">%</code>-encoded string containing <code class="code">attribute=value</code>
  parameters</p>
<p>Passed as <code class="code">params</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>the length of <em class="parameter"><code>params</code></em>, or <code class="code">-1</code> if it is nul-terminated</p>
<p>Passed as <code class="code">length</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>separators</p></td>
<td class="parameter_description">
<p>the separator byte character set between parameters. (usually
  <code class="code">&amp;</code>, but sometimes <code class="code">;</code> or both <code class="code">&amp;;</code>). Note that this function works on
  bytes not characters, so it can't be used to delimit UTF-8 strings for
  anything but ASCII characters. You may pass an empty set, in which case
  no splitting will occur.</p>
<p>Passed as <code class="code">separators</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags to modify the way the parameters are handled.</p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.27"></a><h3>uri:parse-scheme</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:parse-scheme uri))
</pre></div>
<p>Gets the scheme portion of a URI string.
[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
as:
</p>
<div class="informalexample"><pre class="programlisting">
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
</pre></div>
<p>Common schemes include <code class="code">file</code>, <code class="code">https</code>, <code class="code">svn+ssh</code>, etc.</p>
<div class="refsect3">
<a name="id-1.1.78.3.27.5"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a valid URI.</p>
<p>Passed as <code class="code">uri</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.28"></a><h3>uri:peek-scheme</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:peek-scheme uri))
</pre></div>
<p>Gets the scheme portion of a URI string.
[RFC 3986](https://tools.ietf.org/html/rfc3986#section-3) decodes the scheme
as:
</p>
<div class="informalexample"><pre class="programlisting">
URI = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
</pre></div>
<p>Common schemes include <code class="code">file</code>, <code class="code">https</code>, <code class="code">svn+ssh</code>, etc.
</p>
<p>Unlike <code class="function">g_uri_parse_scheme()</code>, the returned scheme is normalized to
all-lowercase and does not need to be freed.</p>
<div class="refsect3">
<a name="id-1.1.78.3.28.6"></a><h4>Parameters</h4>
<div class="informaltable"><table><tr>
<td class="parameter_name"><p>uri</p></td>
<td class="parameter_description">
<p>a valid URI.</p>
<p>Passed as <code class="code">uri</code></p>
</td>
</tr></table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.29"></a><h3>uri:resolve-relative</h3>
<div class="informalexample"><pre class="programlisting">(define-values (%return) (uri:resolve-relative base-uri-string uri-ref flags))
</pre></div>
<p>Parses <em class="parameter"><code>uri_ref</code></em> according to <em class="parameter"><code>flags</code></em> and, if it is a
[relative URI][relative-absolute-uris], resolves it relative to
<em class="parameter"><code>base_uri_string</code></em>. If the result is not a valid absolute URI, it will be
discarded, and an error returned.
</p>
<p>(If <em class="parameter"><code>base_uri_string</code></em> is <code class="constant">NULL</code>, this just returns <em class="parameter"><code>uri_ref</code></em>, or
<code class="constant">NULL</code> if <em class="parameter"><code>uri_ref</code></em> is invalid or not absolute.)</p>
<div class="refsect3">
<a name="id-1.1.78.3.29.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>base_uri_string</p></td>
<td class="parameter_description">
<p>a string representing a base URI</p>
<p>Passed as <code class="code">base-uri-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>uri_ref</p></td>
<td class="parameter_description">
<p>a string representing a relative or absolute URI</p>
<p>Passed as <code class="code">uri-ref</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags describing how to parse <em class="parameter"><code>uri_ref</code></em></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.30"></a><h3>uri:split</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return scheme userinfo host port path query fragment)
  (uri:split uri-ref flags))
</pre></div>
<p>Parses <em class="parameter"><code>uri_ref</code></em> (which can be an
[absolute or relative URI][relative-absolute-uris]) according to <em class="parameter"><code>flags</code></em>, and
returns the pieces. Any component that doesn't appear in <em class="parameter"><code>uri_ref</code></em> will be
returned as <code class="constant">NULL</code> (but note that all URIs always have a path component,
though it may be the empty string).
</p>
<p>If <em class="parameter"><code>flags</code></em> contains <code class="constant">G_URI_FLAGS_ENCODED</code>, then <code class="code">%</code>-encoded characters in
<em class="parameter"><code>uri_ref</code></em> will remain encoded in the output strings. (If not,
then all such characters will be decoded.) Note that decoding will
only work if the URI components are ASCII or UTF-8, so you will
need to use <code class="constant">G_URI_FLAGS_ENCODED</code> if they are not.
</p>
<p>Note that the <code class="constant">G_URI_FLAGS_HAS_PASSWORD</code> and
<code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code> <em class="parameter"><code>flags</code></em> are ignored by <code class="function">g_uri_split()</code>,
since it always returns only the full userinfo; use
<code class="function">g_uri_split_with_user()</code> if you want it split up.</p>
<div class="refsect3">
<a name="id-1.1.78.3.30.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>uri_ref</p></td>
<td class="parameter_description">
<p>a string containing a relative or absolute URI</p>
<p>Passed as <code class="code">uri-ref</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags for parsing <em class="parameter"><code>uri_ref</code></em></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>on return, contains
   the scheme (converted to lowercase), or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>userinfo</p></td>
<td class="parameter_description">
<p>on return, contains
   the userinfo, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">userinfo</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>on return, contains the
   host, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>on return, contains the
   port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>path</p></td>
<td class="parameter_description">
<p>on return, contains the
   path</p>
<p>Passed as <code class="code">path</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>query</p></td>
<td class="parameter_description">
<p>on return, contains the
   query, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">query</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fragment</p></td>
<td class="parameter_description">
<p>on return, contains
   the fragment, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">fragment</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.31"></a><h3>uri:split-network</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return scheme host port)
  (uri:split-network uri-string flags))
</pre></div>
<p>Parses <em class="parameter"><code>uri_string</code></em> (which must be an [absolute URI][relative-absolute-uris])
according to <em class="parameter"><code>flags</code></em>, and returns the pieces relevant to connecting to a host.
See the documentation for <code class="function">g_uri_split()</code> for more details; this is
mostly a wrapper around that function with simpler arguments.
However, it will return an error if <em class="parameter"><code>uri_string</code></em> is a relative URI,
or does not contain a hostname component.</p>
<div class="refsect3">
<a name="id-1.1.78.3.31.4"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>uri_string</p></td>
<td class="parameter_description">
<p>a string containing an absolute URI</p>
<p>Passed as <code class="code">uri-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags for parsing <em class="parameter"><code>uri_string</code></em></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>on return, contains
   the scheme (converted to lowercase), or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>on return, contains the
   host, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>on return, contains the
   port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.32"></a><h3>uri:split-with-user</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return scheme user password auth-params host port path query fragment)
  (uri:split-with-user uri-ref flags))
</pre></div>
<p>Parses <em class="parameter"><code>uri_ref</code></em> (which can be an
[absolute or relative URI][relative-absolute-uris]) according to <em class="parameter"><code>flags</code></em>, and
returns the pieces. Any component that doesn't appear in <em class="parameter"><code>uri_ref</code></em> will be
returned as <code class="constant">NULL</code> (but note that all URIs always have a path component,
though it may be the empty string).
</p>
<p>See <code class="function">g_uri_split()</code>, and the definition of <span class="type">GUriFlags</span>, for more
information on the effect of <em class="parameter"><code>flags</code></em>. Note that <em class="parameter"><code>password</code></em> will only
be parsed out if <em class="parameter"><code>flags</code></em> contains <code class="constant">G_URI_FLAGS_HAS_PASSWORD</code>, and
<em class="parameter"><code>auth_params</code></em> will only be parsed out if <em class="parameter"><code>flags</code></em> contains
<code class="constant">G_URI_FLAGS_HAS_AUTH_PARAMS</code>.</p>
<div class="refsect3">
<a name="id-1.1.78.3.32.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>uri_ref</p></td>
<td class="parameter_description">
<p>a string containing a relative or absolute URI</p>
<p>Passed as <code class="code">uri-ref</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>flags</p></td>
<td class="parameter_description">
<p>flags for parsing <em class="parameter"><code>uri_ref</code></em></p>
<p>Passed as <code class="code">flags</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>scheme</p></td>
<td class="parameter_description">
<p>on return, contains
   the scheme (converted to lowercase), or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">scheme</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>user</p></td>
<td class="parameter_description">
<p>on return, contains
   the user, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">user</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>password</p></td>
<td class="parameter_description">
<p>on return, contains
   the password, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">password</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>auth_params</p></td>
<td class="parameter_description">
<p>on return, contains
   the auth_params, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">auth-params</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>host</p></td>
<td class="parameter_description">
<p>on return, contains the
   host, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">host</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>port</p></td>
<td class="parameter_description">
<p>on return, contains the
   port, or <code class="code">-1</code></p>
<p>Passed as <code class="code">port</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>path</p></td>
<td class="parameter_description">
<p>on return, contains the
   path</p>
<p>Passed as <code class="code">path</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>query</p></td>
<td class="parameter_description">
<p>on return, contains the
   query, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">query</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>fragment</p></td>
<td class="parameter_description">
<p>on return, contains
   the fragment, or <code class="constant">NULL</code></p>
<p>Passed as <code class="code">fragment</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.33"></a><h3>uri:unescape-bytes</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri:unescape-bytes escaped-string length illegal-characters))
</pre></div>
<p>Unescapes a segment of an escaped string as binary data.
</p>
<p>Note that in contrast to <code class="function">g_uri_unescape_string()</code>, this does allow
nul bytes to appear in the output.
</p>
<p>If any of the characters in <em class="parameter"><code>illegal_characters</code></em> appears as an escaped
character in <em class="parameter"><code>escaped_string</code></em>, then that is an error and <code class="constant">NULL</code> will be
returned. This is useful if you want to avoid for instance having a slash
being expanded in an escaped path element, which might confuse pathname
handling.</p>
<div class="refsect3">
<a name="id-1.1.78.3.33.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>escaped_string</p></td>
<td class="parameter_description">
<p>A URI-escaped string</p>
<p>Passed as <code class="code">escaped-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>length</p></td>
<td class="parameter_description">
<p>the length (in bytes) of <em class="parameter"><code>escaped_string</code></em> to escape, or <code class="code">-1</code> if it
  is nul-terminated.</p>
<p>Passed as <code class="code">length</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>illegal_characters</p></td>
<td class="parameter_description">
<p>a string of illegal characters
  not to be allowed, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">illegal-characters</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.34"></a><h3>uri:unescape-segment</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri:unescape-segment escaped-string escaped-string-end illegal-characters))
</pre></div>
<p>Unescapes a segment of an escaped string.
</p>
<p>If any of the characters in <em class="parameter"><code>illegal_characters</code></em> or the NUL
character appears as an escaped character in <em class="parameter"><code>escaped_string</code></em>, then
that is an error and <code class="constant">NULL</code> will be returned. This is useful if you
want to avoid for instance having a slash being expanded in an
escaped path element, which might confuse pathname handling.
</p>
<p>Note: <code class="code">NUL</code> byte is not accepted in the output, in contrast to
<code class="function">g_uri_unescape_bytes()</code>.</p>
<div class="refsect3">
<a name="id-1.1.78.3.34.6"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>escaped_string</p></td>
<td class="parameter_description">
<p>A string, may be <code class="constant">NULL</code></p>
<p>Passed as <code class="code">escaped-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>escaped_string_end</p></td>
<td class="parameter_description">
<p>Pointer to end of <em class="parameter"><code>escaped_string</code></em>,
  may be <code class="constant">NULL</code></p>
<p>Passed as <code class="code">escaped-string-end</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>illegal_characters</p></td>
<td class="parameter_description">
<p>An optional string of illegal
  characters not to be allowed, may be <code class="constant">NULL</code></p>
<p>Passed as <code class="code">illegal-characters</code></p>
</td>
</tr>
</table></div>
</div>
</div>
<div class="refsect2">
<a name="id-1.1.78.3.35"></a><h3>uri:unescape-string</h3>
<div class="informalexample"><pre class="programlisting">(define-values
  (%return)
  (uri:unescape-string escaped-string illegal-characters))
</pre></div>
<p>Unescapes a whole escaped string.
</p>
<p>If any of the characters in <em class="parameter"><code>illegal_characters</code></em> or the NUL
character appears as an escaped character in <em class="parameter"><code>escaped_string</code></em>, then
that is an error and <code class="constant">NULL</code> will be returned. This is useful if you
want to avoid for instance having a slash being expanded in an
escaped path element, which might confuse pathname handling.</p>
<div class="refsect3">
<a name="id-1.1.78.3.35.5"></a><h4>Parameters</h4>
<div class="informaltable"><table>
<tr>
<td class="parameter_name"><p>escaped_string</p></td>
<td class="parameter_description">
<p>an escaped string to be unescaped.</p>
<p>Passed as <code class="code">escaped-string</code></p>
</td>
</tr>
<tr>
<td class="parameter_name"><p>illegal_characters</p></td>
<td class="parameter_description">
<p>a string of illegal characters
  not to be allowed, or <code class="constant">NULL</code>.</p>
<p>Passed as <code class="code">illegal-characters</code></p>
</td>
</tr>
</table></div>
</div>
</div>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.33.1</div>
</body>
</html>