Action against software patentsGnome2 LogoW3C LogoRed Hat Logo
Made with Libxml2 Logo

Module uri from libxml2

API Menu
API Indexes
Related links

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)
xmlURIPtr	xmlParseURIRaw		(const char * str, 
int raw)
int	xmlParseURIReference		(xmlURIPtr uri, 
const char * str)
xmlChar *	xmlPathToURI		(const xmlChar * path)
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 (deprecated - use with char * fragment : the fragment identifier int cleanup : parsing potentially unclean URI char * query_raw : the query string (as it appears in the }

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 based on RFC 3986 URI-reference = [ absoluteURI | relativeURI ] [ "#" fragment ]

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

Function: xmlParseURIRaw

xmlURIPtr	xmlParseURIRaw		(const char * str, 
int raw)

Parse an URI but allows to keep intact the original fragments. URI-reference = URI / relative-ref

str:the URI string to analyze
raw:if 1 unescaping of URI pieces are disabled
Returns:a newly built xmlURIPtr or NULL in case of error

Function: xmlParseURIReference

int	xmlParseURIReference		(xmlURIPtr uri, 
const char * str)

Parse an URI reference string based on RFC 3986 and fills in the appropriate fields of the @uri structure URI-reference = URI / relative-ref

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

Function: xmlPathToURI

xmlChar *	xmlPathToURI		(const xmlChar * path)

Constructs an URI expressing the existing path

path:the resource locator in a filesystem notation
Returns:a new URI, 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: xmlPrintURI

void	xmlPrintURI			(FILE * stream, 
xmlURIPtr uri)

Prints the URI in the stream @stream.

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, but does not check that the string is an URI. The output is a direct unsigned char translation of %XX values (no encoding) Note that the length of the result can only be smaller or same size as the input string.

str:the string to unescape
len:the length in bytes to unescape (or <= 0 to indicate full string)
target:optional destination buffer
Returns:a copy of the string, but unescaped, will return NULL only in case of error

Daniel Veillard