diff options
author | Jörg Frings-Fürst <debian@jff-webhsoting.net> | 2018-11-16 07:16:51 +0100 |
---|---|---|
committer | Jörg Frings-Fürst <debian@jff-webhsoting.net> | 2018-11-16 07:16:51 +0100 |
commit | cd9c1ea3e9c54da1a211563736d6f84664058da8 (patch) | |
tree | f1d883b562a669deb6bfd59b4de27bfaaa63d8a5 /include/uriparser | |
parent | 71a38df59b7b10358477073c9bc053055aa394ce (diff) | |
parent | 5ef83547e904e4d411239ea0a27571e7d1a0b5b4 (diff) |
Merge branch 'feature/upstream' into develop
Diffstat (limited to 'include/uriparser')
-rw-r--r-- | include/uriparser/Uri.h | 318 | ||||
-rw-r--r-- | include/uriparser/UriBase.h | 161 | ||||
-rw-r--r-- | include/uriparser/UriDefsConfig.h | 2 |
3 files changed, 472 insertions, 9 deletions
diff --git a/include/uriparser/Uri.h b/include/uriparser/Uri.h index f4600fb..43fa206 100644 --- a/include/uriparser/Uri.h +++ b/include/uriparser/Uri.h @@ -1,4 +1,4 @@ -/* 5afca6d8abb5d1a22b4e28c912538e6729692afc98f089d9e538ca01c43ab805 (0.8.6+) +/* c071c0bd2264218705abd9e6b19250adb67d6fefa4866d705b9d2f2672281001 (0.9.0+) * * uriparser - RFC 3986 URI parsing library * @@ -143,8 +143,8 @@ typedef struct URI_TYPE(HostDataStruct) { * Represents an RFC 3986 %URI. * Missing components can be {NULL, NULL} ranges. * - * @see uriParseUriA * @see uriFreeUriMembersA + * @see uriFreeUriMembersMmA * @see UriParserStateA * @since 0.3.0 */ @@ -173,6 +173,7 @@ typedef struct URI_TYPE(UriStruct) { * a components absence. * * @see uriFreeUriMembersA + * @see uriFreeUriMembersMmA * @since 0.3.0 */ typedef struct URI_TYPE(ParserStateStruct) { @@ -202,7 +203,8 @@ typedef struct URI_TYPE(QueryListStruct) { /** - * Parses a RFC 3986 URI. + * Parses a RFC 3986 %URI. + * Uses default libc-based memory manager. * * @param state <b>INOUT</b>: Parser state with set output %URI, must not be NULL * @param first <b>IN</b>: Pointer to the first character to parse, must not be NULL @@ -210,8 +212,11 @@ typedef struct URI_TYPE(QueryListStruct) { * @return 0 on success, error code otherwise * * @see uriParseUriA + * @see uriParseSingleUriA + * @see uriParseSingleUriExA * @see uriToStringA * @since 0.3.0 + * @deprecated Deprecated since 0.9.0, please migrate to uriParseSingleUriExA (with "Single"). */ int URI_FUNC(ParseUriEx)(URI_TYPE(ParserState) * state, const URI_CHAR * first, const URI_CHAR * afterLast); @@ -220,14 +225,18 @@ int URI_FUNC(ParseUriEx)(URI_TYPE(ParserState) * state, /** * Parses a RFC 3986 %URI. + * Uses default libc-based memory manager. * * @param state <b>INOUT</b>: Parser state with set output %URI, must not be NULL * @param text <b>IN</b>: Text to parse, must not be NULL * @return 0 on success, error code otherwise * * @see uriParseUriExA + * @see uriParseSingleUriA + * @see uriParseSingleUriExA * @see uriToStringA * @since 0.3.0 + * @deprecated Deprecated since 0.9.0, please migrate to uriParseSingleUriA (with "Single"). */ int URI_FUNC(ParseUri)(URI_TYPE(ParserState) * state, const URI_CHAR * text); @@ -235,12 +244,88 @@ int URI_FUNC(ParseUri)(URI_TYPE(ParserState) * state, /** + * Parses a single RFC 3986 %URI. + * Uses default libc-based memory manager. + * + * @param uri <b>OUT</b>: Output %URI, must not be NULL + * @param text <b>IN</b>: Pointer to the first character to parse, + * must not be NULL + * @param errorPos <b>OUT</b>: Pointer to a pointer to the first character + * causing a syntax error, can be NULL; + * only set when URI_ERROR_SYNTAX was returned + * @return 0 on success, error code otherwise + * + * @see uriParseSingleUriExA + * @see uriParseSingleUriExMmA + * @see uriToStringA + * @since 0.9.0 + */ +int URI_FUNC(ParseSingleUri)(URI_TYPE(Uri) * uri, const URI_CHAR * text, + const URI_CHAR ** errorPos); + + + +/** + * Parses a single RFC 3986 %URI. + * Uses default libc-based memory manager. + * + * @param uri <b>OUT</b>: Output %URI, must not be NULL + * @param first <b>IN</b>: Pointer to the first character to parse, + * must not be NULL + * @param afterLast <b>IN</b>: Pointer to the character after the last to + * parse, can be NULL + * (to use first + strlen(first)) + * @param errorPos <b>OUT</b>: Pointer to a pointer to the first character + * causing a syntax error, can be NULL; + * only set when URI_ERROR_SYNTAX was returned + * @return 0 on success, error code otherwise + * + * @see uriParseSingleUriA + * @see uriParseSingleUriExMmA + * @see uriToStringA + * @since 0.9.0 + */ +int URI_FUNC(ParseSingleUriEx)(URI_TYPE(Uri) * uri, + const URI_CHAR * first, const URI_CHAR * afterLast, + const URI_CHAR ** errorPos); + + + +/** + * Parses a single RFC 3986 %URI. + * + * @param uri <b>OUT</b>: Output %URI, must not be NULL + * @param first <b>IN</b>: Pointer to the first character to parse, + * must not be NULL + * @param afterLast <b>IN</b>: Pointer to the character after the last to + * parse, can be NULL + * (to use first + strlen(first)) + * @param errorPos <b>OUT</b>: Pointer to a pointer to the first character + * causing a syntax error, can be NULL; + * only set when URI_ERROR_SYNTAX was returned + * @param memory <b>IN</b>: Memory manager to use, NULL for default libc + * @return 0 on success, error code otherwise + * + * @see uriParseSingleUriA + * @see uriParseSingleUriExA + * @see uriToStringA + * @since 0.9.0 + */ +int URI_FUNC(ParseSingleUriExMm)(URI_TYPE(Uri) * uri, + const URI_CHAR * first, const URI_CHAR * afterLast, + const URI_CHAR ** errorPos, UriMemoryManager * memory); + + + +/** * Frees all memory associated with the members * of the %URI structure. Note that the structure * itself is not freed, only its members. + * Uses default libc-based memory manager. * * @param uri <b>INOUT</b>: %URI structure whose members should be freed * + * @see uriFreeUriMembersMmA * @since 0.3.0 */ void URI_FUNC(FreeUriMembers)(URI_TYPE(Uri) * uri); @@ -248,6 +333,23 @@ void URI_FUNC(FreeUriMembers)(URI_TYPE(Uri) * uri); /** + * Frees all memory associated with the members + * of the %URI structure. Note that the structure + * itself is not freed, only its members. + * + * @param uri <b>INOUT</b>: %URI structure whose members should be freed + * @param memory <b>IN</b>: Memory manager to use, NULL for default libc + * @return 0 on success, error code otherwise + * + * @see uriFreeUriMembersA + * @since 0.9.0 + */ +int URI_FUNC(FreeUriMembersMm)(URI_TYPE(Uri) * uri, + UriMemoryManager * memory); + + + +/** * Percent-encodes all unreserved characters from the input string and * writes the encoded version to the output string. * Be sure to allocate <b>3 times</b> the space of the input buffer for @@ -342,6 +444,7 @@ const URI_CHAR * URI_FUNC(UnescapeInPlace)(URI_CHAR * inout); /** * Performs reference resolution as described in * <a href="http://tools.ietf.org/html/rfc3986#section-5.2.2">section 5.2.2 of RFC 3986</a>. + * Uses default libc-based memory manager. * NOTE: On success you have to call uriFreeUriMembersA on \p absoluteDest manually later. * * @param absoluteDest <b>OUT</b>: Result %URI @@ -349,7 +452,10 @@ const URI_CHAR * URI_FUNC(UnescapeInPlace)(URI_CHAR * inout); * @param absoluteBase <b>IN</b>: Base %URI to apply * @return Error code or 0 on success * - * @see uriRemoveBaseUriA, uriAddBaseUriExA + * @see uriRemoveBaseUriA + * @see uriRemoveBaseUriMmA + * @see uriAddBaseUriExA + * @see uriAddBaseUriExMmA * @since 0.4.0 */ int URI_FUNC(AddBaseUri)(URI_TYPE(Uri) * absoluteDest, @@ -361,6 +467,7 @@ int URI_FUNC(AddBaseUri)(URI_TYPE(Uri) * absoluteDest, /** * Performs reference resolution as described in * <a href="http://tools.ietf.org/html/rfc3986#section-5.2.2">section 5.2.2 of RFC 3986</a>. + * Uses default libc-based memory manager. * NOTE: On success you have to call uriFreeUriMembersA on \p absoluteDest manually later. * * @param absoluteDest <b>OUT</b>: Result %URI @@ -369,7 +476,9 @@ int URI_FUNC(AddBaseUri)(URI_TYPE(Uri) * absoluteDest, * @param options <b>IN</b>: Configuration to apply * @return Error code or 0 on success * - * @see uriRemoveBaseUriA, uriAddBaseUriA + * @see uriRemoveBaseUriA + * @see uriAddBaseUriA + * @see uriAddBaseUriExMmA * @since 0.8.1 */ int URI_FUNC(AddBaseUriEx)(URI_TYPE(Uri) * absoluteDest, @@ -380,11 +489,37 @@ int URI_FUNC(AddBaseUriEx)(URI_TYPE(Uri) * absoluteDest, /** + * Performs reference resolution as described in + * <a href="http://tools.ietf.org/html/rfc3986#section-5.2.2">section 5.2.2 of RFC 3986</a>. + * NOTE: On success you have to call uriFreeUriMembersMmA on \p absoluteDest manually later. + * + * @param absoluteDest <b>OUT</b>: Result %URI + * @param relativeSource <b>IN</b>: Reference to resolve + * @param absoluteBase <b>IN</b>: Base %URI to apply + * @param options <b>IN</b>: Configuration to apply + * @param memory <b>IN</b>: Memory manager to use, NULL for default libc + * @return Error code or 0 on success + * + * @see uriRemoveBaseUriA + * @see uriRemoveBaseUriMmA + * @see uriAddBaseUriA + * @see uriAddBaseUriExA + * @since 0.9.0 + */ +int URI_FUNC(AddBaseUriExMm)(URI_TYPE(Uri) * absoluteDest, + const URI_TYPE(Uri) * relativeSource, + const URI_TYPE(Uri) * absoluteBase, + UriResolutionOptions options, UriMemoryManager * memory); + + + +/** * Tries to make a relative %URI (a reference) from an * absolute %URI and a given base %URI. The resulting %URI is going to be * relative if the absolute %URI and base %UI share both scheme and authority. * If that is not the case, the result will still be * an absolute URI (with scheme part if necessary). + * Uses default libc-based memory manager. * NOTE: On success you have to call uriFreeUriMembersA on * \p dest manually later. * @@ -394,7 +529,10 @@ int URI_FUNC(AddBaseUriEx)(URI_TYPE(Uri) * absoluteDest, * @param domainRootMode <b>IN</b>: Create %URI with path relative to domain root * @return Error code or 0 on success * - * @see uriAddBaseUriA, uriAddBaseUriExA + * @see uriRemoveBaseUriMmA + * @see uriAddBaseUriA + * @see uriAddBaseUriExA + * @see uriAddBaseUriExMmA * @since 0.5.2 */ int URI_FUNC(RemoveBaseUri)(URI_TYPE(Uri) * dest, @@ -405,6 +543,35 @@ int URI_FUNC(RemoveBaseUri)(URI_TYPE(Uri) * dest, /** + * Tries to make a relative %URI (a reference) from an + * absolute %URI and a given base %URI. The resulting %URI is going to be + * relative if the absolute %URI and base %UI share both scheme and authority. + * If that is not the case, the result will still be + * an absolute URI (with scheme part if necessary). + * NOTE: On success you have to call uriFreeUriMembersMmA on + * \p dest manually later. + * + * @param dest <b>OUT</b>: Result %URI + * @param absoluteSource <b>IN</b>: Absolute %URI to make relative + * @param absoluteBase <b>IN</b>: Base %URI + * @param domainRootMode <b>IN</b>: Create %URI with path relative to domain root + * @param memory <b>IN</b>: Memory manager to use, NULL for default libc + * @return Error code or 0 on success + * + * @see uriRemoveBaseUriA + * @see uriAddBaseUriA + * @see uriAddBaseUriExA + * @see uriAddBaseUriExMmA + * @since 0.9.0 + */ +int URI_FUNC(RemoveBaseUriMm)(URI_TYPE(Uri) * dest, + const URI_TYPE(Uri) * absoluteSource, + const URI_TYPE(Uri) * absoluteBase, + UriBool domainRootMode, UriMemoryManager * memory); + + + +/** * Checks two URIs for equivalence. Comparison is done * the naive way, without prior normalization. * NOTE: Two <c>NULL</c> URIs are equal as well. @@ -460,24 +627,48 @@ int URI_FUNC(ToString)(URI_CHAR * dest, const URI_TYPE(Uri) * uri, int maxChars, * @return Normalization job mask * * @see uriNormalizeSyntaxA + * @see uriNormalizeSyntaxExA + * @see uriNormalizeSyntaxExMmA + * @see uriNormalizeSyntaxMaskRequiredExA * @since 0.5.0 + * @deprecated Deprecated since 0.9.0, please migrate to uriNormalizeSyntaxMaskRequiredExA (with "Ex"). */ unsigned int URI_FUNC(NormalizeSyntaxMaskRequired)(const URI_TYPE(Uri) * uri); /** + * Determines the components of a %URI that are not normalized. + * + * @param uri <b>IN</b>: %URI to check + * @param outMask <b>OUT</b>: Normalization job mask + * @return Error code or 0 on success + * + * @see uriNormalizeSyntaxA + * @see uriNormalizeSyntaxExA + * @see uriNormalizeSyntaxExMmA + * @see uriNormalizeSyntaxMaskRequiredA + * @since 0.9.0 + */ +int URI_FUNC(NormalizeSyntaxMaskRequiredEx)(const URI_TYPE(Uri) * uri, + unsigned int * outMask); + + + +/** * 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. + * Uses default libc-based memory manager. * * @param uri <b>INOUT</b>: %URI to normalize * @param mask <b>IN</b>: Normalization mask * @return Error code or 0 on success * * @see uriNormalizeSyntaxA + * @see uriNormalizeSyntaxExMmA * @see uriNormalizeSyntaxMaskRequiredA * @since 0.5.0 */ @@ -486,15 +677,39 @@ int URI_FUNC(NormalizeSyntaxEx)(URI_TYPE(Uri) * 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. + * + * @param uri <b>INOUT</b>: %URI to normalize + * @param mask <b>IN</b>: Normalization mask + * @param memory <b>IN</b>: Memory manager to use, NULL for default libc + * @return Error code or 0 on success + * + * @see uriNormalizeSyntaxA + * @see uriNormalizeSyntaxExA + * @see uriNormalizeSyntaxMaskRequiredA + * @since 0.9.0 + */ +int URI_FUNC(NormalizeSyntaxExMm)(URI_TYPE(Uri) * uri, unsigned int mask, + UriMemoryManager * memory); + + + +/** * 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. + * Uses default libc-based memory manager. * * @param uri <b>INOUT</b>: %URI to normalize * @return Error code or 0 on success * * @see uriNormalizeSyntaxExA + * @see uriNormalizeSyntaxExMmA * @see uriNormalizeSyntaxMaskRequiredA * @since 0.5.0 */ @@ -639,8 +854,12 @@ int URI_FUNC(ComposeQueryCharsRequiredEx)(const URI_TYPE(QueryList) * queryList, * * @see uriComposeQueryExA * @see uriComposeQueryMallocA + * @see uriComposeQueryMallocExA + * @see uriComposeQueryMallocExMmA * @see uriComposeQueryCharsRequiredA * @see uriDissectQueryMallocA + * @see uriDissectQueryMallocExA + * @see uriDissectQueryMallocExMmA * @since 0.7.0 */ int URI_FUNC(ComposeQuery)(URI_CHAR * dest, @@ -661,9 +880,13 @@ int URI_FUNC(ComposeQuery)(URI_CHAR * dest, * @return Error code or 0 on success * * @see uriComposeQueryA + * @see uriComposeQueryMallocA * @see uriComposeQueryMallocExA + * @see uriComposeQueryMallocExMmA * @see uriComposeQueryCharsRequiredExA + * @see uriDissectQueryMallocA * @see uriDissectQueryMallocExA + * @see uriDissectQueryMallocExMmA * @since 0.7.0 */ int URI_FUNC(ComposeQueryEx)(URI_CHAR * dest, @@ -678,14 +901,18 @@ int URI_FUNC(ComposeQueryEx)(URI_CHAR * dest, * The composed string does not start with '?', * on the way ' ' is converted to '+' and line breaks are * normalized to "%0D%0A". + * Uses default libc-based memory manager. * * @param dest <b>OUT</b>: Output destination * @param queryList <b>IN</b>: Query list to convert * @return Error code or 0 on success * * @see uriComposeQueryMallocExA + * @see uriComposeQueryMallocExMmA * @see uriComposeQueryA * @see uriDissectQueryMallocA + * @see uriDissectQueryMallocExA + * @see uriDissectQueryMallocExMmA * @since 0.7.0 */ int URI_FUNC(ComposeQueryMalloc)(URI_CHAR ** dest, @@ -697,6 +924,7 @@ int URI_FUNC(ComposeQueryMalloc)(URI_CHAR ** dest, * Converts a query list structure back to a query string. * Memory for this string is allocated internally. * The composed string does not start with '?'. + * Uses default libc-based memory manager. * * @param dest <b>OUT</b>: Output destination * @param queryList <b>IN</b>: Query list to convert @@ -705,8 +933,11 @@ int URI_FUNC(ComposeQueryMalloc)(URI_CHAR ** dest, * @return Error code or 0 on success * * @see uriComposeQueryMallocA + * @see uriComposeQueryMallocExMmA * @see uriComposeQueryExA + * @see uriDissectQueryMallocA * @see uriDissectQueryMallocExA + * @see uriDissectQueryMallocExMmA * @since 0.7.0 */ int URI_FUNC(ComposeQueryMallocEx)(URI_CHAR ** dest, @@ -716,8 +947,36 @@ int URI_FUNC(ComposeQueryMallocEx)(URI_CHAR ** dest, /** + * Converts a query list structure back to a query string. + * Memory for this string is allocated internally. + * The composed string does not start with '?'. + * + * @param dest <b>OUT</b>: Output destination + * @param queryList <b>IN</b>: Query list to convert + * @param spaceToPlus <b>IN</b>: Whether to convert ' ' to '+' or not + * @param normalizeBreaks <b>IN</b>: Whether to convert CR and LF to CR-LF or not. + * @param memory <b>IN</b>: Memory manager to use, NULL for default libc + * @return Error code or 0 on success + * + * @see uriComposeQueryMallocA + * @see uriComposeQueryMallocExA + * @see uriComposeQueryExA + * @see uriDissectQueryMallocA + * @see uriDissectQueryMallocExA + * @see uriDissectQueryMallocExMmA + * @since 0.9.0 + */ +int URI_FUNC(ComposeQueryMallocExMm)(URI_CHAR ** dest, + const URI_TYPE(QueryList) * queryList, + UriBool spaceToPlus, UriBool normalizeBreaks, + UriMemoryManager * memory); + + + +/** * 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. + * Uses default libc-based memory manager. * * @param dest <b>OUT</b>: Output destination * @param itemCount <b>OUT</b>: Number of items found, can be NULL @@ -726,8 +985,10 @@ int URI_FUNC(ComposeQueryMallocEx)(URI_CHAR ** dest, * @return Error code or 0 on success * * @see uriDissectQueryMallocExA + * @see uriDissectQueryMallocExMmA * @see uriComposeQueryA * @see uriFreeQueryListA + * @see uriFreeQueryListMmA * @since 0.7.0 */ int URI_FUNC(DissectQueryMalloc)(URI_TYPE(QueryList) ** dest, int * itemCount, @@ -737,6 +998,7 @@ int URI_FUNC(DissectQueryMalloc)(URI_TYPE(QueryList) ** dest, int * itemCount, /** * Constructs a query list from the raw query string of a given URI. + * Uses default libc-based memory manager. * * @param dest <b>OUT</b>: Output destination * @param itemCount <b>OUT</b>: Number of items found, can be NULL @@ -747,6 +1009,7 @@ int URI_FUNC(DissectQueryMalloc)(URI_TYPE(QueryList) ** dest, int * itemCount, * @return Error code or 0 on success * * @see uriDissectQueryMallocA + * @see uriDissectQueryMallocExMmA * @see uriComposeQueryExA * @see uriFreeQueryListA * @since 0.7.0 @@ -758,17 +1021,60 @@ int URI_FUNC(DissectQueryMallocEx)(URI_TYPE(QueryList) ** dest, int * itemCount, /** + * Constructs a query list from the raw query string of a given URI. + * + * @param dest <b>OUT</b>: Output destination + * @param itemCount <b>OUT</b>: Number of items found, can be NULL + * @param first <b>IN</b>: Pointer to first character <b>after</b> '?' + * @param afterLast <b>IN</b>: Pointer to character after the last one still in + * @param plusToSpace <b>IN</b>: Whether to convert '+' to ' ' or not + * @param breakConversion <b>IN</b>: Line break conversion mode + * @param memory <b>IN</b>: Memory manager to use, NULL for default libc + * @return Error code or 0 on success + * + * @see uriDissectQueryMallocA + * @see uriDissectQueryMallocExA + * @see uriComposeQueryExA + * @see uriFreeQueryListA + * @see uriFreeQueryListMmA + * @since 0.9.0 + */ +int URI_FUNC(DissectQueryMallocExMm)(URI_TYPE(QueryList) ** dest, int * itemCount, + const URI_CHAR * first, const URI_CHAR * afterLast, + UriBool plusToSpace, UriBreakConversion breakConversion, + UriMemoryManager * memory); + + + +/** * Frees all memory associated with the given query list. * The structure itself is freed as well. * * @param queryList <b>INOUT</b>: Query list to free * + * @see uriFreeQueryListMmA * @since 0.7.0 */ void URI_FUNC(FreeQueryList)(URI_TYPE(QueryList) * queryList); +/** + * Frees all memory associated with the given query list. + * The structure itself is freed as well. + * + * @param queryList <b>INOUT</b>: Query list to free + * @param memory <b>IN</b>: Memory manager to use, NULL for default libc + * @return Error code or 0 on success + * + * @see uriFreeQueryListA + * @since 0.9.0 + */ +int URI_FUNC(FreeQueryListMm)(URI_TYPE(QueryList) * queryList, + UriMemoryManager * memory); + + + #ifdef __cplusplus } #endif diff --git a/include/uriparser/UriBase.h b/include/uriparser/UriBase.h index 0c2a5e7..f396235 100644 --- a/include/uriparser/UriBase.h +++ b/include/uriparser/UriBase.h @@ -54,8 +54,8 @@ /* Version */ #define URI_VER_MAJOR 0 -#define URI_VER_MINOR 8 -#define URI_VER_RELEASE 6 +#define URI_VER_MINOR 9 +#define URI_VER_RELEASE 0 #define URI_VER_SUFFIX_ANSI "" #define URI_VER_SUFFIX_UNICODE URI_ANSI_TO_UNICODE(URI_VER_SUFFIX_ANSI) @@ -113,6 +113,7 @@ typedef int UriBool; /**< Boolean type */ #define URI_ERROR_OUTPUT_TOO_LARGE 4 /* Some output is to large for the receiving buffer */ #define URI_ERROR_NOT_IMPLEMENTED 8 /* The called function is not implemented yet */ #define URI_ERROR_RANGE_INVALID 9 /* The parameters passed contained invalid ranges */ +#define URI_ERROR_MEMORY_MANAGER_INCOMPLETE 10 /* [>=0.9.0] The UriMemoryManager passed does not implement all needed functions */ /* Errors specific to ToString */ @@ -125,6 +126,8 @@ typedef int UriBool; /**< Boolean type */ #define URI_ERROR_REMOVEBASE_REL_BASE 6 /* Given base is not absolute */ #define URI_ERROR_REMOVEBASE_REL_SOURCE 7 /* Given base is not absolute */ +/* Error specific to uriTestMemoryManager */ +#define URI_ERROR_MEMORY_MANAGER_FAULTY 11 /* [>=0.9.0] The UriMemoryManager given did not pass the test suite */ #ifndef URI_DOXYGEN @@ -153,6 +156,63 @@ typedef struct UriIp6Struct { } UriIp6; /**< @copydoc UriIp6Struct */ +struct UriMemoryManagerStruct; /* foward declaration to break loop */ + + +/** + * Function signature that custom malloc(3) functions must conform to + * + * @since 0.9.0 + */ +typedef void * (*UriFuncMalloc)(struct UriMemoryManagerStruct *, size_t); + +/** + * Function signature that custom calloc(3) functions must conform to + * + * @since 0.9.0 + */ +typedef void * (*UriFuncCalloc)(struct UriMemoryManagerStruct *, size_t, size_t); + +/** + * Function signature that custom realloc(3) functions must conform to + * + * @since 0.9.0 + */ +typedef void * (*UriFuncRealloc)(struct UriMemoryManagerStruct *, void *, size_t); + +/** + * Function signature that custom reallocarray(3) functions must conform to + * + * @since 0.9.0 + */ +typedef void * (*UriFuncReallocarray)(struct UriMemoryManagerStruct *, void *, size_t, size_t); + +/** + * Function signature that custom free(3) functions must conform to + * + * @since 0.9.0 + */ +typedef void (*UriFuncFree)(struct UriMemoryManagerStruct *, void *); + + +/** + * Class-like interface of custom memory managers + * + * @see uriCompleteMemoryManager + * @see uriEmulateCalloc + * @see uriEmulateReallocarray + * @see uriTestMemoryManager + * @since 0.9.0 + */ +typedef struct UriMemoryManagerStruct { + UriFuncMalloc malloc; /**< Pointer to custom malloc(3) */ + UriFuncCalloc calloc; /**< Pointer to custom calloc(3); to emulate using malloc and memset see uriEmulateCalloc */ + UriFuncRealloc realloc; /**< Pointer to custom realloc(3) */ + UriFuncReallocarray reallocarray; /**< Pointer to custom reallocarray(3); to emulate using realloc see uriEmulateReallocarray */ + UriFuncFree free; /**< Pointer to custom free(3) */ + void * userData; /**< Pointer to data that the other function members need access to */ +} UriMemoryManager; /**< @copydoc UriMemoryManagerStruct */ + /** * Specifies a line break conversion mode. @@ -194,4 +254,101 @@ typedef enum UriResolutionOptionsEnum { +/** + * Wraps a memory manager backend that only provides malloc and free + * to make a complete memory manager ready to be used. + * + * The core feature of this wrapper is that you don't need to implement + * realloc if you don't want to. The wrapped memory manager uses + * backend->malloc, memcpy, and backend->free and soieof(size_t) extra + * bytes per allocation to emulate fallback realloc for you. + * + * memory->calloc is uriEmulateCalloc. + * memory->free uses backend->free and handles the size header. + * memory->malloc uses backend->malloc and adds a size header. + * memory->realloc uses memory->malloc, memcpy, and memory->free and reads + * the size header. + * memory->reallocarray is uriEmulateReallocarray. + * + * The internal workings behind memory->free, memory->malloc, and + * memory->realloc may change so the functions exposed by these function + * pointer sshould be consided internal and not public API. + * + * @param memory <b>OUT</b>: Where to write the wrapped memory manager to + * @param backend <b>IN</b>: Memory manager to use as a backend + * @return Error code or 0 on success + * + * @see uriEmulateCalloc + * @see uriEmulateReallocarray + * @see UriMemoryManager + * @since 0.9.0 + */ +int uriCompleteMemoryManager(UriMemoryManager * memory, + UriMemoryManager * backend); + + + +/** + * Offers emulation of calloc(3) based on memory->malloc and memset. + * See "man 3 calloc" as well. + * + * @param memory <b>IN</b>: Memory manager to use, should not be NULL + * @param nmemb <b>IN</b>: Number of elements to allocate + * @param size <b>IN</b>: Size in bytes per element + * @return Pointer to allocated memory or NULL + * + * @see uriCompleteMemoryManager + * @see uriEmulateReallocarray + * @see UriMemoryManager + * @since 0.9.0 + */ +void * uriEmulateCalloc(UriMemoryManager * memory, + size_t nmemb, size_t size); + + + +/** + * Offers emulation of reallocarray(3) based on memory->realloc. + * See "man 3 reallocarray" as well. + * + * @param memory <b>IN</b>: Memory manager to use, should not be NULL + * @param ptr <b>IN</b>: Pointer allocated using memory->malloc/... or NULL + * @param nmemb <b>IN</b>: Number of elements to allocate + * @param size <b>IN</b>: Size in bytes per element + * @return Pointer to allocated memory or NULL + * + * @see uriCompleteMemoryManager + * @see uriEmulateCalloc + * @see UriMemoryManager + * @since 0.9.0 + */ +void * uriEmulateReallocarray(UriMemoryManager * memory, + void * ptr, size_t nmemb, size_t size); + + + +/** + * Run multiple tests against a given memory manager. + * For example, one test + * 1. allocates a small amount of memory, + * 2. writes some magic bytes to it, + * 3. reallocates it, + * 4. checks that previous values are still present, + * 5. and frees that memory. + * + * It is recommended to compile with AddressSanitizer enabled + * to take full advantage of uriTestMemoryManager. + * + * @param memory <b>IN</b>: Memory manager to use, should not be NULL + * @return Error code or 0 on success + * + * @see uriEmulateCalloc + * @see uriEmulateReallocarray + * @see UriMemoryManager + * @since 0.9.0 + */ +int uriTestMemoryManager(UriMemoryManager * memory); + + + #endif /* URI_BASE_H */ diff --git a/include/uriparser/UriDefsConfig.h b/include/uriparser/UriDefsConfig.h index 9f7ac65..9af4968 100644 --- a/include/uriparser/UriDefsConfig.h +++ b/include/uriparser/UriDefsConfig.h @@ -76,7 +76,7 @@ /* Function inlining, not ANSI/ISO C! */ -#if (defined(URI_DOXYGEN) || defined(URI_SIZEDOWN)) +#if defined(URI_DOXYGEN) # define URI_INLINE #elif defined(__INTEL_COMPILER) /* Intel C/C++ */ |