uriparser  0.7.6
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 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

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

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

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

See also:
uriFreeUriMembersA
Since:
0.3.0

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

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

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

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

Since:
0.7.0

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

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

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.

typedef struct UriUriStructA UriUriA

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

See also:
uriParseUriA
uriFreeUriMembersA
UriParserStateA
Since:
0.3.0

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


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:
absoluteDestOUT: Result URI
relativeSourceIN: Reference to resolve
absoluteBaseIN: Base URI to apply
Returns:
Error code or 0 on success
See also:
uriRemoveBaseUriA
Since:
0.4.0
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:
destOUT: Output destination
queryListIN: Query list to convert
maxCharsIN: Maximum number of characters to copy including terminator
charsWrittenOUT: 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:
queryListIN: Query list to measure
charsRequiredOUT: 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:
queryListIN: Query list to measure
charsRequiredOUT: Length of the string representation in characters excluding terminator
spaceToPlusIN: Wether to convert ' ' to '+' or not
normalizeBreaksIN: 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:
destOUT: Output destination
queryListIN: Query list to convert
maxCharsIN: Maximum number of characters to copy including terminator
charsWrittenOUT: Number of characters written, can be lower than maxChars even if the query list is too long!
spaceToPlusIN: Wether to convert ' ' to '+' or not
normalizeBreaksIN: 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:
destOUT: Output destination
queryListIN: 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:
destOUT: Output destination
queryListIN: Query list to convert
spaceToPlusIN: Wether to convert ' ' to '+' or not
normalizeBreaksIN: 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:
destOUT: Output destination
itemCountOUT: Number of items found, can be NULL
firstIN: Pointer to first character after '?'
afterLastIN: 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:
destOUT: Output destination
itemCountOUT: Number of items found, can be NULL
firstIN: Pointer to first character after '?'
afterLastIN: Pointer to character after the last one still in
plusToSpaceIN: Whether to convert '+' to ' ' or not
breakConversionIN: 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:
aIN: First URI
bIN: 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:
inIN: Text source
outOUT: Encoded text destination
spaceToPlusIN: Wether to convert ' ' to '+' or not
normalizeBreaksIN: 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:
inFirstIN: Pointer to first character of the input text
inAfterLastIN: Pointer after the last character of the input text
outOUT: Encoded text destination
spaceToPlusIN: Wether to convert ' ' to '+' or not
normalizeBreaksIN: 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:
queryListINOUT: 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:
uriINOUT: 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:
uriINOUT: 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:
uriINOUT: URI to normalize
maskIN: 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:
uriIN: 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:
stateINOUT: Parser state with set output URI, must not be NULL
textIN: 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:
stateINOUT: Parser state with set output URI, must not be NULL
firstIN: Pointer to the first character to parse, must not be NULL
afterLastIN: 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:
destOUT: Result URI
absoluteSourceIN: Absolute URI to make relative
absoluteBaseIN: Base URI
domainRootModeIN: Create URI with path relative to domain root
Returns:
Error code or 0 on success
See also:
uriAddBaseUriA
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:
destOUT: Output destination
uriIN: URI to convert
maxCharsIN: Maximum number of characters to copy including terminator
charsWrittenOUT: 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:
uriIN: URI to measure
charsRequiredOUT: 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:
inoutINOUT: 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:
inoutINOUT: Text to unescape/decode
plusToSpaceIN: Whether to convert '+' to ' ' or not
breakConversionIN: 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:
filenameIN: Unix filename to convert
uriStringOUT: 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:
uriStringIN: URI string to convert
filenameOUT: 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:
uriStringIN: URI string to convert
filenameOUT: 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:
filenameIN: Windows filename to convert
uriStringOUT: Destination to write URI string to
Returns:
Error code or 0 on success
See also:
uriUriStringToWindowsFilenameA
uriUnixFilenameToUriStringA
Since:
0.5.2
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator