From c3dce46c5f7cad6bc3cc91cc2c711ac089f25923 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6rg=20Frings-F=C3=BCrst?= Date: Fri, 8 May 2026 11:53:45 +0200 Subject: New upstream version 1.0.1+dfsg --- doc/Mainpage.txt | 242 +++++++++++++++++++++++++++---------------------------- 1 file changed, 121 insertions(+), 121 deletions(-) (limited to 'doc/Mainpage.txt') diff --git a/doc/Mainpage.txt b/doc/Mainpage.txt index 19d8115..a65ac36 100644 --- a/doc/Mainpage.txt +++ b/doc/Mainpage.txt @@ -27,19 +27,19 @@ * Parsing a URI with uriparser looks like this: * * @code - * UriUriA uri; - * const char * const uriString = "file:///home/user/song.mp3"; - * const char * errorPos; - * - * if (uriParseSingleUriA(&uri, uriString, &errorPos) != URI_SUCCESS) { - * /COMMENT_HACK* Failure (no need to call uriFreeUriMembersA) *COMMENT_HACK/ - * ... - * return ...; - * } - * - * /COMMENT_HACK* Success *COMMENT_HACK/ - * ... - * uriFreeUriMembersA(&uri); + * UriUriA uri; + * const char * const uriString = "file:///home/user/song.mp3"; + * const char * errorPos; + * + * if (uriParseSingleUriA(&uri, uriString, &errorPos) != URI_SUCCESS) { + * /COMMENT_HACK* Failure (no need to call uriFreeUriMembersA) *COMMENT_HACK/ + * ... + * return ...; + * } + * + * /COMMENT_HACK* Success *COMMENT_HACK/ + * ... + * uriFreeUriMembersA(&uri); * @endcode * * While the URI object (::UriUriA) holds information about the recognized @@ -47,35 +47,35 @@ * errorPos points to the first character starting invalid syntax. * * @subsection recomposition Recomposing URIs (from object back to string) - * According to RFC 3986 + * According to RFC 3986 * gluing parts of a URI together to form a string is called recomposition. * Before we can recompose a URI object we have to know how much * space the resulting string will take: * * @code - * UriUriA uri; - * char * uriString; - * int charsRequired; - * ... - * if (uriToStringCharsRequiredA(&uri, &charsRequired) != URI_SUCCESS) { - * /COMMENT_HACK* Failure *COMMENT_HACK/ - * ... - * } - * charsRequired++; + * UriUriA uri; + * char * uriString; + * int charsRequired; + * ... + * if (uriToStringCharsRequiredA(&uri, &charsRequired) != URI_SUCCESS) { + * /COMMENT_HACK* Failure *COMMENT_HACK/ + * ... + * } + * charsRequired++; * @endcode * * Now we can tell uriToStringA() to write the string to a given buffer: * * @code - * uriString = malloc(charsRequired * sizeof(char)); - * if (uriString == NULL) { - * /COMMENT_HACK* Failure *COMMENT_HACK/ - * ... - * } - * if (uriToStringA(uriString, &uri, charsRequired, NULL) != URI_SUCCESS) { - * /COMMENT_HACK* Failure *COMMENT_HACK/ - * ... - * } + * uriString = malloc(charsRequired * sizeof(char)); + * if (uriString == NULL) { + * /COMMENT_HACK* Failure *COMMENT_HACK/ + * ... + * } + * if (uriToStringA(uriString, &uri, charsRequired, NULL) != URI_SUCCESS) { + * /COMMENT_HACK* Failure *COMMENT_HACK/ + * ... + * } * @endcode * * @remarks @@ -87,25 +87,25 @@ * * * @subsection resolution Resolving References - * Reference Resolution + * Reference Resolution * is the process of turning a (relative) URI reference into an absolute URI by applying a base * URI to it. In code it looks like this: * * @code - * UriUriA absoluteDest; - * UriUriA relativeSource; - * UriUriA absoluteBase; - * ... - * /COMMENT_HACK* relativeSource holds "../TWO" now *COMMENT_HACK/ - * /COMMENT_HACK* absoluteBase holds "file:///one/two/three" now *COMMENT_HACK/ - * if (uriAddBaseUriA(&absoluteDest, &relativeSource, &absoluteBase) != URI_SUCCESS) { - * /COMMENT_HACK* Failure *COMMENT_HACK/ - * uriFreeUriMembersA(&absoluteDest); - * ... - * } - * /COMMENT_HACK* absoluteDest holds "file:///one/TWO" now *COMMENT_HACK/ - * ... - * uriFreeUriMembersA(&absoluteDest); + * UriUriA absoluteDest; + * UriUriA relativeSource; + * UriUriA absoluteBase; + * ... + * /COMMENT_HACK* relativeSource holds "../TWO" now *COMMENT_HACK/ + * /COMMENT_HACK* absoluteBase holds "file:///one/two/three" now *COMMENT_HACK/ + * if (uriAddBaseUriA(&absoluteDest, &relativeSource, &absoluteBase) != URI_SUCCESS) { + * /COMMENT_HACK* Failure *COMMENT_HACK/ + * uriFreeUriMembersA(&absoluteDest); + * ... + * } + * /COMMENT_HACK* absoluteDest holds "file:///one/TWO" now *COMMENT_HACK/ + * ... + * uriFreeUriMembersA(&absoluteDest); * @endcode * * @remarks @@ -120,20 +120,20 @@ * carry a scheme * * @code - * UriUriA dest; - * UriUriA absoluteSource; - * UriUriA absoluteBase; - * ... - * /COMMENT_HACK* absoluteSource holds "file:///one/TWO" now *COMMENT_HACK/ - * /COMMENT_HACK* absoluteBase holds "file:///one/two/three" now *COMMENT_HACK/ - * if (uriRemoveBaseUriA(&dest, &absoluteSource, &absoluteBase, URI_FALSE) != URI_SUCCESS) { - * /COMMENT_HACK* Failure *COMMENT_HACK/ - * uriFreeUriMembersA(&dest); - * ... - * } - * /COMMENT_HACK* dest holds "../TWO" now *COMMENT_HACK/ - * ... - * uriFreeUriMembersA(&dest); + * UriUriA dest; + * UriUriA absoluteSource; + * UriUriA absoluteBase; + * ... + * /COMMENT_HACK* absoluteSource holds "file:///one/TWO" now *COMMENT_HACK/ + * /COMMENT_HACK* absoluteBase holds "file:///one/two/three" now *COMMENT_HACK/ + * if (uriRemoveBaseUriA(&dest, &absoluteSource, &absoluteBase, URI_FALSE) != URI_SUCCESS) { + * /COMMENT_HACK* Failure *COMMENT_HACK/ + * uriFreeUriMembersA(&dest); + * ... + * } + * /COMMENT_HACK* dest holds "../TWO" now *COMMENT_HACK/ + * ... + * uriFreeUriMembersA(&dest); * @endcode * * The fourth parameter is the domain root mode. With URI_FALSE as above this will produce @@ -146,17 +146,17 @@ * i.e. without creating an URI object. * * @code - * const char * const absFilename = "E:\\Documents and Settings"; - * const int bytesNeeded = 8 + 3 * strlen(absFilename) + 1; - * char * absUri = malloc(bytesNeeded * sizeof(char)); - * if (uriWindowsFilenameToUriStringA(absFilename, absUri) != URI_SUCCESS) { - * /COMMENT_HACK* Failure *COMMENT_HACK/ - * free(absUri); - * ... - * } - * /COMMENT_HACK* absUri is "file:///E:/Documents%20and%20Settings" now *COMMENT_HACK/ - * ... - * free(absUri); + * const char * const absFilename = "E:\\Documents and Settings"; + * const int bytesNeeded = 8 + 3 * strlen(absFilename) + 1; + * char * absUri = malloc(bytesNeeded * sizeof(char)); + * if (uriWindowsFilenameToUriStringA(absFilename, absUri) != URI_SUCCESS) { + * /COMMENT_HACK* Failure *COMMENT_HACK/ + * free(absUri); + * ... + * } + * /COMMENT_HACK* absUri is "file:///E:/Documents%20and%20Settings" now *COMMENT_HACK/ + * ... + * free(absUri); * @endcode * * Conversion works .. @@ -183,9 +183,9 @@ * @subsection normalization Normalizing URIs * Sometimes we come across unnecessarily long URIs like "http://example.org/one/two/../../one". * The algorithm we can use to shorten this URI down to "http://example.org/one" is called - * Syntax-Based Normalization. + * Syntax-Based Normalization. * Note that normalizing a URI does more than just "stripping dot segments". Please have a look at - * Section 6.2.2 of RFC 3986 + * Section 6.2.2 of RFC 3986 * for the full description. * * As we asked uriToStringCharsRequiredA() for the required space when converting @@ -194,22 +194,22 @@ * mask to uriNormalizeSyntaxExA(): * * @code - * const unsigned int dirtyParts = uriNormalizeSyntaxMaskRequiredA(&uri); - * if (uriNormalizeSyntaxExA(&uri, dirtyParts) != URI_SUCCESS) { - * /COMMENT_HACK* Failure *COMMENT_HACK/ - * ... - * } + * const unsigned int dirtyParts = uriNormalizeSyntaxMaskRequiredA(&uri); + * if (uriNormalizeSyntaxExA(&uri, dirtyParts) != URI_SUCCESS) { + * /COMMENT_HACK* Failure *COMMENT_HACK/ + * ... + * } * @endcode * * If you don't want to normalize all parts of the URI you can pass a custom * mask as well: * * @code - * const unsigned int normMask = URI_NORMALIZE_SCHEME | URI_NORMALIZE_USER_INFO; - * if (uriNormalizeSyntaxExA(&uri, normMask) != URI_SUCCESS) { - * /COMMENT_HACK* Failure *COMMENT_HACK/ - * ... - * } + * const unsigned int normMask = URI_NORMALIZE_SCHEME | URI_NORMALIZE_USER_INFO; + * if (uriNormalizeSyntaxExA(&uri, normMask) != URI_SUCCESS) { + * /COMMENT_HACK* Failure *COMMENT_HACK/ + * ... + * } * @endcode * * Please see ::UriNormalizationMaskEnum for the complete set of flags. @@ -219,36 +219,36 @@ * internally: * * @code - * if (uriNormalizeSyntaxA(&uri) != URI_SUCCESS) { - * /COMMENT_HACK* Failure *COMMENT_HACK/ - * ... - * } + * if (uriNormalizeSyntaxA(&uri) != URI_SUCCESS) { + * /COMMENT_HACK* Failure *COMMENT_HACK/ + * ... + * } * @endcode * * * @section querystrings Working with Query Strings - * RFC 3986 + * RFC 3986 * itself does not understand the query part of a URI as a list of key/value pairs. * But HTML 2.0 does and defines a media type application/x-www-form-urlencoded - * in in section 8.2.1 - * of RFC 1866. + * in in section 8.2.1 + * of RFC 1866. * uriparser allows you to dissect (or parse) a query string into unescaped key/value pairs * and back. * * To dissect the query part of a just-parsed URI you could write code like this: * * @code - * UriUriA uri; - * UriQueryListA * queryList; - * int itemCount; - * ... - * if (uriDissectQueryMallocA(&queryList, &itemCount, uri.query.first, - * uri.query.afterLast) != URI_SUCCESS) { - * /COMMENT_HACK* Failure *COMMENT_HACK/ - * ... - * } - * ... - * uriFreeQueryListA(queryList); + * UriUriA uri; + * UriQueryListA * queryList; + * int itemCount; + * ... + * if (uriDissectQueryMallocA(&queryList, &itemCount, uri.query.first, + * uri.query.afterLast) != URI_SUCCESS) { + * /COMMENT_HACK* Failure *COMMENT_HACK/ + * ... + * } + * ... + * uriFreeQueryListA(queryList); * @endcode * * @remarks @@ -259,25 +259,25 @@ * To compose a query string from a query list you could write code like this: * * @code - * int charsRequired; - * int charsWritten; - * char * queryString; - * ... - * if (uriComposeQueryCharsRequiredA(queryList, &charsRequired) != URI_SUCCESS) { - * /COMMENT_HACK* Failure *COMMENT_HACK/ - * ... - * } - * queryString = malloc((charsRequired + 1) * sizeof(char)); - * if (queryString == NULL) { - * /COMMENT_HACK* Failure *COMMENT_HACK/ - * ... - * } - * if (uriComposeQueryA(queryString, queryList, charsRequired + 1, &charsWritten) != URI_SUCCESS) { - * /COMMENT_HACK* Failure *COMMENT_HACK/ - * ... - * } - * ... - * free(queryString); + * int charsRequired; + * int charsWritten; + * char * queryString; + * ... + * if (uriComposeQueryCharsRequiredA(queryList, &charsRequired) != URI_SUCCESS) { + * /COMMENT_HACK* Failure *COMMENT_HACK/ + * ... + * } + * queryString = malloc((charsRequired + 1) * sizeof(char)); + * if (queryString == NULL) { + * /COMMENT_HACK* Failure *COMMENT_HACK/ + * ... + * } + * if (uriComposeQueryA(queryString, queryList, charsRequired + 1, &charsWritten) != URI_SUCCESS) { + * /COMMENT_HACK* Failure *COMMENT_HACK/ + * ... + * } + * ... + * free(queryString); * @endcode * * -- cgit v1.2.3