#

## Module uri from libxml2

API Menu

- Main Menu
- Developer Menu
- Code Examples
- API Menu
- Parser API
- Tree API
- Reader API
- XML Guidelines
- ChangeLog

API Indexes

- Alphabetic
- Constructors
- Functions/Types
- Modules
- Symbols

Related links

- Mail archive
- XSLT libxslt
- DOM gdome2
- XML-DSig xmlsec
- FTP
- Windows binaries
- Solaris binaries
- MacOsX binaries
- Pascal bindings
- Bug Tracker

library of generic URI related routines Implements RFC 2396

## Table of Contents

    Structure xmlURI
    struct _xmlURI

    Typedef xmlURI * xmlURIPtr

    xmlChar *	xmlBuildRelativeURI	(const xmlChar * URI,
    					 const xmlChar * base)

    xmlChar *	xmlBuildURI		(const xmlChar * URI,
    					 const xmlChar * base)

    xmlChar *	xmlCanonicPath		(const xmlChar * path)

    xmlURIPtr	xmlCreateURI		(void)

    void	xmlFreeURI			(xmlURIPtr uri)

    int	xmlNormalizeURIPath		(char * path)

    xmlURIPtr	xmlParseURI		(const char * str)

    int	xmlParseURIReference		(xmlURIPtr uri,
    					 const char * str)

    void	xmlPrintURI			(FILE * stream,
    					 xmlURIPtr uri)

    xmlChar *	xmlSaveUri		(xmlURIPtr uri)

    xmlChar *	xmlURIEscape		(const xmlChar * str)

    xmlChar *	xmlURIEscapeStr		(const xmlChar * str,
    					 const xmlChar * list)

    char *	xmlURIUnescapeString		(const char * str,
    					 int len,
    					 char * target)

## Description

### Structure xmlURI

    Structure xmlURI
    struct _xmlURI {
        char *	scheme	: the URI scheme
        char *	opaque	: opaque part
        char *	authority	: the authority part
        char *	server	: the server part
        char *	user	: the user part
        int	port	: the port number
        char *	path	: the path string
        char *	query	: the query string
        char *	fragment	: the fragment identifier
        int	cleanup	: parsing potentially unclean URI
    }

### Function: xmlBuildRelativeURI

    xmlChar *	xmlBuildRelativeURI	(const xmlChar * URI,
    					 const xmlChar * base)

Expresses the URI of the reference in terms relative to the base. Some examples of this operation include: base = "http://site1.com/docs/book1.html" URI input URI returned docs/pic1.gif pic1.gif docs/img/pic1.gif img/pic1.gif img/pic1.gif ../img/pic1.gif http://site1.com/docs/pic1.gif pic1.gif http://site2.com/docs/pic1.gif http://site2.com/docs/pic1.gif base = "docs/book1.html" URI input URI returned docs/pic1.gif pic1.gif docs/img/pic1.gif img/pic1.gif img/pic1.gif ../img/pic1.gif http://site1.com/docs/pic1.gif http://site1.com/docs/pic1.gif Note: if the URI reference is really wierd or complicated, it may be worthwhile to first convert it into a "nice" one by calling xmlBuildURI (using 'base') before calling this routine, since this routine (for reasonable efficiency) assumes URI has already been through some validation.

`URI`: | the URI reference under consideration
`base`: | the base value
`Returns`: | a new URI string (to be freed by the caller) or NULL in case error.

### Function: xmlBuildURI

    xmlChar *	xmlBuildURI		(const xmlChar * URI,
    					 const xmlChar * base)

Computes he final URI of the reference done by checking that the given URI is valid, and building the final URI using the base URI. This is processed according to section 5.2 of the RFC 2396 5.2. Resolving Relative References to Absolute Form

`URI`: | the URI instance found in the document
`base`: | the base value
`Returns`: | a new URI string (to be freed by the caller) or NULL in case of error.

### Function: xmlCanonicPath

    xmlChar *	xmlCanonicPath		(const xmlChar * path)

Constructs a canonic path from the specified path.

`path`: | the resource locator in a filesystem notation
`Returns`: | a new canonic path, or a duplicate of the path parameter if the construction fails. The caller is responsible for freeing the memory occupied by the returned string. If there is insufficient memory available, or the argument is NULL, the function returns NULL.

### Function: xmlCreateURI

    xmlURIPtr	xmlCreateURI		(void)

Simply creates an empty xmlURI

`Returns`: | the new structure or NULL in case of error

### Function: xmlFreeURI

    void	xmlFreeURI			(xmlURIPtr uri)

Free up the xmlURI struct

`uri`: | pointer to an xmlURI

### Function: xmlNormalizeURIPath

    int	xmlNormalizeURIPath		(char * path)

Applies the 5 normalization steps to a path string--that is, RFC 2396 Section 5.2, steps 6.c through 6.g. Normalization occurs directly on the string, no new allocation is done

`path`: | pointer to the path string
`Returns`: | 0 or an error code

### Function: xmlParseURI

    xmlURIPtr	xmlParseURI		(const char * str)

Parse an URI URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]

`str`: | the URI string to analyze
`Returns`: | a newly build xmlURIPtr or NULL in case of error

### Function: xmlParseURIReference

    int	xmlParseURIReference		(xmlURIPtr uri,
    					 const char * str)

Parse an URI reference string and fills in the appropriate fields of the @uri structure URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]

`uri`: | pointer to an URI structure
`str`: | the string to analyze
`Returns`: | 0 or the error code

### Function: xmlPrintURI

    void	xmlPrintURI			(FILE * stream,
    					 xmlURIPtr uri)

Prints the URI in the stream @steam.

`stream`: | a FILE* for the output
`uri`: | pointer to an xmlURI

### Function: xmlSaveUri

    xmlChar *	xmlSaveUri		(xmlURIPtr uri)

Save the URI as an escaped string

`uri`: | pointer to an xmlURI
`Returns`: | a new string (to be deallocated by caller)

### Function: xmlURIEscape

    xmlChar *	xmlURIEscape		(const xmlChar * str)

Escaping routine, does not do validity checks ! It will try to escape the chars needing this, but this is heuristic based it's impossible to be sure.

`str`: | the string of the URI to escape
`Returns`: | an copy of the string, but escaped 25 May 2001 Uses xmlParseURI and xmlURIEscapeStr to try to escape correctly according to RFC2396. - Carl Douglas

### Function: xmlURIEscapeStr

    xmlChar *	xmlURIEscapeStr		(const xmlChar * str,
    					 const xmlChar * list)

This routine escapes a string to hex, ignoring reserved characters (a-z) and the characters in the exception list.

`str`: | string to escape
`list`: | exception list string of chars not to escape
`Returns`: | a new escaped string or NULL in case of error.

### Function: xmlURIUnescapeString

    char *	xmlURIUnescapeString		(const char * str,
    					 int len,
    					 char * target)

Unescaping routine, does not do validity checks ! Output is direct unsigned char translation of %XX values (no encoding)

`str`: | the string to unescape
`len`: | the length in bytes to unescape (or <= 0 to indicate full string)
`target`: | optional destination buffer
`Returns`: | an copy of the string, but unescaped

Daniel Veillard