libxml2
Loading...
Searching...
No Matches
uri.h File Reference

library of generic URI related routines More...

Data Structures

struct  _xmlURI
 A parsed URI reference. More...

Typedefs

typedef struct _xmlURI xmlURI
 Parsed URI.

Functions

xmlURIxmlCreateURI (void)
 Simply creates an empty xmlURI.
int xmlBuildURISafe (const xmlChar *URI, const xmlChar *base, xmlChar **out)
 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.
xmlCharxmlBuildURI (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.
int xmlBuildRelativeURISafe (const xmlChar *URI, const xmlChar *base, xmlChar **out)
 Expresses the URI of the reference in terms relative to the base.
xmlCharxmlBuildRelativeURI (const xmlChar *URI, const xmlChar *base)
 See xmlBuildRelativeURISafe.
xmlURIxmlParseURI (const char *str)
 Parse an URI based on RFC 3986.
int xmlParseURISafe (const char *str, xmlURI **uri)
 Parse an URI based on RFC 3986.
xmlURIxmlParseURIRaw (const char *str, int raw)
 Parse an URI but allows to keep intact the original fragments.
int xmlParseURIReference (xmlURI *uri, const char *str)
 Parse an URI reference string based on RFC 3986 and fills in the appropriate fields of the uri structure.
xmlCharxmlSaveUri (xmlURI *uri)
 Save the URI as an escaped string.
void xmlPrintURI (FILE *stream, xmlURI *uri)
 Prints the URI in the stream stream.
xmlCharxmlURIEscapeStr (const xmlChar *str, const xmlChar *list)
 This routine escapes a string to hex, ignoring unreserved characters a-z, A-Z, 0-9, "-._~", a few sub-delims "!*'()", the gen-delim "@" (why?) and the characters in the exception list.
char * xmlURIUnescapeString (const char *str, int len, char *target)
 Unescaping routine, but does not check that the string is an URI.
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.
xmlCharxmlURIEscape (const xmlChar *str)
 Escaping routine, does not do validity checks !
void xmlFreeURI (xmlURI *uri)
 Free up the xmlURI struct.
xmlCharxmlCanonicPath (const xmlChar *path)
 Prepares a path.
xmlCharxmlPathToURI (const xmlChar *path)
 Constructs an URI expressing the existing path.

Detailed Description

library of generic URI related routines

library of generic URI related routines Implements RFC 2396

Author
Daniel Veillard

Function Documentation

◆ xmlBuildRelativeURI()

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

See xmlBuildRelativeURISafe.

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

◆ xmlBuildRelativeURISafe()

int xmlBuildRelativeURISafe ( const xmlChar * URI,
const xmlChar * base,
xmlChar ** valPtr )

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
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
Since
2.13.0
Parameters
URIthe URI reference under consideration
basethe base value
valPtrpointer to result URI
Returns
0 on success, -1 if a memory allocation failed or an error code if URI or base are invalid.

◆ 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

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

◆ xmlBuildURISafe()

int xmlBuildURISafe ( const xmlChar * URI,
const xmlChar * base,
xmlChar ** valPtr )

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

Since
2.13.0
Parameters
URIthe URI instance found in the document
basethe base value
valPtrpointer to result URI
Returns
0 on success, -1 if a memory allocation failed or an error code if URI or base are invalid.

◆ xmlCanonicPath()

xmlChar * xmlCanonicPath ( const xmlChar * path)

Prepares a path.

If the path contains the substring "://", it is considered a Legacy Extended IRI. Characters which aren't allowed in URIs are escaped.

Otherwise, the path is considered a filesystem path which is copied without modification.

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.

Parameters
paththe resource locator in a filesystem notation
Returns
the escaped path.

◆ xmlCreateURI()

xmlURI * xmlCreateURI ( void )

Simply creates an empty xmlURI.

Returns
the new structure or NULL in case of error

◆ xmlFreeURI()

void xmlFreeURI ( xmlURI * uri)

Free up the xmlURI struct.

Parameters
uripointer to an xmlURI

◆ 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

Parameters
pathpointer to the path string
Returns
0 or an error code

◆ xmlParseURI()

xmlURI * xmlParseURI ( const char * str)

Parse an URI based on RFC 3986.

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

Parameters
strthe URI string to analyze
Returns
a newly built xmlURI or NULL in case of error

◆ xmlParseURIRaw()

xmlURI * xmlParseURIRaw ( const char * str,
int raw )

Parse an URI but allows to keep intact the original fragments.

URI-reference = URI / relative-ref

Parameters
strthe URI string to analyze
rawif 1 unescaping of URI pieces are disabled
Returns
a newly built xmlURI or NULL in case of error

◆ xmlParseURIReference()

int xmlParseURIReference ( xmlURI * 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

Parameters
uripointer to an URI structure
strthe string to analyze
Returns
0 or the error code

◆ xmlParseURISafe()

int xmlParseURISafe ( const char * str,
xmlURI ** uriOut )

Parse an URI based on RFC 3986.

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

Since
2.13.0
Parameters
strthe URI string to analyze
uriOutoptional pointer to parsed URI
Returns
0 on success, an error code (typically 1) if the URI is invalid or -1 if a memory allocation failed.

◆ xmlPathToURI()

xmlChar * xmlPathToURI ( const xmlChar * path)

Constructs an URI expressing the existing path.

Parameters
paththe 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.

◆ xmlPrintURI()

void xmlPrintURI ( FILE * stream,
xmlURI * uri )

Prints the URI in the stream stream.

Parameters
streama FILE* for the output
uripointer to an xmlURI

◆ xmlSaveUri()

xmlChar * xmlSaveUri ( xmlURI * uri)

Save the URI as an escaped string.

Parameters
uripointer to an xmlURI
Returns
a new string (to be deallocated by caller)

◆ 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.

25 May 2001 Uses xmlParseURI and xmlURIEscapeStr to try to escape correctly according to RFC2396.

  • Carl Douglas
    Parameters
    strthe string of the URI to escape
    Returns
    an copy of the string, but escaped

◆ xmlURIEscapeStr()

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

This routine escapes a string to hex, ignoring unreserved characters a-z, A-Z, 0-9, "-._~", a few sub-delims "!*'()", the gen-delim "@" (why?) and the characters in the exception list.

Parameters
strstring to escape
listexception list string of chars not to escape
Returns
a new escaped string or NULL in case of error.

◆ 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.

Parameters
strthe string to unescape
lenthe length in bytes to unescape (or <= 0 to indicate full string)
targetoptional destination buffer
Returns
a copy of the string, but unescaped, will return NULL only in case of error