Main Page | Data Structures | File List | Data Fields | Globals

Uri.h File Reference


Detailed Description

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


Data Structures

struct  UriTextRangeStructA
struct  UriPathSegmentStructA
struct  UriHostDataStructA
struct  UriUriStructA
struct  UriParserStateStructA
struct  UriQueryListStructA

Typedefs

typedef UriTextRangeStructA UriTextRangeA
typedef UriPathSegmentStructA UriPathSegmentA
typedef UriHostDataStructA UriHostDataA
typedef UriUriStructA UriUriA
typedef UriParserStateStructA UriParserStateA
typedef 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)


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

typedef struct UriTextRangeStructA UriTextRangeA
 

Specifies a range of characters within a string. The range includes all characters from <c>first</c> to one before <c>afterLast</c>. 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.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.

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
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:
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 <c>NULL</c> URIs are equal as well.

Parameters:
a IN: First URI
b IN: Second URI
Returns:
<c>URI_TRUE</c> when equal, <c>URI_FAlSE</c> 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 <c>normalizeBreaks == URI_FALSE</c> and 6 times the space for <c>normalizeBreaks == URI_FALSE</c> (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 <c>normalizeBreaks == URI_FALSE</c> and 6 times the space for <c>normalizeBreaks == URI_TRUE</c> (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).

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
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 <c>inout</c> 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 <c>inout</c> 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


Generated on Tue Jun 30 16:34:30 2009 for uriparser by  doxygen 1.3.9.1