libxml2/doc/html/libxml-uri.html

   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">
   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         }
  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">
  32
  33
  34
  35 struct      <a href="libxml-uri.html#xmlURI">xmlURI</a>;
  36 typedef     <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);
  41 int         <a href="libxml-uri.html#xmlParseURIReference">xmlParseURIReference</a>            (<a href="libxml-uri.html#xmlURIPtr">xmlURIPtr</a> uri,
  42                                              const char *str);
  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);
  44 void        <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);
  48 char*       <a href="libxml-uri.html#xmlURIUnescapeString">xmlURIUnescapeString</a>            (const char *str,
  49                                              int len,
  50                                              char *target);
  51 int         <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);
  53 void        <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 {
  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 */
  68 };
  69 </pre><p>
  70 A parsed URI reference. This is a struct containing the various fields
  71 as described in RFC 2396 but separated for further processing.</p><p>
  72
  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>
  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>
  77 Simply creates an empty xmlURI</p><p>
  78
  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
  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>
  82 Computes he final URI of the reference done by checking that
  83 the given URI is valid, and building the final URI using the
  84 base URI. This is processed according to section 5.2 of the
  85 RFC 2396
  86 </p><p>
  87 5.2. Resolving Relative References to Absolute Form</p><p>
  88
  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
  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.
  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>
  94 Parse an URI
  95 </p><p>
  96 URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]</p><p>
  97
  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
  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
 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>
 102 Parse an URI reference string and fills in the appropriate fields
 103 of the <i><tt>uri</tt></i> structure
 104 </p><p>
 105 URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]</p><p>
 106
 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
 109 </td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>0 or the error code
 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>
 111 Save the URI as an escaped string</p><p>
 112
 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
 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)
 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>
 117 Prints the URI in the stream <i><tt>steam</tt></i>.</p><p>
 118
 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
 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>
 123 This routine escapes a string to hex, ignoring reserved characters (a-z)
 124 and the characters in the exception list.</p><p>
 125
 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
 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.
 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,
 130                                              int len,
 131                                              char *target);</pre><p>
 132 Unescaping routine, does not do validity checks !
 133 Output is direct unsigned char translation of <tt>XX</tt> values (no encoding)</p><p>
 134
 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
 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
 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>
 140 Applies the 5 normalization steps to a path string--that is, RFC 2396
 141 Section 5.2, steps 6.c through 6.g.
 142 </p><p>
 143 Normalization occurs directly on the string, no new allocation is done</p><p>
 144
 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
 146 </td></tr><tr><td><span class="term"><span class="emphasis"><em>Returns</em></span> :</span></td><td>0 or an error code
 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>
 148 Escaping routine, does not do validity checks !
 149 It will try to escape the chars needing this, but this is heuristic
 150 based it's impossible to be sure.</p><p>
 151
 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
 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
 154
 155 25 May 2001
 156 Uses xmlParseURI and xmlURIEscapeStr to try to escape correctly
 157 according to RFC2396.
 158   - Carl Douglas
 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>
 160 Free up the xmlURI struct</p><p>
 161
 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
 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>
 164 Constructs a canonic path from the specified path.</p><p>
 165
 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
 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
 168 construction fails. The caller is responsible for freeing the memory occupied
 169 by the returned string. If there is insufficient memory available, or the
 170 argument is NULL, the function returns NULL.
 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>