uriparser 0.8.2

- Main Page
- Data Structures
- Files

- File List
- Globals

Data Structures | Typedefs | Functions
Uri.h File Reference

## Data Structures
struct | UriTextRangeStructA
struct | UriPathSegmentStructA
struct | UriHostDataStructA
struct | UriUriStructA
struct | UriParserStateStructA
struct | UriQueryListStructA

## Typedefs
typedef struct UriTextRangeStructA | UriTextRangeA
typedef struct UriPathSegmentStructA | UriPathSegmentA
typedef struct UriHostDataStructA | UriHostDataA
typedef struct UriUriStructA | UriUriA
typedef struct UriParserStateStructA | UriParserStateA
typedef struct UriQueryListStructA | UriQueryListA

## Functions
int | uriParseUriExA (UriParserStateA *state, const char *first, const char *afterLast)
int | uriParseUriA (UriParserStateA *state, const char *text)
void | uriFreeUriMembersA (UriUriA *uri)
char * | uriEscapeExA (const char *inFirst, const char *inAfterLast, char *out, UriBool spaceToPlus, UriBool normalizeBreaks)
char * | uriEscapeA (const char *in, char *out, UriBool spaceToPlus, UriBool normalizeBreaks)
const char * | uriUnescapeInPlaceExA (char *inout, UriBool plusToSpace, UriBreakConversion breakConversion)
const char * | uriUnescapeInPlaceA (char *inout)
int | uriAddBaseUriA (UriUriA *absoluteDest, const UriUriA *relativeSource, const UriUriA *absoluteBase)
int | uriAddBaseUriExA (UriUriA *absoluteDest, const UriUriA *relativeSource, const UriUriA *absoluteBase, UriResolutionOptions options)
int | uriRemoveBaseUriA (UriUriA *dest, const UriUriA *absoluteSource, const UriUriA *absoluteBase, UriBool domainRootMode)
UriBool | uriEqualsUriA (const UriUriA *a, const UriUriA *b)
int | uriToStringCharsRequiredA (const UriUriA *uri, int *charsRequired)
int | uriToStringA (char *dest, const UriUriA *uri, int maxChars, int *charsWritten)
unsigned int | uriNormalizeSyntaxMaskRequiredA (const UriUriA *uri)
int | uriNormalizeSyntaxExA (UriUriA *uri, unsigned int mask)
int | uriNormalizeSyntaxA (UriUriA *uri)
int | uriUnixFilenameToUriStringA (const char *filename, char *uriString)
int | uriWindowsFilenameToUriStringA (const char *filename, char *uriString)
int | uriUriStringToUnixFilenameA (const char *uriString, char *filename)
int | uriUriStringToWindowsFilenameA (const char *uriString, char *filename)
int | uriComposeQueryCharsRequiredA (const UriQueryListA *queryList, int *charsRequired)
int | uriComposeQueryCharsRequiredExA (const UriQueryListA *queryList, int *charsRequired, UriBool spaceToPlus, UriBool normalizeBreaks)
int | uriComposeQueryA (char *dest, const UriQueryListA *queryList, int maxChars, int *charsWritten)
int | uriComposeQueryExA (char *dest, const UriQueryListA *queryList, int maxChars, int *charsWritten, UriBool spaceToPlus, UriBool normalizeBreaks)
int | uriComposeQueryMallocA (char **dest, const UriQueryListA *queryList)
int | uriComposeQueryMallocExA (char **dest, const UriQueryListA *queryList, UriBool spaceToPlus, UriBool normalizeBreaks)
int | uriDissectQueryMallocA (UriQueryListA **dest, int *itemCount, const char *first, const char *afterLast)
int | uriDissectQueryMallocExA (UriQueryListA **dest, int *itemCount, const char *first, const char *afterLast, UriBool plusToSpace, UriBreakConversion breakConversion)
void | uriFreeQueryListA (UriQueryListA *queryList)

## Detailed Description

Holds the RFC 3986 URI parser interface. NOTE: This header includes itself twice.

## Typedef Documentation

typedef struct UriHostDataStructA UriHostDataA

Holds structured host information. This is either a IPv4, IPv6, plain text for IPvFuture or all zero for a registered name.

See also
  UriUriA

Since
  0.3.0Holds structured host information. This is either a IPv4, IPv6, plain text for IPvFuture or all zero for a registered name.

See also
  UriUriA

Since
  0.3.0

typedef struct UriParserStateStructA UriParserStateA

Represents a state of the URI parser. Missing components can be NULL to reflect a components absence.

See also
  uriFreeUriMembersA

Since
  0.3.0Represents a state of the URI parser. Missing components can be NULL to reflect a components absence.

See also
  uriFreeUriMembersA

Since
  0.3.0

typedef struct UriPathSegmentStructA UriPathSegmentA

Represents a path segment within a URI path. More precisely it is a node in a linked list of path segments.

See also
  UriUriA

Since
  0.3.0Represents a path segment within a URI path. More precisely it is a node in a linked list of path segments.

See also
  UriUriA

Since
  0.3.0

typedef struct UriQueryListStructA UriQueryListA

Represents a query element. More precisely it is a node in a linked list of query elements.

Since
  0.7.0Represents a query element. More precisely it is a node in a linked list of query elements.
  0.7.0

typedef struct UriTextRangeStructA UriTextRangeA

Specifies a range of characters within a string. The range includes all characters from `first` to one before `afterLast`. So if both are non-NULL the difference is the length of the text range.

See also
  UriUriA
  UriPathSegmentA
  UriHostDataA

Since
  0.3.0Specifies a range of characters within a string. The range includes all characters from `first` to one before `afterLast`. So if both are non-NULL the difference is the length of the text range.

See also
  UriUriA
  UriPathSegmentA
  UriHostDataA

Since
  0.3.0

typedef struct UriUriStructA UriUriA

Represents an RFC 3986 URI. Missing components can be {NULL, NULL} ranges.

See also
  uriParseUriA
  uriFreeUriMembersA
  UriParserStateA

Since
  0.3.0Represents an RFC 3986 URI. Missing components can be {NULL, NULL} ranges.

See also
  uriParseUriA
  uriFreeUriMembersA
  UriParserStateA

Since
  0.3.0

## Function Documentation

int uriAddBaseUriA | ( | UriUriA * | absoluteDest,
|  | const UriUriA * | relativeSource,
|  | const UriUriA * | absoluteBase
| ) |  |

Performs reference resolution as described in section 5.2.2 of RFC 3986. NOTE: On success you have to call uriFreeUriMembersA on `absoluteDest` manually later.

Parameters

  absoluteDest | OUT: Result URI
  relativeSource | IN: Reference to resolve
  absoluteBase | IN: Base URI to apply

Returns
  Error code or 0 on success

See also
  uriRemoveBaseUriA, uriAddBaseUriExA

Since
  0.4.0

int uriAddBaseUriExA | ( | UriUriA * | absoluteDest,
|  | const UriUriA * | relativeSource,
|  | const UriUriA * | absoluteBase,
|  | UriResolutionOptions | options
| ) |  |

Performs reference resolution as described in section 5.2.2 of RFC 3986. NOTE: On success you have to call uriFreeUriMembersA on `absoluteDest` manually later.

Parameters

  absoluteDest | OUT: Result URI
  relativeSource | IN: Reference to resolve
  absoluteBase | IN: Base URI to apply
  options | IN: Configuration to apply

Returns
  Error code or 0 on success

See also
  uriRemoveBaseUriA, uriAddBaseUriA

Since
  0.8.1

int uriComposeQueryA | ( | char * | dest,
|  | const UriQueryListA * | queryList,
|  | int | maxChars,
|  | int * | charsWritten
| ) |  |

Converts a query list structure back to a query string. The composed string does not start with '?', on the way ' ' is converted to '+' and line breaks are normalized to "%0D%0A".

Parameters

  dest | OUT: Output destination
  queryList | IN: Query list to convert
  maxChars | IN: Maximum number of characters to copy including terminator
  charsWritten | OUT: Number of characters written, can be lower than maxChars even if the query list is too long!

Returns
  Error code or 0 on success

See also
  uriComposeQueryExA
  uriComposeQueryMallocA
  uriComposeQueryCharsRequiredA
  uriDissectQueryMallocA

Since
  0.7.0

int uriComposeQueryCharsRequiredA | ( | const UriQueryListA * | queryList,
|  | int * | charsRequired
| ) |  |

Calculates the number of characters needed to store the string representation of the given query list excluding the terminator. It is assumed that line breaks are will be normalized to "%0D%0A".

Parameters

  queryList | IN: Query list to measure
  charsRequired | OUT: Length of the string representation in characters excluding terminator

Returns
  Error code or 0 on success

See also
  uriComposeQueryCharsRequiredExA
  uriComposeQueryA

Since
  0.7.0

int uriComposeQueryCharsRequiredExA | ( | const UriQueryListA * | queryList,
|  | int * | charsRequired,
|  | UriBool | spaceToPlus,
|  | UriBool | normalizeBreaks
| ) |  |

Calculates the number of characters needed to store the string representation of the given query list excluding the terminator.

Parameters

  queryList | IN: Query list to measure
  charsRequired | OUT: Length of the string representation in characters excluding terminator
  spaceToPlus | IN: Wether to convert ' ' to '+' or not
  normalizeBreaks | IN: Wether to convert CR and LF to CR-LF or not.

Returns
  Error code or 0 on success

See also
  uriComposeQueryCharsRequiredA
  uriComposeQueryExA

Since
  0.7.0

int uriComposeQueryExA | ( | char * | dest,
|  | const UriQueryListA * | queryList,
|  | int | maxChars,
|  | int * | charsWritten,
|  | UriBool | spaceToPlus,
|  | UriBool | normalizeBreaks
| ) |  |

Converts a query list structure back to a query string. The composed string does not start with '?'.

Parameters

  dest | OUT: Output destination
  queryList | IN: Query list to convert
  maxChars | IN: Maximum number of characters to copy including terminator
  charsWritten | OUT: Number of characters written, can be lower than maxChars even if the query list is too long!
  spaceToPlus | IN: Wether to convert ' ' to '+' or not
  normalizeBreaks | IN: Wether to convert CR and LF to CR-LF or not.

Returns
  Error code or 0 on success

See also
  uriComposeQueryA
  uriComposeQueryMallocExA
  uriComposeQueryCharsRequiredExA
  uriDissectQueryMallocExA

Since
  0.7.0

int uriComposeQueryMallocA | ( | char ** | dest,
|  | const UriQueryListA * | queryList
| ) |  |

Converts a query list structure back to a query string. Memory for this string is allocated internally. The composed string does not start with '?', on the way ' ' is converted to '+' and line breaks are normalized to "%0D%0A".

Parameters

  dest | OUT: Output destination
  queryList | IN: Query list to convert

Returns
  Error code or 0 on success

See also
  uriComposeQueryMallocExA
  uriComposeQueryA
  uriDissectQueryMallocA

Since
  0.7.0

int uriComposeQueryMallocExA | ( | char ** | dest,
|  | const UriQueryListA * | queryList,
|  | UriBool | spaceToPlus,
|  | UriBool | normalizeBreaks
| ) |  |

Converts a query list structure back to a query string. Memory for this string is allocated internally. The composed string does not start with '?'.

Parameters

  dest | OUT: Output destination
  queryList | IN: Query list to convert
  spaceToPlus | IN: Wether to convert ' ' to '+' or not
  normalizeBreaks | IN: Wether to convert CR and LF to CR-LF or not.

Returns
  Error code or 0 on success

See also
  uriComposeQueryMallocA
  uriComposeQueryExA
  uriDissectQueryMallocExA

Since
  0.7.0

int uriDissectQueryMallocA | ( | UriQueryListA ** | dest,
|  | int * | itemCount,
|  | const char * | first,
|  | const char * | afterLast
| ) |  |

Constructs a query list from the raw query string of a given URI. On the way '+' is converted back to ' ', line breaks are not modified.

Parameters

  dest | OUT: Output destination
  itemCount | OUT: Number of items found, can be NULL
  first | IN: Pointer to first character after '?'
  afterLast | IN: Pointer to character after the last one still in

Returns
  Error code or 0 on success

See also
  uriDissectQueryMallocExA
  uriComposeQueryA
  uriFreeQueryListA

Since
  0.7.0

int uriDissectQueryMallocExA | ( | UriQueryListA ** | dest,
|  | int * | itemCount,
|  | const char * | first,
|  | const char * | afterLast,
|  | UriBool | plusToSpace,
|  | UriBreakConversion | breakConversion
| ) |  |

Constructs a query list from the raw query string of a given URI.

Parameters

  dest | OUT: Output destination
  itemCount | OUT: Number of items found, can be NULL
  first | IN: Pointer to first character after '?'
  afterLast | IN: Pointer to character after the last one still in
  plusToSpace | IN: Whether to convert '+' to ' ' or not
  breakConversion | IN: Line break conversion mode

Returns
  Error code or 0 on success

See also
  uriDissectQueryMallocA
  uriComposeQueryExA
  uriFreeQueryListA

Since
  0.7.0

UriBool uriEqualsUriA | ( | const UriUriA * | a,
|  | const UriUriA * | b
| ) |  |

Checks two URIs for equivalence. Comparison is done the naive way, without prior normalization. NOTE: Two `NULL` URIs are equal as well.

Parameters

  a | IN: First URI
  b | IN: Second URI

Returns
  `URI_TRUE` when equal, `URI_FAlSE` else

Since
  0.4.0

char* uriEscapeA | ( | const char * | in,
|  | char * | out,
|  | UriBool | spaceToPlus,
|  | UriBool | normalizeBreaks
| ) |  |

Percent-encodes all unreserved characters from the input string and writes the encoded version to the output string. Be sure to allocate 3 times the space of the input buffer for the output buffer for `normalizeBreaks == URI_FALSE` and 6 times the space for `normalizeBreaks == URI_TRUE` (since e.g. "\x0d" becomes "%0D%0A" in that case)

Parameters

  in | IN: Text source
  out | OUT: Encoded text destination
  spaceToPlus | IN: Wether to convert ' ' to '+' or not
  normalizeBreaks | IN: Wether to convert CR and LF to CR-LF or not.

Returns
  Position of terminator in output string

See also
  uriEscapeExA
  uriUnescapeInPlaceA

Since
  0.5.0

char* uriEscapeExA | ( | const char * | inFirst,
|  | const char * | inAfterLast,
|  | char * | out,
|  | UriBool | spaceToPlus,
|  | UriBool | normalizeBreaks
| ) |  |

Percent-encodes all unreserved characters from the input string and writes the encoded version to the output string. Be sure to allocate 3 times the space of the input buffer for the output buffer for `normalizeBreaks == URI_FALSE` and 6 times the space for `normalizeBreaks == URI_TRUE` (since e.g. "\x0d" becomes "%0D%0A" in that case)

Parameters

  inFirst | IN: Pointer to first character of the input text
  inAfterLast | IN: Pointer after the last character of the input text
  out | OUT: Encoded text destination
  spaceToPlus | IN: Wether to convert ' ' to '+' or not
  normalizeBreaks | IN: Wether to convert CR and LF to CR-LF or not.

Returns
  Position of terminator in output string

See also
  uriEscapeA
  uriUnescapeInPlaceExA

Since
  0.5.2

void uriFreeQueryListA | ( | UriQueryListA * | queryList | ) |

Frees all memory associated with the given query list. The structure itself is freed as well.

Parameters

  queryList | INOUT: Query list to free

Since
  0.7.0

void uriFreeUriMembersA | ( | UriUriA * | uri | ) |

Frees all memory associated with the members of the URI structure. Note that the structure itself is not freed, only its members.

Parameters

  uri | INOUT: URI structure whose members should be freed

Since
  0.3.0

int uriNormalizeSyntaxA | ( | UriUriA * | uri | ) |

Normalizes all components of a URI.

NOTE: If necessary the URI becomes owner of all memory behind the text pointed to. Text is duplicated in that case.

Parameters

  uri | INOUT: URI to normalize

Returns
  Error code or 0 on success

See also
  uriNormalizeSyntaxExA
  uriNormalizeSyntaxMaskRequiredA

Since
  0.5.0

int uriNormalizeSyntaxExA | ( | UriUriA * | uri,
|  | unsigned int | mask
| ) |  |

Normalizes a URI using a normalization mask. The normalization mask decides what components are normalized.

NOTE: If necessary the URI becomes owner of all memory behind the text pointed to. Text is duplicated in that case.

Parameters

  uri | INOUT: URI to normalize
  mask | IN: Normalization mask

Returns
  Error code or 0 on success

See also
  uriNormalizeSyntaxA
  uriNormalizeSyntaxMaskRequiredA

Since
  0.5.0

unsigned int uriNormalizeSyntaxMaskRequiredA | ( | const UriUriA * | uri | ) |

Determines the components of a URI that are not normalized.

Parameters

  uri | IN: URI to check

Returns
  Normalization job mask

See also
  uriNormalizeSyntaxA

Since
  0.5.0

int uriParseUriA | ( | UriParserStateA * | state,
|  | const char * | text
| ) |  |

Parses a RFC 3986 URI.

Parameters

  state | INOUT: Parser state with set output URI, must not be NULL
  text | IN: Text to parse, must not be NULL

Returns
  0 on success, error code otherwise

See also
  uriParseUriExA
  uriToStringA

Since
  0.3.0

int uriParseUriExA | ( | UriParserStateA * | state,
|  | const char * | first,
|  | const char * | afterLast
| ) |  |

Parses a RFC 3986 URI.

Parameters

  state | INOUT: Parser state with set output URI, must not be NULL
  first | IN: Pointer to the first character to parse, must not be NULL
  afterLast | IN: Pointer to the character after the last to parse, must not be NULL

Returns
  0 on success, error code otherwise

See also
  uriParseUriA
  uriToStringA

Since
  0.3.0

int uriRemoveBaseUriA | ( | UriUriA * | dest,
|  | const UriUriA * | absoluteSource,
|  | const UriUriA * | absoluteBase,
|  | UriBool | domainRootMode
| ) |  |

Tries to make a relative URI (a reference) from an absolute URI and a given base URI. This can only work if the absolute URI shares scheme and authority with the base URI. If it does not the result will still be an absolute URI (with scheme part if necessary). NOTE: On success you have to call uriFreeUriMembersA on `dest` manually later.

Parameters

  dest | OUT: Result URI
  absoluteSource | IN: Absolute URI to make relative
  absoluteBase | IN: Base URI
  domainRootMode | IN: Create URI with path relative to domain root

Returns
  Error code or 0 on success

See also
  uriAddBaseUriA, uriAddBaseUriExA

Since
  0.5.2

int uriToStringA | ( | char * | dest,
|  | const UriUriA * | uri,
|  | int | maxChars,
|  | int * | charsWritten
| ) |  |

Converts a URI structure back to text as described in section 5.3 of RFC 3986.

Parameters

  dest | OUT: Output destination
  uri | IN: URI to convert
  maxChars | IN: Maximum number of characters to copy including terminator
  charsWritten | OUT: Number of characters written, can be lower than maxChars even if the URI is too long!

Returns
  Error code or 0 on success

See also
  uriToStringCharsRequiredA

Since
  0.4.0

int uriToStringCharsRequiredA | ( | const UriUriA * | uri,
|  | int * | charsRequired
| ) |  |

Calculates the number of characters needed to store the string representation of the given URI excluding the terminator.

Parameters

  uri | IN: URI to measure
  charsRequired | OUT: Length of the string representation in characters excluding terminator

Returns
  Error code or 0 on success

See also
  uriToStringA

Since
  0.5.0

const char* uriUnescapeInPlaceA | ( | char * | inout | ) |

Unescapes percent-encoded groups in a given string. E.g. "%20" will become " ". Unescaping is done in place. The return value will be point to the new position of the terminating zero. Use this value to get the new length of the string. NULL is only returned if `inout` is NULL.

NOTE: '+' is not decoded to ' ' and line breaks are not converted. Use the more advanced UnescapeInPlaceEx for that features instead.

Parameters

  inout | INOUT: Text to unescape/decode

Returns
  Pointer to new position of the terminating zero

See also
  uriUnescapeInPlaceExA
  uriEscapeA

Since
  0.3.0

const char* uriUnescapeInPlaceExA | ( | char * | inout,
|  | UriBool | plusToSpace,
|  | UriBreakConversion | breakConversion
| ) |  |

Unescapes percent-encoded groups in a given string. E.g. "%20" will become " ". Unescaping is done in place. The return value will be point to the new position of the terminating zero. Use this value to get the new length of the string. NULL is only returned if `inout` is NULL.

Parameters

  inout | INOUT: Text to unescape/decode
  plusToSpace | IN: Whether to convert '+' to ' ' or not
  breakConversion | IN: Line break conversion mode

Returns
  Pointer to new position of the terminating zero

See also
  uriUnescapeInPlaceA
  uriEscapeExA

Since
  0.5.0

int uriUnixFilenameToUriStringA | ( | const char * | filename,
|  | char * | uriString
| ) |  |

Converts a Unix filename to a URI string. The destination buffer must be large enough to hold 7 + 3 * len(filename) + 1 characters in case of an absolute filename or 3 * len(filename) + 1 in case of a relative filename.

EXAMPLE Input: "/bin/bash" Output: "file:///bin/bash"

Parameters

  filename | IN: Unix filename to convert
  uriString | OUT: Destination to write URI string to

Returns
  Error code or 0 on success

See also
  uriUriStringToUnixFilenameA
  uriWindowsFilenameToUriStringA

Since
  0.5.2

int uriUriStringToUnixFilenameA | ( | const char * | uriString,
|  | char * | filename
| ) |  |

Extracts a Unix filename from a URI string. The destination buffer must be large enough to hold len(uriString) + 1 - 7 characters in case of an absolute URI or len(uriString) + 1 in case of a relative URI.

Parameters

  uriString | IN: URI string to convert
  filename | OUT: Destination to write filename to

Returns
  Error code or 0 on success

See also
  uriUnixFilenameToUriStringA
  uriUriStringToWindowsFilenameA

Since
  0.5.2

int uriUriStringToWindowsFilenameA | ( | const char * | uriString,
|  | char * | filename
| ) |  |

Extracts a Windows filename from a URI string. The destination buffer must be large enough to hold len(uriString) + 1 - 8 characters in case of an absolute URI or len(uriString) + 1 in case of a relative URI.

Parameters

  uriString | IN: URI string to convert
  filename | OUT: Destination to write filename to

Returns
  Error code or 0 on success

See also
  uriWindowsFilenameToUriStringA
  uriUriStringToUnixFilenameA

Since
  0.5.2

int uriWindowsFilenameToUriStringA | ( | const char * | filename,
|  | char * | uriString
| ) |  |

Converts a Windows filename to a URI string. The destination buffer must be large enough to hold 8 + 3 * len(filename) + 1 characters in case of an absolute filename or 3 * len(filename) + 1 in case of a relative filename.

EXAMPLE Input: "E:\\Documents and Settings" Output: "file:///E:/Documents%20and%20Settings"

Parameters

  filename | IN: Windows filename to convert
  uriString | OUT: Destination to write URI string to

Returns
  Error code or 0 on success

See also
  uriUriStringToWindowsFilenameA
  uriUnixFilenameToUriStringA

Since
  0.5.2