summaryrefslogtreecommitdiffstats
path: root/plugins/uriparser/Uri.h
diff options
context:
space:
mode:
authorAndreas Baumann <mail@andreasbaumann.cc>2017-05-06 16:36:16 +0200
committerSven Nierlein <sven@nierlein.de>2018-10-22 16:30:31 +0200
commita739a5614834178ba88d04972b4f4ba9c560e1df (patch)
treee9ebee27575d064000e9e210dba2b36c914e8544 /plugins/uriparser/Uri.h
parent28a4c7076a3115d30aeb3b3b5e5bde715692e4a7 (diff)
downloadmonitoring-plugins-a739a5614834178ba88d04972b4f4ba9c560e1df.tar.gz
some rework:
- added old style 'redir' function and options along to a new libcurl internal 'follow' parameter 'curl' - moved picohttpparser to it's own subdirectory - added uriparser to be used instead of the home-grown parser in 'redir'
Diffstat (limited to 'plugins/uriparser/Uri.h')
-rw-r--r--plugins/uriparser/Uri.h777
1 files changed, 777 insertions, 0 deletions
diff --git a/plugins/uriparser/Uri.h b/plugins/uriparser/Uri.h
new file mode 100644
index 00000000..4a185808
--- /dev/null
+++ b/plugins/uriparser/Uri.h
@@ -0,0 +1,777 @@
1/*
2 * uriparser - RFC 3986 URI parsing library
3 *
4 * Copyright (C) 2007, Weijia Song <songweijia@gmail.com>
5 * Copyright (C) 2007, Sebastian Pipping <webmaster@hartwork.org>
6 * All rights reserved.
7 *
8 * Redistribution and use in source and binary forms, with or without
9 * modification, are permitted provided that the following conditions
10 * are met:
11 *
12 * * Redistributions of source code must retain the above
13 * copyright notice, this list of conditions and the following
14 * disclaimer.
15 *
16 * * Redistributions in binary form must reproduce the above
17 * copyright notice, this list of conditions and the following
18 * disclaimer in the documentation and/or other materials
19 * provided with the distribution.
20 *
21 * * Neither the name of the <ORGANIZATION> nor the names of its
22 * contributors may be used to endorse or promote products
23 * derived from this software without specific prior written
24 * permission.
25 *
26 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
27 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
28 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
29 * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
30 * COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
31 * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
32 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
33 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
34 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
35 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
36 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
37 * OF THE POSSIBILITY OF SUCH DAMAGE.
38 */
39
40/**
41 * @file Uri.h
42 * Holds the RFC 3986 %URI parser interface.
43 * NOTE: This header includes itself twice.
44 */
45
46#if (defined(URI_PASS_ANSI) && !defined(URI_H_ANSI)) \
47 || (defined(URI_PASS_UNICODE) && !defined(URI_H_UNICODE)) \
48 || (!defined(URI_PASS_ANSI) && !defined(URI_PASS_UNICODE))
49/* What encodings are enabled? */
50#include "UriDefsConfig.h"
51#if (!defined(URI_PASS_ANSI) && !defined(URI_PASS_UNICODE))
52/* Include SELF twice */
53# ifdef URI_ENABLE_ANSI
54# define URI_PASS_ANSI 1
55# include "Uri.h"
56# undef URI_PASS_ANSI
57# endif
58# ifdef URI_ENABLE_UNICODE
59# define URI_PASS_UNICODE 1
60# include "Uri.h"
61# undef URI_PASS_UNICODE
62# endif
63/* Only one pass for each encoding */
64#elif (defined(URI_PASS_ANSI) && !defined(URI_H_ANSI) \
65 && defined(URI_ENABLE_ANSI)) || (defined(URI_PASS_UNICODE) \
66 && !defined(URI_H_UNICODE) && defined(URI_ENABLE_UNICODE))
67# ifdef URI_PASS_ANSI
68# define URI_H_ANSI 1
69# include "UriDefsAnsi.h"
70# else
71# define URI_H_UNICODE 1
72# include "UriDefsUnicode.h"
73# endif
74
75
76
77#ifdef __cplusplus
78extern "C" {
79#endif
80
81
82
83#ifndef URI_DOXYGEN
84# include "UriBase.h"
85#endif
86
87
88
89/**
90 * Specifies a range of characters within a string.
91 * The range includes all characters from <c>first</c>
92 * to one before <c>afterLast</c>. So if both are
93 * non-NULL the difference is the length of the text range.
94 *
95 * @see UriUriA
96 * @see UriPathSegmentA
97 * @see UriHostDataA
98 * @since 0.3.0
99 */
100typedef struct URI_TYPE(TextRangeStruct) {
101 const URI_CHAR * first; /**< Pointer to first character */
102 const URI_CHAR * afterLast; /**< Pointer to character after the last one still in */
103} URI_TYPE(TextRange); /**< @copydoc UriTextRangeStructA */
104
105
106
107/**
108 * Represents a path segment within a %URI path.
109 * More precisely it is a node in a linked
110 * list of path segments.
111 *
112 * @see UriUriA
113 * @since 0.3.0
114 */
115typedef struct URI_TYPE(PathSegmentStruct) {
116 URI_TYPE(TextRange) text; /**< Path segment name */
117 struct URI_TYPE(PathSegmentStruct) * next; /**< Pointer to the next path segment in the list, can be NULL if last already */
118
119 void * reserved; /**< Reserved to the parser */
120} URI_TYPE(PathSegment); /**< @copydoc UriPathSegmentStructA */
121
122
123
124/**
125 * Holds structured host information.
126 * This is either a IPv4, IPv6, plain
127 * text for IPvFuture or all zero for
128 * a registered name.
129 *
130 * @see UriUriA
131 * @since 0.3.0
132 */
133typedef struct URI_TYPE(HostDataStruct) {
134 UriIp4 * ip4; /**< IPv4 address */
135 UriIp6 * ip6; /**< IPv6 address */
136 URI_TYPE(TextRange) ipFuture; /**< IPvFuture address */
137} URI_TYPE(HostData); /**< @copydoc UriHostDataStructA */
138
139
140
141/**
142 * Represents an RFC 3986 %URI.
143 * Missing components can be {NULL, NULL} ranges.
144 *
145 * @see uriParseUriA
146 * @see uriFreeUriMembersA
147 * @see UriParserStateA
148 * @since 0.3.0
149 */
150typedef struct URI_TYPE(UriStruct) {
151 URI_TYPE(TextRange) scheme; /**< Scheme (e.g. "http") */
152 URI_TYPE(TextRange) userInfo; /**< User info (e.g. "user:pass") */
153 URI_TYPE(TextRange) hostText; /**< Host text (set for all hosts, excluding square brackets) */
154 URI_TYPE(HostData) hostData; /**< Structured host type specific data */
155 URI_TYPE(TextRange) portText; /**< Port (e.g. "80") */
156 URI_TYPE(PathSegment) * pathHead; /**< Head of a linked list of path segments */
157 URI_TYPE(PathSegment) * pathTail; /**< Tail of the list behind pathHead */
158 URI_TYPE(TextRange) query; /**< Query without leading "?" */
159 URI_TYPE(TextRange) fragment; /**< Query without leading "#" */
160 UriBool absolutePath; /**< Absolute path flag, distincting "a" and "/a" */
161 UriBool owner; /**< Memory owner flag */
162
163 void * reserved; /**< Reserved to the parser */
164} URI_TYPE(Uri); /**< @copydoc UriUriStructA */
165
166
167
168/**
169 * Represents a state of the %URI parser.
170 * Missing components can be NULL to reflect
171 * a components absence.
172 *
173 * @see uriFreeUriMembersA
174 * @since 0.3.0
175 */
176typedef struct URI_TYPE(ParserStateStruct) {
177 URI_TYPE(Uri) * uri; /**< Plug in the %URI structure to be filled while parsing here */
178 int errorCode; /**< Code identifying the occured error */
179 const URI_CHAR * errorPos; /**< Pointer to position in case of a syntax error */
180
181 void * reserved; /**< Reserved to the parser */
182} URI_TYPE(ParserState); /**< @copydoc UriParserStateStructA */
183
184
185
186/**
187 * Represents a query element.
188 * More precisely it is a node in a linked
189 * list of query elements.
190 *
191 * @since 0.7.0
192 */
193typedef struct URI_TYPE(QueryListStruct) {
194 const URI_CHAR * key; /**< Key of the query element */
195 const URI_CHAR * value; /**< Value of the query element, can be NULL */
196
197 struct URI_TYPE(QueryListStruct) * next; /**< Pointer to the next key/value pair in the list, can be NULL if last already */
198} URI_TYPE(QueryList); /**< @copydoc UriQueryListStructA */
199
200
201
202/**
203 * Parses a RFC 3986 URI.
204 *
205 * @param state <b>INOUT</b>: Parser state with set output %URI, must not be NULL
206 * @param first <b>IN</b>: Pointer to the first character to parse, must not be NULL
207 * @param afterLast <b>IN</b>: Pointer to the character after the last to parse, must not be NULL
208 * @return 0 on success, error code otherwise
209 *
210 * @see uriParseUriA
211 * @see uriToStringA
212 * @since 0.3.0
213 */
214int URI_FUNC(ParseUriEx)(URI_TYPE(ParserState) * state,
215 const URI_CHAR * first, const URI_CHAR * afterLast);
216
217
218
219/**
220 * Parses a RFC 3986 %URI.
221 *
222 * @param state <b>INOUT</b>: Parser state with set output %URI, must not be NULL
223 * @param text <b>IN</b>: Text to parse, must not be NULL
224 * @return 0 on success, error code otherwise
225 *
226 * @see uriParseUriExA
227 * @see uriToStringA
228 * @since 0.3.0
229 */
230int URI_FUNC(ParseUri)(URI_TYPE(ParserState) * state,
231 const URI_CHAR * text);
232
233
234
235/**
236 * Frees all memory associated with the members
237 * of the %URI structure. Note that the structure
238 * itself is not freed, only its members.
239 *
240 * @param uri <b>INOUT</b>: %URI structure whose members should be freed
241 *
242 * @since 0.3.0
243 */
244void URI_FUNC(FreeUriMembers)(URI_TYPE(Uri) * uri);
245
246
247
248/**
249 * Percent-encodes all unreserved characters from the input string and
250 * writes the encoded version to the output string.
251 * Be sure to allocate <b>3 times</b> the space of the input buffer for
252 * the output buffer for <c>normalizeBreaks == URI_FALSE</c> and <b>6 times</b>
253 * the space for <c>normalizeBreaks == URI_TRUE</c>
254 * (since e.g. "\x0d" becomes "%0D%0A" in that case)
255 *
256 * @param inFirst <b>IN</b>: Pointer to first character of the input text
257 * @param inAfterLast <b>IN</b>: Pointer after the last character of the input text
258 * @param out <b>OUT</b>: Encoded text destination
259 * @param spaceToPlus <b>IN</b>: Wether to convert ' ' to '+' or not
260 * @param normalizeBreaks <b>IN</b>: Wether to convert CR and LF to CR-LF or not.
261 * @return Position of terminator in output string
262 *
263 * @see uriEscapeA
264 * @see uriUnescapeInPlaceExA
265 * @since 0.5.2
266 */
267URI_CHAR * URI_FUNC(EscapeEx)(const URI_CHAR * inFirst,
268 const URI_CHAR * inAfterLast, URI_CHAR * out,
269 UriBool spaceToPlus, UriBool normalizeBreaks);
270
271
272
273/**
274 * Percent-encodes all unreserved characters from the input string and
275 * writes the encoded version to the output string.
276 * Be sure to allocate <b>3 times</b> the space of the input buffer for
277 * the output buffer for <c>normalizeBreaks == URI_FALSE</c> and <b>6 times</b>
278 * the space for <c>normalizeBreaks == URI_TRUE</c>
279 * (since e.g. "\x0d" becomes "%0D%0A" in that case)
280 *
281 * @param in <b>IN</b>: Text source
282 * @param out <b>OUT</b>: Encoded text destination
283 * @param spaceToPlus <b>IN</b>: Wether to convert ' ' to '+' or not
284 * @param normalizeBreaks <b>IN</b>: Wether to convert CR and LF to CR-LF or not.
285 * @return Position of terminator in output string
286 *
287 * @see uriEscapeExA
288 * @see uriUnescapeInPlaceA
289 * @since 0.5.0
290 */
291URI_CHAR * URI_FUNC(Escape)(const URI_CHAR * in, URI_CHAR * out,
292 UriBool spaceToPlus, UriBool normalizeBreaks);
293
294
295
296/**
297 * Unescapes percent-encoded groups in a given string.
298 * E.g. "%20" will become " ". Unescaping is done in place.
299 * The return value will be point to the new position
300 * of the terminating zero. Use this value to get the new
301 * length of the string. NULL is only returned if <c>inout</c>
302 * is NULL.
303 *
304 * @param inout <b>INOUT</b>: Text to unescape/decode
305 * @param plusToSpace <b>IN</b>: Whether to convert '+' to ' ' or not
306 * @param breakConversion <b>IN</b>: Line break conversion mode
307 * @return Pointer to new position of the terminating zero
308 *
309 * @see uriUnescapeInPlaceA
310 * @see uriEscapeExA
311 * @since 0.5.0
312 */
313const URI_CHAR * URI_FUNC(UnescapeInPlaceEx)(URI_CHAR * inout,
314 UriBool plusToSpace, UriBreakConversion breakConversion);
315
316
317
318/**
319 * Unescapes percent-encoded groups in a given string.
320 * E.g. "%20" will become " ". Unescaping is done in place.
321 * The return value will be point to the new position
322 * of the terminating zero. Use this value to get the new
323 * length of the string. NULL is only returned if <c>inout</c>
324 * is NULL.
325 *
326 * NOTE: '+' is not decoded to ' ' and line breaks are not converted.
327 * Use the more advanced UnescapeInPlaceEx for that features instead.
328 *
329 * @param inout <b>INOUT</b>: Text to unescape/decode
330 * @return Pointer to new position of the terminating zero
331 *
332 * @see uriUnescapeInPlaceExA
333 * @see uriEscapeA
334 * @since 0.3.0
335 */
336const URI_CHAR * URI_FUNC(UnescapeInPlace)(URI_CHAR * inout);
337
338
339
340/**
341 * Performs reference resolution as described in
342 * <a href="http://tools.ietf.org/html/rfc3986#section-5.2.2">section 5.2.2 of RFC 3986</a>.
343 * NOTE: On success you have to call uriFreeUriMembersA on \p absoluteDest manually later.
344 *
345 * @param absoluteDest <b>OUT</b>: Result %URI
346 * @param relativeSource <b>IN</b>: Reference to resolve
347 * @param absoluteBase <b>IN</b>: Base %URI to apply
348 * @return Error code or 0 on success
349 *
350 * @see uriRemoveBaseUriA, uriAddBaseUriExA
351 * @since 0.4.0
352 */
353int URI_FUNC(AddBaseUri)(URI_TYPE(Uri) * absoluteDest,
354 const URI_TYPE(Uri) * relativeSource,
355 const URI_TYPE(Uri) * absoluteBase);
356
357
358
359/**
360 * Performs reference resolution as described in
361 * <a href="http://tools.ietf.org/html/rfc3986#section-5.2.2">section 5.2.2 of RFC 3986</a>.
362 * NOTE: On success you have to call uriFreeUriMembersA on \p absoluteDest manually later.
363 *
364 * @param absoluteDest <b>OUT</b>: Result %URI
365 * @param relativeSource <b>IN</b>: Reference to resolve
366 * @param absoluteBase <b>IN</b>: Base %URI to apply
367 * @param options <b>IN</b>: Configuration to apply
368 * @return Error code or 0 on success
369 *
370 * @see uriRemoveBaseUriA, uriAddBaseUriA
371 * @since 0.8.1
372 */
373int URI_FUNC(AddBaseUriEx)(URI_TYPE(Uri) * absoluteDest,
374 const URI_TYPE(Uri) * relativeSource,
375 const URI_TYPE(Uri) * absoluteBase,
376 UriResolutionOptions options);
377
378
379
380/**
381 * Tries to make a relative %URI (a reference) from an
382 * absolute %URI and a given base %URI. This can only work if
383 * the absolute %URI shares scheme and authority with
384 * the base %URI. If it does not the result will still be
385 * an absolute URI (with scheme part if necessary).
386 * NOTE: On success you have to call uriFreeUriMembersA on
387 * \p dest manually later.
388 *
389 * @param dest <b>OUT</b>: Result %URI
390 * @param absoluteSource <b>IN</b>: Absolute %URI to make relative
391 * @param absoluteBase <b>IN</b>: Base %URI
392 * @param domainRootMode <b>IN</b>: Create %URI with path relative to domain root
393 * @return Error code or 0 on success
394 *
395 * @see uriAddBaseUriA, uriAddBaseUriExA
396 * @since 0.5.2
397 */
398int URI_FUNC(RemoveBaseUri)(URI_TYPE(Uri) * dest,
399 const URI_TYPE(Uri) * absoluteSource,
400 const URI_TYPE(Uri) * absoluteBase,
401 UriBool domainRootMode);
402
403
404
405/**
406 * Checks two URIs for equivalence. Comparison is done
407 * the naive way, without prior normalization.
408 * NOTE: Two <c>NULL</c> URIs are equal as well.
409 *
410 * @param a <b>IN</b>: First %URI
411 * @param b <b>IN</b>: Second %URI
412 * @return <c>URI_TRUE</c> when equal, <c>URI_FAlSE</c> else
413 *
414 * @since 0.4.0
415 */
416UriBool URI_FUNC(EqualsUri)(const URI_TYPE(Uri) * a, const URI_TYPE(Uri) * b);
417
418
419
420/**
421 * Calculates the number of characters needed to store the
422 * string representation of the given %URI excluding the
423 * terminator.
424 *
425 * @param uri <b>IN</b>: %URI to measure
426 * @param charsRequired <b>OUT</b>: Length of the string representation in characters <b>excluding</b> terminator
427 * @return Error code or 0 on success
428 *
429 * @see uriToStringA
430 * @since 0.5.0
431 */
432int URI_FUNC(ToStringCharsRequired)(const URI_TYPE(Uri) * uri,
433 int * charsRequired);
434
435
436
437/**
438 * Converts a %URI structure back to text as described in
439 * <a href="http://tools.ietf.org/html/rfc3986#section-5.3">section 5.3 of RFC 3986</a>.
440 *
441 * @param dest <b>OUT</b>: Output destination
442 * @param uri <b>IN</b>: %URI to convert
443 * @param maxChars <b>IN</b>: Maximum number of characters to copy <b>including</b> terminator
444 * @param charsWritten <b>OUT</b>: Number of characters written, can be lower than maxChars even if the %URI is too long!
445 * @return Error code or 0 on success
446 *
447 * @see uriToStringCharsRequiredA
448 * @since 0.4.0
449 */
450int URI_FUNC(ToString)(URI_CHAR * dest, const URI_TYPE(Uri) * uri, int maxChars, int * charsWritten);
451
452
453
454/**
455 * Determines the components of a %URI that are not normalized.
456 *
457 * @param uri <b>IN</b>: %URI to check
458 * @return Normalization job mask
459 *
460 * @see uriNormalizeSyntaxA
461 * @since 0.5.0
462 */
463unsigned int URI_FUNC(NormalizeSyntaxMaskRequired)(const URI_TYPE(Uri) * uri);
464
465
466
467/**
468 * Normalizes a %URI using a normalization mask.
469 * The normalization mask decides what components are normalized.
470 *
471 * NOTE: If necessary the %URI becomes owner of all memory
472 * behind the text pointed to. Text is duplicated in that case.
473 *
474 * @param uri <b>INOUT</b>: %URI to normalize
475 * @param mask <b>IN</b>: Normalization mask
476 * @return Error code or 0 on success
477 *
478 * @see uriNormalizeSyntaxA
479 * @see uriNormalizeSyntaxMaskRequiredA
480 * @since 0.5.0
481 */
482int URI_FUNC(NormalizeSyntaxEx)(URI_TYPE(Uri) * uri, unsigned int mask);
483
484
485
486/**
487 * Normalizes all components of a %URI.
488 *
489 * NOTE: If necessary the %URI becomes owner of all memory
490 * behind the text pointed to. Text is duplicated in that case.
491 *
492 * @param uri <b>INOUT</b>: %URI to normalize
493 * @return Error code or 0 on success
494 *
495 * @see uriNormalizeSyntaxExA
496 * @see uriNormalizeSyntaxMaskRequiredA
497 * @since 0.5.0
498 */
499int URI_FUNC(NormalizeSyntax)(URI_TYPE(Uri) * uri);
500
501
502
503/**
504 * Converts a Unix filename to a %URI string.
505 * The destination buffer must be large enough to hold 7 + 3 * len(filename) + 1
506 * characters in case of an absolute filename or 3 * len(filename) + 1 in case
507 * of a relative filename.
508 *
509 * EXAMPLE
510 * Input: "/bin/bash"
511 * Output: "file:///bin/bash"
512 *
513 * @param filename <b>IN</b>: Unix filename to convert
514 * @param uriString <b>OUT</b>: Destination to write %URI string to
515 * @return Error code or 0 on success
516 *
517 * @see uriUriStringToUnixFilenameA
518 * @see uriWindowsFilenameToUriStringA
519 * @since 0.5.2
520 */
521int URI_FUNC(UnixFilenameToUriString)(const URI_CHAR * filename,
522 URI_CHAR * uriString);
523
524
525
526/**
527 * Converts a Windows filename to a %URI string.
528 * The destination buffer must be large enough to hold 8 + 3 * len(filename) + 1
529 * characters in case of an absolute filename or 3 * len(filename) + 1 in case
530 * of a relative filename.
531 *
532 * EXAMPLE
533 * Input: "E:\\Documents and Settings"
534 * Output: "file:///E:/Documents%20and%20Settings"
535 *
536 * @param filename <b>IN</b>: Windows filename to convert
537 * @param uriString <b>OUT</b>: Destination to write %URI string to
538 * @return Error code or 0 on success
539 *
540 * @see uriUriStringToWindowsFilenameA
541 * @see uriUnixFilenameToUriStringA
542 * @since 0.5.2
543 */
544int URI_FUNC(WindowsFilenameToUriString)(const URI_CHAR * filename,
545 URI_CHAR * uriString);
546
547
548
549/**
550 * Extracts a Unix filename from a %URI string.
551 * The destination buffer must be large enough to hold len(uriString) + 1 - 7
552 * characters in case of an absolute %URI or len(uriString) + 1 in case
553 * of a relative %URI.
554 *
555 * @param uriString <b>IN</b>: %URI string to convert
556 * @param filename <b>OUT</b>: Destination to write filename to
557 * @return Error code or 0 on success
558 *
559 * @see uriUnixFilenameToUriStringA
560 * @see uriUriStringToWindowsFilenameA
561 * @since 0.5.2
562 */
563int URI_FUNC(UriStringToUnixFilename)(const URI_CHAR * uriString,
564 URI_CHAR * filename);
565
566
567
568/**
569 * Extracts a Windows filename from a %URI string.
570 * The destination buffer must be large enough to hold len(uriString) + 1 - 8
571 * characters in case of an absolute %URI or len(uriString) + 1 in case
572 * of a relative %URI.
573 *
574 * @param uriString <b>IN</b>: %URI string to convert
575 * @param filename <b>OUT</b>: Destination to write filename to
576 * @return Error code or 0 on success
577 *
578 * @see uriWindowsFilenameToUriStringA
579 * @see uriUriStringToUnixFilenameA
580 * @since 0.5.2
581 */
582int URI_FUNC(UriStringToWindowsFilename)(const URI_CHAR * uriString,
583 URI_CHAR * filename);
584
585
586
587/**
588 * Calculates the number of characters needed to store the
589 * string representation of the given query list excluding the
590 * terminator. It is assumed that line breaks are will be
591 * normalized to "%0D%0A".
592 *
593 * @param queryList <b>IN</b>: Query list to measure
594 * @param charsRequired <b>OUT</b>: Length of the string representation in characters <b>excluding</b> terminator
595 * @return Error code or 0 on success
596 *
597 * @see uriComposeQueryCharsRequiredExA
598 * @see uriComposeQueryA
599 * @since 0.7.0
600 */
601int URI_FUNC(ComposeQueryCharsRequired)(const URI_TYPE(QueryList) * queryList,
602 int * charsRequired);
603
604
605
606/**
607 * Calculates the number of characters needed to store the
608 * string representation of the given query list excluding the
609 * terminator.
610 *
611 * @param queryList <b>IN</b>: Query list to measure
612 * @param charsRequired <b>OUT</b>: Length of the string representation in characters <b>excluding</b> terminator
613 * @param spaceToPlus <b>IN</b>: Wether to convert ' ' to '+' or not
614 * @param normalizeBreaks <b>IN</b>: Wether to convert CR and LF to CR-LF or not.
615 * @return Error code or 0 on success
616 *
617 * @see uriComposeQueryCharsRequiredA
618 * @see uriComposeQueryExA
619 * @since 0.7.0
620 */
621int URI_FUNC(ComposeQueryCharsRequiredEx)(const URI_TYPE(QueryList) * queryList,
622 int * charsRequired, UriBool spaceToPlus, UriBool normalizeBreaks);
623
624
625
626/**
627 * Converts a query list structure back to a query string.
628 * The composed string does not start with '?',
629 * on the way ' ' is converted to '+' and line breaks are
630 * normalized to "%0D%0A".
631 *
632 * @param dest <b>OUT</b>: Output destination
633 * @param queryList <b>IN</b>: Query list to convert
634 * @param maxChars <b>IN</b>: Maximum number of characters to copy <b>including</b> terminator
635 * @param charsWritten <b>OUT</b>: Number of characters written, can be lower than maxChars even if the query list is too long!
636 * @return Error code or 0 on success
637 *
638 * @see uriComposeQueryExA
639 * @see uriComposeQueryMallocA
640 * @see uriComposeQueryCharsRequiredA
641 * @see uriDissectQueryMallocA
642 * @since 0.7.0
643 */
644int URI_FUNC(ComposeQuery)(URI_CHAR * dest,
645 const URI_TYPE(QueryList) * queryList, int maxChars, int * charsWritten);
646
647
648
649/**
650 * Converts a query list structure back to a query string.
651 * The composed string does not start with '?'.
652 *
653 * @param dest <b>OUT</b>: Output destination
654 * @param queryList <b>IN</b>: Query list to convert
655 * @param maxChars <b>IN</b>: Maximum number of characters to copy <b>including</b> terminator
656 * @param charsWritten <b>OUT</b>: Number of characters written, can be lower than maxChars even if the query list is too long!
657 * @param spaceToPlus <b>IN</b>: Wether to convert ' ' to '+' or not
658 * @param normalizeBreaks <b>IN</b>: Wether to convert CR and LF to CR-LF or not.
659 * @return Error code or 0 on success
660 *
661 * @see uriComposeQueryA
662 * @see uriComposeQueryMallocExA
663 * @see uriComposeQueryCharsRequiredExA
664 * @see uriDissectQueryMallocExA
665 * @since 0.7.0
666 */
667int URI_FUNC(ComposeQueryEx)(URI_CHAR * dest,
668 const URI_TYPE(QueryList) * queryList, int maxChars, int * charsWritten,
669 UriBool spaceToPlus, UriBool normalizeBreaks);
670
671
672
673/**
674 * Converts a query list structure back to a query string.
675 * Memory for this string is allocated internally.
676 * The composed string does not start with '?',
677 * on the way ' ' is converted to '+' and line breaks are
678 * normalized to "%0D%0A".
679 *
680 * @param dest <b>OUT</b>: Output destination
681 * @param queryList <b>IN</b>: Query list to convert
682 * @return Error code or 0 on success
683 *
684 * @see uriComposeQueryMallocExA
685 * @see uriComposeQueryA
686 * @see uriDissectQueryMallocA
687 * @since 0.7.0
688 */
689int URI_FUNC(ComposeQueryMalloc)(URI_CHAR ** dest,
690 const URI_TYPE(QueryList) * queryList);
691
692
693
694/**
695 * Converts a query list structure back to a query string.
696 * Memory for this string is allocated internally.
697 * The composed string does not start with '?'.
698 *
699 * @param dest <b>OUT</b>: Output destination
700 * @param queryList <b>IN</b>: Query list to convert
701 * @param spaceToPlus <b>IN</b>: Wether to convert ' ' to '+' or not
702 * @param normalizeBreaks <b>IN</b>: Wether to convert CR and LF to CR-LF or not.
703 * @return Error code or 0 on success
704 *
705 * @see uriComposeQueryMallocA
706 * @see uriComposeQueryExA
707 * @see uriDissectQueryMallocExA
708 * @since 0.7.0
709 */
710int URI_FUNC(ComposeQueryMallocEx)(URI_CHAR ** dest,
711 const URI_TYPE(QueryList) * queryList,
712 UriBool spaceToPlus, UriBool normalizeBreaks);
713
714
715
716/**
717 * Constructs a query list from the raw query string of a given URI.
718 * On the way '+' is converted back to ' ', line breaks are not modified.
719 *
720 * @param dest <b>OUT</b>: Output destination
721 * @param itemCount <b>OUT</b>: Number of items found, can be NULL
722 * @param first <b>IN</b>: Pointer to first character <b>after</b> '?'
723 * @param afterLast <b>IN</b>: Pointer to character after the last one still in
724 * @return Error code or 0 on success
725 *
726 * @see uriDissectQueryMallocExA
727 * @see uriComposeQueryA
728 * @see uriFreeQueryListA
729 * @since 0.7.0
730 */
731int URI_FUNC(DissectQueryMalloc)(URI_TYPE(QueryList) ** dest, int * itemCount,
732 const URI_CHAR * first, const URI_CHAR * afterLast);
733
734
735
736/**
737 * Constructs a query list from the raw query string of a given URI.
738 *
739 * @param dest <b>OUT</b>: Output destination
740 * @param itemCount <b>OUT</b>: Number of items found, can be NULL
741 * @param first <b>IN</b>: Pointer to first character <b>after</b> '?'
742 * @param afterLast <b>IN</b>: Pointer to character after the last one still in
743 * @param plusToSpace <b>IN</b>: Whether to convert '+' to ' ' or not
744 * @param breakConversion <b>IN</b>: Line break conversion mode
745 * @return Error code or 0 on success
746 *
747 * @see uriDissectQueryMallocA
748 * @see uriComposeQueryExA
749 * @see uriFreeQueryListA
750 * @since 0.7.0
751 */
752int URI_FUNC(DissectQueryMallocEx)(URI_TYPE(QueryList) ** dest, int * itemCount,
753 const URI_CHAR * first, const URI_CHAR * afterLast,
754 UriBool plusToSpace, UriBreakConversion breakConversion);
755
756
757
758/**
759 * Frees all memory associated with the given query list.
760 * The structure itself is freed as well.
761 *
762 * @param queryList <b>INOUT</b>: Query list to free
763 *
764 * @since 0.7.0
765 */
766void URI_FUNC(FreeQueryList)(URI_TYPE(QueryList) * queryList);
767
768
769
770#ifdef __cplusplus
771}
772#endif
773
774
775
776#endif
777#endif