libxml2: uri.h File Reference

libxml2

Loading...
Searching...
No Matches
Data Structures | Typedefs | Functions
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
xmlURI * | xmlCreateURI (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.
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.
int | xmlBuildRelativeURISafe (const xmlChar *URI, const xmlChar *base, xmlChar **out)
| Expresses the URI of the reference in terms relative to the base.
xmlChar * | xmlBuildRelativeURI (const xmlChar *URI, const xmlChar *base)
| See xmlBuildRelativeURISafe.
xmlURI * | xmlParseURI (const char *str)
| Parse an URI based on RFC 3986.
int | xmlParseURISafe (const char *str, xmlURI **uri)
| Parse an URI based on RFC 3986.
xmlURI * | xmlParseURIRaw (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.
xmlChar * | xmlSaveUri (xmlURI *uri)
| Save the URI as an escaped string.
void | xmlPrintURI (FILE *stream, xmlURI *uri)
| Prints the URI in the stream stream.
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.
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.
xmlChar * | xmlURIEscape (const xmlChar *str)
| Escaping routine, does not do validity checks !
void | xmlFreeURI (xmlURI *uri)
| Free up the xmlURI struct.
xmlChar * | xmlCanonicPath (const xmlChar *path)
| Prepares a path.
xmlChar * | xmlPathToURI (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

Copyright
  See Copyright for the status of this software.

Author
  Daniel Veillard

## Function Documentation

## ◆ xmlBuildRelativeURI()

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

See xmlBuildRelativeURISafe.

Parameters

  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.

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

  URI | the URI reference under consideration
  base | the base value
  valPtr | pointer 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

  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.

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

  URI | the URI instance found in the document
  base | the base value
  valPtr | pointer 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

  path | the 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

  uri | pointer 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

  path | pointer 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

  str | the 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

  str | the URI string to analyze
  raw | if 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

  uri | pointer to an URI structure
  str | the 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

  str | the URI string to analyze
  uriOut | optional 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

  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.

## ◆ xmlPrintURI()

void xmlPrintURI | ( | FILE * | stream,
|  | xmlURI * | uri )

Prints the URI in the stream stream.

Parameters

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

## ◆ xmlSaveUri()

xmlChar * xmlSaveUri | ( | xmlURI * | uri | ) |

Save the URI as an escaped string.

Parameters

  uri | pointer 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

    str | the 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

  str | string to escape
  list | exception 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

  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