diff options
Diffstat (limited to 'include/uriparser/UriBase.h')
| -rw-r--r-- | include/uriparser/UriBase.h | 161 |
1 files changed, 159 insertions, 2 deletions
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 */ |