Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / libxml2 / 2fdbd32d514c8b9d166a80564aca3426ec9cfdb2 / . / doc / html / libxml-uri.html
blob: 8e32519a32542aad1bd8ce3d3244cd7b6e93b05f [file] [log] [blame]
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>uri</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><style xmlns="http://www.w3.org/TR/xhtml1/transitional" type="text/css">
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]2 .synopsis, .classsynopsis {
3 background: #eeeeee;
4 border: solid 1px #aaaaaa;
5 padding: 0.5em;
6 }
7 .programlisting {
8 background: #eeeeff;
9 border: solid 1px #aaaaff;
10 padding: 0.5em;
11 }
12 .variablelist {
13 padding: 4px;
14 margin-left: 3em;
15 }
16 .navigation {
17 background: #ffeeee;
18 border: solid 1px #ffaaaa;
19 margin-top: 0.5em;
20 margin-bottom: 0.5em;
21 }
22 .navigation a {
23 color: #770000;
24 }
25 .navigation a:visited {
26 color: #550000;
27 }
28 .navigation .title {
29 font-size: 200%;
30 }
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]31 </style><link rel="home" href="index.html" title="Gnome XML Library Reference Manual"><link rel="up" href="libxml-lib.html" title="Libxml Library Reference"><link rel="previous" href="libxml-relaxng.html" title="relaxng"><link rel="next" href="libxml-xmlerror.html" title="xmlerror"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navigation" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2"><tr valign="middle"><td><a accesskey="p" href="libxml-relaxng.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></img></a></td><td><a accesskey="u" href="libxml-lib.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></img></a></td><td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></img></a></td><th width="100%" align="center">Gnome XML Library Reference Manual</th><td><a accesskey="n" href="libxml-xmlerror.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></img></a></td></tr></table><div class="refentry" lang="en"><a name="libxml-uri"></a><div class="titlepage"></div><div class="refnamediv"><h2>uri</h2><p>uri &#8212; </p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
Daniel Veillardb732a0e2000-10-15 11:27:01 +0000[diff] [blame]32
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]33
34
35struct <a href="libxml-uri.html#xmlURI">xmlURI</a>;
36typedef <a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a>;
37<a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> <a href="libxml-uri.html#xmlCreateURI">xmlCreateURI</a> (void);
38<a href="libxml-tree.html#xmlChar">xmlChar</a>* <a href="libxml-uri.html#xmlBuildURI">xmlBuildURI</a> (const <a href="libxml-tree.html#xmlChar">xmlChar</a> *URI,
39 const <a href="libxml-tree.html#xmlChar">xmlChar</a> *base);
40<a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> <a href="libxml-uri.html#xmlParseURI">xmlParseURI</a> (const char *str);
41int <a href="libxml-uri.html#xmlParseURIReference">xmlParseURIReference</a> (<a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> uri,
Daniel Veillardb732a0e2000-10-15 11:27:01 +0000[diff] [blame]42 const char *str);
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]43<a href="libxml-tree.html#xmlChar">xmlChar</a>* <a href="libxml-uri.html#xmlSaveUri">xmlSaveUri</a> (<a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> uri);
44void <a href="libxml-uri.html#xmlPrintURI">xmlPrintURI</a> (<GTKDOCLINK xmlns="http://www.w3.org/TR/xhtml1/transitional" HREF="FILE-CAPS">FILE</GTKDOCLINK> *stream,
45 <a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> uri);
46<a href="libxml-tree.html#xmlChar">xmlChar</a>* <a href="libxml-uri.html#xmlURIEscapeStr">xmlURIEscapeStr</a> (const <a href="libxml-tree.html#xmlChar">xmlChar</a> *str,
47 const <a href="libxml-tree.html#xmlChar">xmlChar</a> *list);
48char* <a href="libxml-uri.html#xmlURIUnescapeString">xmlURIUnescapeString</a> (const char *str,
Daniel Veillardb732a0e2000-10-15 11:27:01 +0000[diff] [blame]49 int len,
50 char *target);
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]51int <a href="libxml-uri.html#xmlNormalizeURIPath">xmlNormalizeURIPath</a> (char *path);
52<a href="libxml-tree.html#xmlChar">xmlChar</a>* <a href="libxml-uri.html#xmlURIEscape">xmlURIEscape</a> (const <a href="libxml-tree.html#xmlChar">xmlChar</a> *str);
53void <a href="libxml-uri.html#xmlFreeURI">xmlFreeURI</a> (<a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> uri);
54<a href="libxml-tree.html#xmlChar">xmlChar</a>* <a href="libxml-uri.html#xmlCanonicPath">xmlCanonicPath</a> (const <a href="libxml-tree.html#xmlChar">xmlChar</a> *path);
55</pre></div><div class="refsect1" lang="en"><h2>Description</h2><p>
56
57</p></div><div class="refsect1" lang="en"><h2>Details</h2><div class="refsect2" lang="en"><h3><a name="xmlURI"></a>struct xmlURI</h3><pre class="programlisting">struct xmlURI {
Daniel Veillardef90ba72001-12-07 14:24:22 +0000[diff] [blame]58 char *scheme; /* the URI scheme */
59 char *opaque; /* opaque part */
60 char *authority; /* the authority part */
61 char *server; /* the server part */
62 char *user; /* the user part */
63 int port; /* the port number */
64 char *path; /* the path string */
65 char *query; /* the query string */
66 char *fragment; /* the fragment identifier */
67 int cleanup; /* parsing potentially unclean URI */
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]68};
69</pre><p>
70A parsed URI reference. This is a struct containing the various fields
71as described in RFC 2396 but separated for further processing.</p><p>
72
Daniel Veillardd7cec922003-06-13 12:30:10 +0000[diff] [blame]73</p></div><hr xmlns="http://www.w3.org/TR/xhtml1/transitional"></hr><div class="refsect2" lang="en"><h3><a name="xmlURIPtr"></a>xmlURIPtr</h3><pre class="programlisting">typedef xmlURI *xmlURIPtr;
74</pre><p>
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]75
76</p></div><hr xmlns="http://www.w3.org/TR/xhtml1/transitional"></hr><div class="refsect2" lang="en"><h3><a name="xmlCreateURI"></a>xmlCreateURI ()</h3><pre class="programlisting"><a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> xmlCreateURI (void);</pre><p>
77Simply creates an empty xmlURI</p><p>
78
Daniel Veillardd7cec922003-06-13 12:30:10 +0000[diff] [blame]79</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>the new structure or NULL in case of error
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]80</td></tr></tbody></table></div></div><hr xmlns="http://www.w3.org/TR/xhtml1/transitional"></hr><div class="refsect2" lang="en"><h3><a name="xmlBuildURI"></a>xmlBuildURI ()</h3><pre class="programlisting"><a href="libxml-tree.html#xmlChar">xmlChar</a>* xmlBuildURI (const <a href="libxml-tree.html#xmlChar">xmlChar</a> *URI,
81 const <a href="libxml-tree.html#xmlChar">xmlChar</a> *base);</pre><p>
82Computes he final URI of the reference done by checking that
Daniel Veillardb732a0e2000-10-15 11:27:01 +0000[diff] [blame]83the given URI is valid, and building the final URI using the
84base URI. This is processed according to section 5.2 of the
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]85RFC 2396
86</p><p>
875.2. Resolving Relative References to Absolute Form</p><p>
88
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]89</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i><tt>URI</tt></i> :</span></td><td> the URI instance found in the document
90</td></tr><tr><td><span class="term"><i><tt>base</tt></i> :</span></td><td> the base value
Daniel Veillardd7cec922003-06-13 12:30:10 +0000[diff] [blame]91</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>a new URI string (to be freed by the caller) or NULL in case
92 of error.
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]93</td></tr></tbody></table></div></div><hr xmlns="http://www.w3.org/TR/xhtml1/transitional"></hr><div class="refsect2" lang="en"><h3><a name="xmlParseURI"></a>xmlParseURI ()</h3><pre class="programlisting"><a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> xmlParseURI (const char *str);</pre><p>
94Parse an URI
95</p><p>
Daniel Veillardcfba2fe2003-08-15 00:33:43 +0000[diff] [blame]96URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]</p><p>
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]97
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]98</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i><tt>str</tt></i> :</span></td><td> the URI string to analyze
Daniel Veillardd7cec922003-06-13 12:30:10 +0000[diff] [blame]99</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>a newly build xmlURIPtr or NULL in case of error
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]100</td></tr></tbody></table></div></div><hr xmlns="http://www.w3.org/TR/xhtml1/transitional"></hr><div class="refsect2" lang="en"><h3><a name="xmlParseURIReference"></a>xmlParseURIReference ()</h3><pre class="programlisting">int xmlParseURIReference (<a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> uri,
101 const char *str);</pre><p>
102Parse an URI reference string and fills in the appropriate fields
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]103of the <i><tt>uri</tt></i> structure
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]104</p><p>
Daniel Veillardcfba2fe2003-08-15 00:33:43 +0000[diff] [blame]105URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]</p><p>
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]106
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]107</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i><tt>uri</tt></i> :</span></td><td> pointer to an URI structure
108</td></tr><tr><td><span class="term"><i><tt>str</tt></i> :</span></td><td> the string to analyze
Daniel Veillardd7cec922003-06-13 12:30:10 +0000[diff] [blame]109</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>0 or the error code
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]110</td></tr></tbody></table></div></div><hr xmlns="http://www.w3.org/TR/xhtml1/transitional"></hr><div class="refsect2" lang="en"><h3><a name="xmlSaveUri"></a>xmlSaveUri ()</h3><pre class="programlisting"><a href="libxml-tree.html#xmlChar">xmlChar</a>* xmlSaveUri (<a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> uri);</pre><p>
111Save the URI as an escaped string</p><p>
112
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]113</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i><tt>uri</tt></i> :</span></td><td> pointer to an xmlURI
Daniel Veillardd7cec922003-06-13 12:30:10 +0000[diff] [blame]114</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>a new string (to be deallocated by caller)
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]115</td></tr></tbody></table></div></div><hr xmlns="http://www.w3.org/TR/xhtml1/transitional"></hr><div class="refsect2" lang="en"><h3><a name="xmlPrintURI"></a>xmlPrintURI ()</h3><pre class="programlisting">void xmlPrintURI (<GTKDOCLINK xmlns="http://www.w3.org/TR/xhtml1/transitional" HREF="FILE-CAPS">FILE</GTKDOCLINK> *stream,
116 <a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> uri);</pre><p>
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]117Prints the URI in the stream <i><tt>steam</tt></i>.</p><p>
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]118
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]119</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i><tt>stream</tt></i> :</span></td><td> a FILE* for the output
120</td></tr><tr><td><span class="term"><i><tt>uri</tt></i> :</span></td><td> pointer to an xmlURI
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]121</td></tr></tbody></table></div></div><hr xmlns="http://www.w3.org/TR/xhtml1/transitional"></hr><div class="refsect2" lang="en"><h3><a name="xmlURIEscapeStr"></a>xmlURIEscapeStr ()</h3><pre class="programlisting"><a href="libxml-tree.html#xmlChar">xmlChar</a>* xmlURIEscapeStr (const <a href="libxml-tree.html#xmlChar">xmlChar</a> *str,
122 const <a href="libxml-tree.html#xmlChar">xmlChar</a> *list);</pre><p>
123This routine escapes a string to hex, ignoring reserved characters (a-z)
124and the characters in the exception list.</p><p>
125
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]126</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i><tt>str</tt></i> :</span></td><td> string to escape
127</td></tr><tr><td><span class="term"><i><tt>list</tt></i> :</span></td><td> exception list string of chars not to escape
Daniel Veillardd7cec922003-06-13 12:30:10 +0000[diff] [blame]128</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>a new escaped string or NULL in case of error.
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]129</td></tr></tbody></table></div></div><hr xmlns="http://www.w3.org/TR/xhtml1/transitional"></hr><div class="refsect2" lang="en"><h3><a name="xmlURIUnescapeString"></a>xmlURIUnescapeString ()</h3><pre class="programlisting">char* xmlURIUnescapeString (const char *str,
Daniel Veillardb732a0e2000-10-15 11:27:01 +0000[diff] [blame]130 int len,
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]131 char *target);</pre><p>
132Unescaping routine, does not do validity checks !
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]133Output is direct unsigned char translation of <tt>XX</tt> values (no encoding)</p><p>
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]134
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]135</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i><tt>str</tt></i> :</span></td><td> the string to unescape
136</td></tr><tr><td><span class="term"><i><tt>len</tt></i> :</span></td><td> the length in bytes to unescape (or &lt;= 0 to indicate full string)
137</td></tr><tr><td><span class="term"><i><tt>target</tt></i> :</span></td><td> optional destination buffer
Daniel Veillardd7cec922003-06-13 12:30:10 +0000[diff] [blame]138</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>an copy of the string, but unescaped
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]139</td></tr></tbody></table></div></div><hr xmlns="http://www.w3.org/TR/xhtml1/transitional"></hr><div class="refsect2" lang="en"><h3><a name="xmlNormalizeURIPath"></a>xmlNormalizeURIPath ()</h3><pre class="programlisting">int xmlNormalizeURIPath (char *path);</pre><p>
140Applies the 5 normalization steps to a path string--that is, RFC 2396
141Section 5.2, steps 6.c through 6.g.
142</p><p>
143Normalization occurs directly on the string, no new allocation is done</p><p>
144
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]145</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i><tt>path</tt></i> :</span></td><td> pointer to the path string
Daniel Veillardd7cec922003-06-13 12:30:10 +0000[diff] [blame]146</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>0 or an error code
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]147</td></tr></tbody></table></div></div><hr xmlns="http://www.w3.org/TR/xhtml1/transitional"></hr><div class="refsect2" lang="en"><h3><a name="xmlURIEscape"></a>xmlURIEscape ()</h3><pre class="programlisting"><a href="libxml-tree.html#xmlChar">xmlChar</a>* xmlURIEscape (const <a href="libxml-tree.html#xmlChar">xmlChar</a> *str);</pre><p>
148Escaping routine, does not do validity checks !
Daniel Veillard28929b22000-11-13 18:22:49 +0000[diff] [blame]149It will try to escape the chars needing this, but this is heuristic
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]150based it's impossible to be sure.</p><p>
151
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]152</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i><tt>str</tt></i> :</span></td><td> the string of the URI to escape
Daniel Veillardd7cec922003-06-13 12:30:10 +0000[diff] [blame]153</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>an copy of the string, but escaped
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]154
Daniel Veillardd7cec922003-06-13 12:30:10 +0000[diff] [blame]15525 May 2001
156Uses xmlParseURI and xmlURIEscapeStr to try to escape correctly
157according to RFC2396.
158 - Carl Douglas
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]159</td></tr></tbody></table></div></div><hr xmlns="http://www.w3.org/TR/xhtml1/transitional"></hr><div class="refsect2" lang="en"><h3><a name="xmlFreeURI"></a>xmlFreeURI ()</h3><pre class="programlisting">void xmlFreeURI (<a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> uri);</pre><p>
160Free up the xmlURI struct</p><p>
161
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]162</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i><tt>uri</tt></i> :</span></td><td> pointer to an xmlURI
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame]163</td></tr></tbody></table></div></div><hr xmlns="http://www.w3.org/TR/xhtml1/transitional"></hr><div class="refsect2" lang="en"><h3><a name="xmlCanonicPath"></a>xmlCanonicPath ()</h3><pre class="programlisting"><a href="libxml-tree.html#xmlChar">xmlChar</a>* xmlCanonicPath (const <a href="libxml-tree.html#xmlChar">xmlChar</a> *path);</pre><p>
164Constructs a canonic path from the specified path.</p><p>
165
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]166</p><div class="variablelist"><table border="0"><col align="left" valign="top"><tbody><tr><td><span class="term"><i><tt>path</tt></i> :</span></td><td> the resource locator in a filesystem notation
Daniel Veillardd7cec922003-06-13 12:30:10 +0000[diff] [blame]167</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>a new canonic path, or a duplicate of the path parameter if the
168construction fails. The caller is responsible for freeing the memory occupied
169by the returned string. If there is insufficient memory available, or the
170argument is NULL, the function returns NULL.
Daniel Veillard2fdbd322003-08-18 12:15:38 +0000[diff] [blame^]171</td></tr></tbody></table></div></div></div></div><table xmlns="http://www.w3.org/TR/xhtml1/transitional" class="navigation" width="100%" summary="Navigation footer" cellpadding="2" cellspacing="0"><tr valign="middle"><td align="left"><a accesskey="p" href="libxml-relaxng.html"><b>&lt;&lt; relaxng</b></a></td><td align="right"><a accesskey="n" href="libxml-xmlerror.html"><b>xmlerror &gt;&gt;</b></a></td></tr></table></body></html>