Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / libxml2 / d433046ae52b0488a9fad77d2045c0139b8cada8 / . / doc / html / libxml-uri.html
blob: 9949fc2f0af05ef04dfe14ec67c7544922bfb59b [file] [log] [blame]
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame^]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
2<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">
3 .synopsis, .classsynopsis {
4 background: #eeeeee;
5 border: solid 1px #aaaaaa;
6 padding: 0.5em;
7 }
8 .programlisting {
9 background: #eeeeff;
10 border: solid 1px #aaaaff;
11 padding: 0.5em;
12 }
13 .variablelist {
14 padding: 4px;
15 margin-left: 3em;
16 }
17 .navigation {
18 background: #ffeeee;
19 border: solid 1px #ffaaaa;
20 margin-top: 0.5em;
21 margin-bottom: 0.5em;
22 }
23 .navigation a {
24 color: #770000;
25 }
26 .navigation a:visited {
27 color: #550000;
28 }
29 .navigation .title {
30 font-size: 200%;
31 }
32 </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]33
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame^]34
35
36struct <a href="libxml-uri.html#xmlURI">xmlURI</a>;
37typedef <a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a>;
38<a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> <a href="libxml-uri.html#xmlCreateURI">xmlCreateURI</a> (void);
39<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,
40 const <a href="libxml-tree.html#xmlChar">xmlChar</a> *base);
41<a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> <a href="libxml-uri.html#xmlParseURI">xmlParseURI</a> (const char *str);
42int <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]43 const char *str);
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame^]44<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);
45void <a href="libxml-uri.html#xmlPrintURI">xmlPrintURI</a> (<GTKDOCLINK xmlns="http://www.w3.org/TR/xhtml1/transitional" HREF="FILE-CAPS">FILE</GTKDOCLINK> *stream,
46 <a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> uri);
47<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,
48 const <a href="libxml-tree.html#xmlChar">xmlChar</a> *list);
49char* <a href="libxml-uri.html#xmlURIUnescapeString">xmlURIUnescapeString</a> (const char *str,
Daniel Veillardb732a0e2000-10-15 11:27:01 +0000[diff] [blame]50 int len,
51 char *target);
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame^]52int <a href="libxml-uri.html#xmlNormalizeURIPath">xmlNormalizeURIPath</a> (char *path);
53<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);
54void <a href="libxml-uri.html#xmlFreeURI">xmlFreeURI</a> (<a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> uri);
55<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);
56</pre></div><div class="refsect1" lang="en"><h2>Description</h2><p>
57
58</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]59 char *scheme; /* the URI scheme */
60 char *opaque; /* opaque part */
61 char *authority; /* the authority part */
62 char *server; /* the server part */
63 char *user; /* the user part */
64 int port; /* the port number */
65 char *path; /* the path string */
66 char *query; /* the query string */
67 char *fragment; /* the fragment identifier */
68 int cleanup; /* parsing potentially unclean URI */
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame^]69};
70</pre><p>
71A parsed URI reference. This is a struct containing the various fields
72as described in RFC 2396 but separated for further processing.</p><p>
73
74</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;
75</pre><p>
76
77</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>
78Simply creates an empty xmlURI</p><p>
79
80</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
81</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,
82 const <a href="libxml-tree.html#xmlChar">xmlChar</a> *base);</pre><p>
83Computes he final URI of the reference done by checking that
Daniel Veillardb732a0e2000-10-15 11:27:01 +0000[diff] [blame]84the given URI is valid, and building the final URI using the
85base URI. This is processed according to section 5.2 of the
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame^]86RFC 2396
87</p><p>
885.2. Resolving Relative References to Absolute Form</p><p>
89
90</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
91</td></tr><tr><td><span class="term"><i><tt>base</tt></i> :</span></td><td> the base value
92</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
93 of error.
94</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>
95Parse an URI
96</p><p>
97URI-reference = [ absoluteURI | relativeURI ] [ &quot;#&quot; fragment ]</p><p>
98
99</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
100</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
101</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,
102 const char *str);</pre><p>
103Parse an URI reference string and fills in the appropriate fields
104of the <i><tt>uri</tt></i> structure
105</p><p>
106URI-reference = [ absoluteURI | relativeURI ] [ &quot;#&quot; fragment ]</p><p>
107
108</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
109</td></tr><tr><td><span class="term"><i><tt>str</tt></i> :</span></td><td> the string to analyze
110</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>0 or the error code
111</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>
112Save the URI as an escaped string</p><p>
113
114</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
115</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)
116</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,
117 <a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> uri);</pre><p>
118Prints the URI in the stream <i><tt>steam</tt></i>.</p><p>
119
120</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
121</td></tr><tr><td><span class="term"><i><tt>uri</tt></i> :</span></td><td> pointer to an xmlURI
122</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,
123 const <a href="libxml-tree.html#xmlChar">xmlChar</a> *list);</pre><p>
124This routine escapes a string to hex, ignoring reserved characters (a-z)
125and the characters in the exception list.</p><p>
126
127</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
128</td></tr><tr><td><span class="term"><i><tt>list</tt></i> :</span></td><td> exception list string of chars not to escape
129</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.
130</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]131 int len,
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame^]132 char *target);</pre><p>
133Unescaping routine, does not do validity checks !
134Output is direct unsigned char translation of <tt>XX</tt> values (no encoding)</p><p>
135
136</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
137</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)
138</td></tr><tr><td><span class="term"><i><tt>target</tt></i> :</span></td><td> optional destination buffer
139</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>an copy of the string, but unescaped
140</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>
141Applies the 5 normalization steps to a path string--that is, RFC 2396
142Section 5.2, steps 6.c through 6.g.
143</p><p>
144Normalization occurs directly on the string, no new allocation is done</p><p>
145
146</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
147</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>0 or an error code
148</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>
149Escaping routine, does not do validity checks !
Daniel Veillard28929b22000-11-13 18:22:49 +0000[diff] [blame]150It will try to escape the chars needing this, but this is heuristic
Daniel Veillardd4330462003-04-29 12:40:16 +0000[diff] [blame^]151based it's impossible to be sure.</p><p>
152
153</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
154</td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>an copy of the string, but escaped
155
15625 May 2001
157Uses xmlParseURI and xmlURIEscapeStr to try to escape correctly
158according to RFC2396.
159 - Carl Douglas
160</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>
161Free up the xmlURI struct</p><p>
162
163</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
164</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>
165Constructs a canonic path from the specified path.</p><p>
166
167</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
168</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
169construction fails. The caller is responsible for freeing the memory occupied
170by the returned string. If there is insufficient memory available, or the
171argument is NULL, the function returns NULL.
172</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>