"Fossies" - the Fresh Open Source Software Archive

Member "uriparser-0.9.5/doc/Mainpage.txt" (18 Mar 2021, 11077 Bytes) of package /linux/www/uriparser-0.9.5.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "Mainpage.txt": 0.9.4_vs_0.9.5.

    1 /**
    2  * @mainpage
    3  *
    4  * @section SEC_TOC Table of Contents
    5  * - <a href="#intro">Introduction</a>
    6  * - Algorithms and Examples
    7  *   - <a href="#parsing">Parsing URIs</a> (from string to object)
    8  *   - <a href="#recomposition">Recomposing URIs</a> (from object back to string)
    9  *   - <a href="#resolution">Resolving References</a>
   10  *   - <a href="#shortening">Creating References</a>
   11  *   - <a href="#filenames">Filenames and URIs</a>
   12  *   - <a href="#normalization">Normalizing URIs</a>
   13  *   - <a href="#querystrings">Working with Query Strings</a>
   14  * - <a href="#chartypes">Narrow Strings and Wide Strings</a>
   15  * - <a href="#autoconf">Autoconf Check</a>
   16  *
   17  *
   18  * @section intro Introduction
   19  * Welcome to the short uriparser integration tutorial.
   20  * It is intended to answer upcoming questions and to shed light
   21  * where function prototypes alone are not enough.
   22  * Please drop me a line if you need further assistance and I will
   23  * see what I can do for you. Good luck with uriparser!
   24  *
   25  *
   26  * @subsection parsing Parsing URIs (from string to object)
   27  * Parsing a URI with uriparser looks like this:
   28  *
   29  * @code
   30  * 	UriUriA uri;
   31  * 	const char * const uriString = "file:///home/user/song.mp3";
   32  * 	const char * errorPos;
   33  *
   34  * 	if (uriParseSingleUriA(&uri, uriString, &errorPos) != URI_SUCCESS) {
   35  * 		/COMMENT_HACK* Failure (no need to call uriFreeUriMembersA) *COMMENT_HACK/
   36  * 		...
   37  * 		return ...;
   38  * 	}
   39  *
   40  * 	/COMMENT_HACK* Success *COMMENT_HACK/
   41  * 	...
   42  * 	uriFreeUriMembersA(&uri);
   43  * @endcode
   44  *
   45  * While the URI object (::UriUriA) holds information about the recognized
   46  * parts of the given URI string, in case of <c>URI_ERROR_SYNTAX</c>,
   47  * <c>errorPos</c> points to the first character starting invalid syntax.
   48  *
   49  * @subsection recomposition Recomposing URIs (from object back to string)
   50  * According to <a href="http://tools.ietf.org/html/rfc3986#section-5.3" target="_blank">RFC 3986</a>
   51  * gluing parts of a URI together to form a string is called recomposition.
   52  * Before we can recompose a URI object we have to know how much
   53  * space the resulting string will take:
   54  *
   55  * @code
   56  * 	UriUriA uri;
   57  * 	char * uriString;
   58  * 	int charsRequired;
   59  * 	...
   60  * 	if (uriToStringCharsRequiredA(&uri, &charsRequired) != URI_SUCCESS) {
   61  * 		/COMMENT_HACK* Failure *COMMENT_HACK/
   62  * 		...
   63  * 	}
   64  * 	charsRequired++;
   65  * @endcode
   66  *
   67  * Now we can tell uriToStringA() to write the string to a given buffer:
   68  *
   69  * @code
   70  * 	uriString = malloc(charsRequired * sizeof(char));
   71  * 	if (uriString == NULL) {
   72  * 		/COMMENT_HACK* Failure *COMMENT_HACK/
   73  * 		...
   74  * 	}
   75  * 	if (uriToStringA(uriString, &uri, charsRequired, NULL) != URI_SUCCESS) {
   76  * 		/COMMENT_HACK* Failure *COMMENT_HACK/
   77  * 		...
   78  * 	}
   79  * @endcode
   80  *
   81  * @remarks
   82  * Incrementing <c>charsRequired</c> by 1 is required since
   83  * uriToStringCharsRequiredA() returns the length of the string
   84  * as strlen() does, but uriToStringA() works with the number
   85  * of maximum characters to be written <b>including</b> the
   86  * zero-terminator.
   87  *
   88  *
   89  * @subsection resolution Resolving References
   90  * <a href="http://tools.ietf.org/html/rfc3986#section-5" target="_blank">Reference Resolution</a>
   91  * is the process of turning a (relative) URI reference into an absolute URI by applying a base
   92  * URI to it. In code it looks like this:
   93  *
   94  * @code
   95  * 	UriUriA absoluteDest;
   96  * 	UriUriA relativeSource;
   97  * 	UriUriA absoluteBase;
   98  * 	...
   99  * 	/COMMENT_HACK* relativeSource holds "../TWO" now *COMMENT_HACK/
  100  * 	/COMMENT_HACK* absoluteBase holds "file:///one/two/three" now *COMMENT_HACK/
  101  * 	if (uriAddBaseUriA(&absoluteDest, &relativeSource, &absoluteBase) != URI_SUCCESS) {
  102  * 		/COMMENT_HACK* Failure *COMMENT_HACK/
  103  * 		uriFreeUriMembersA(&absoluteDest);
  104  * 		...
  105  * 	}
  106  * 	/COMMENT_HACK* absoluteDest holds "file:///one/TWO" now *COMMENT_HACK/
  107  * 	...
  108  * 	uriFreeUriMembersA(&absoluteDest);
  109  * @endcode
  110  *
  111  * @remarks
  112  * uriAddBaseUriA() does not normalize the resulting URI.
  113  * Usually you might want to pass it through uriNormalizeSyntaxA() after.
  114  *
  115  *
  116  * @subsection shortening Creating References
  117  * Reference Creation is the inverse process of Reference Resolution: A common base URI
  118  * is &quot;subtracted&quot; from an absolute URI to make a (relative) reference.
  119  * If the base URI is not common the remaining URI will still be absolute, i.e. will
  120  * carry a scheme
  121  *
  122  * @code
  123  * 	UriUriA dest;
  124  * 	UriUriA absoluteSource;
  125  * 	UriUriA absoluteBase;
  126  * 	...
  127  * 	/COMMENT_HACK* absoluteSource holds "file:///one/TWO" now *COMMENT_HACK/
  128  * 	/COMMENT_HACK* absoluteBase holds "file:///one/two/three" now *COMMENT_HACK/
  129  * 	if (uriRemoveBaseUriA(&dest, &absoluteSource, &absoluteBase, URI_FALSE) != URI_SUCCESS) {
  130  * 		/COMMENT_HACK* Failure *COMMENT_HACK/
  131  * 		uriFreeUriMembersA(&dest);
  132  * 		...
  133  * 	}
  134  * 	/COMMENT_HACK* dest holds "../TWO" now *COMMENT_HACK/
  135  * 	...
  136  * 	uriFreeUriMembersA(&dest);
  137  * @endcode
  138  *
  139  * The fourth parameter is the domain root mode. With <c>URI_FALSE</c> as above this will produce
  140  * URIs relative to the base URI. With <c>URI_TRUE</c> the resulting URI will be relative to the
  141  * domain root instead, e.g. &quot;/one/TWO&quot; in this case.
  142  *
  143  *
  144  * @subsection filenames Filenames and URIs
  145  * Converting filenames to and from URIs works on strings directly,
  146  * i.e. without creating an URI object. 
  147  *
  148  * @code
  149  * 	const char * const absFilename = "E:\\Documents and Settings";
  150  * 	const int bytesNeeded = 8 + 3 * strlen(absFilename) + 1;
  151  * 	char * absUri = malloc(bytesNeeded * sizeof(char));
  152  * 	if (uriWindowsFilenameToUriStringA(absFilename, absUri) != URI_SUCCESS) {
  153  * 		/COMMENT_HACK* Failure *COMMENT_HACK/
  154  * 		free(absUri);
  155  * 		...
  156  * 	}
  157  * 	/COMMENT_HACK* absUri is "file:///E:/Documents%20and%20Settings" now *COMMENT_HACK/
  158  * 	...
  159  * 	free(absUri);
  160  * @endcode
  161  *
  162  * Conversion works ..
  163  * - for relative or absolute values,
  164  * - in both directions (filenames &lt;--&gt; URIs) and
  165  * - with Unix and Windows filenames.
  166  *
  167  * All you have to do is to choose the right function for the task and allocate
  168  * the required space (in characters) for the target buffer.
  169  * Let me present you an overview:
  170  *
  171  * - Filename --&gt; URI
  172  *   - uriUnixFilenameToUriStringA()\n
  173  *     Space required: [<b>7</b> +] 3 * len(filename) + 1 
  174  *   - uriWindowsFilenameToUriStringA()\n
  175  *     Space required: [<b>8</b> +] 3 * len(filename) + 1
  176  * - URI --&gt; filename
  177  *   - uriUriStringToUnixFilenameA()\n
  178  *     Space required: len(uriString) + 1 [- <b>7]</b>
  179  *   - uriUriStringToWindowsFilenameA()\n
  180  *     Space required: len(uriString) + 1 [- <b>8]</b>
  181  *
  182  *
  183  * @subsection normalization Normalizing URIs
  184  * Sometimes we come across unnecessarily long URIs like &quot;http<b></b>://example.org/one/two/../../one&quot;.
  185  * The algorithm we can use to shorten this URI down to &quot;http<b></b>://example.org/one&quot; is called
  186  * <a href="http://tools.ietf.org/html/rfc3986#section-6.2.2" target="_blank">Syntax-Based Normalization</a>.
  187  * Note that normalizing a URI does more than just &quot;stripping dot segments&quot;. Please have a look at
  188  * <a href="http://tools.ietf.org/html/rfc3986#section-6.2.2" target="_blank">Section 6.2.2 of RFC 3986</a>
  189  * for the full description.
  190  *
  191  * As we asked uriToStringCharsRequiredA() for the required space when converting
  192  * a URI object back to a string, we can ask uriNormalizeSyntaxMaskRequiredA() for
  193  * the parts of a URI that require normalization and then pass this normalization
  194  * mask to uriNormalizeSyntaxExA():
  195  *
  196  * @code
  197  * 	const unsigned int dirtyParts = uriNormalizeSyntaxMaskRequiredA(&uri);
  198  * 	if (uriNormalizeSyntaxExA(&uri, dirtyParts) != URI_SUCCESS) {
  199  * 		/COMMENT_HACK* Failure *COMMENT_HACK/
  200  * 		...
  201  * 	}
  202  * @endcode
  203  *
  204  * If you don't want to normalize all parts of the URI you can pass a custom
  205  * mask as well:
  206  *
  207  * @code
  208  * 	const unsigned int normMask = URI_NORMALIZE_SCHEME | URI_NORMALIZE_USER_INFO;
  209  * 	if (uriNormalizeSyntaxExA(&uri, normMask) != URI_SUCCESS) {
  210  * 		/COMMENT_HACK* Failure *COMMENT_HACK/
  211  * 		...
  212  * 	}
  213  * @endcode
  214  *
  215  * Please see ::UriNormalizationMaskEnum for the complete set of flags.
  216  *
  217  * On the other hand calling plain uriNormalizeSyntaxA() (without the &quot;Ex&quot;)
  218  * saves you thinking about single parts, as it queries uriNormalizeSyntaxMaskRequiredA()
  219  * internally:
  220  *
  221  * @code
  222  * 	if (uriNormalizeSyntaxA(&uri) != URI_SUCCESS) {
  223  * 		/COMMENT_HACK* Failure *COMMENT_HACK/
  224  * 		...
  225  * 	}
  226  * @endcode
  227  *
  228  *
  229  * @section querystrings Working with Query Strings
  230  * <a href="http://tools.ietf.org/html/rfc3986" target="_blank">RFC 3986</a>
  231  * itself does not understand the query part of a URI as a list of key/value pairs.
  232  * But HTML 2.0 does and defines a media type <i>application/x-www-form-urlencoded</i>
  233  * in in <a href="http://tools.ietf.org/html/rfc1866#section-8.2.1" target="blank">section 8.2.1</a>
  234  * of <a href="http://tools.ietf.org/html/rfc1866" target="blank">RFC 1866</a>.
  235  * uriparser allows you to dissect (or parse) a query string into unescaped key/value pairs
  236  * and back.
  237  *
  238  * To dissect the query part of a just-parsed URI you could write code like this:
  239  * 
  240  * @code
  241  * 	UriUriA uri;
  242  * 	UriQueryListA * queryList;
  243  * 	int itemCount;
  244  * 	...
  245  * 	if (uriDissectQueryMallocA(&queryList, &itemCount, uri.query.first,
  246  * 			uri.query.afterLast) != URI_SUCCESS) {
  247  * 		/COMMENT_HACK* Failure *COMMENT_HACK/
  248  * 		...
  249  * 	}
  250  * 	...
  251  * 	uriFreeQueryListA(queryList);
  252  * @endcode
  253  *
  254  * @remarks
  255  * - <c>NULL</c> in the <c>value</c> member means there was <b>no</b> '=' in the item text as with "?abc&def".
  256  * - An empty string in the <c>value</c> member means there was '=' in the item as with "?abc=&def".
  257  *
  258  *
  259  * To compose a query string from a query list you could write code like this:
  260  *
  261  * @code
  262  * 	int charsRequired;
  263  * 	int charsWritten;
  264  * 	char * queryString;
  265  * 	...
  266  * 	if (uriComposeQueryCharsRequiredA(queryList, &charsRequired) != URI_SUCCESS) {
  267  * 		/COMMENT_HACK* Failure *COMMENT_HACK/
  268  * 		...
  269  * 	}
  270  * 	queryString = malloc((charsRequired + 1) * sizeof(char));
  271  * 	if (queryString == NULL) {
  272  * 		/COMMENT_HACK* Failure *COMMENT_HACK/
  273  * 		...
  274  * 	}
  275  * 	if (uriComposeQueryA(queryString, queryList, charsRequired + 1, &charsWritten) != URI_SUCCESS) {
  276  * 		/COMMENT_HACK* Failure *COMMENT_HACK/
  277  * 		...
  278  * 	}
  279  * 	...
  280  * 	free(queryString);
  281  * @endcode
  282  *
  283  *
  284  * @section chartypes Narrow Strings and Wide Strings
  285  * uriparser comes with two versions of every structure and function:
  286  * one handling narrow strings (<code>char *</code>) and one working with wide strings (<code>wchar_t *</code>),
  287  * for instance
  288  * - uriParseSingleUriA() for <code>char *</code>
  289  * - uriParseSingleUriW() for <code>wchar_t *</code>.
  290  *
  291  * This tutorial only shows the usage of the narrow string editions but
  292  * their wide string counterparts work in the very same way.
  293  *
  294  *
  295  * @section autoconf Autoconf Check
  296  * You can use the code below to make <c>./configure</c> test for presence
  297  * of uriparser 0.9.0 or later.
  298  *
  299  *<div class="fragment"><pre class="fragment">PKG_CHECK_MODULES([URIPARSER], [liburiparser >= 0.9.0], [], [])</pre></div>
  300  */