1 /* 2 Lizard - Fast LZ compression algorithm 3 Header File 4 Copyright (C) 2011-2016, Yann Collet 5 Copyright (C) 2016-2017, Przemyslaw Skibinski <inikep@gmail.com> 6 7 BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php) 8 9 Redistribution and use in source and binary forms, with or without 10 modification, are permitted provided that the following conditions are 11 met: 12 13 * Redistributions of source code must retain the above copyright 14 notice, this list of conditions and the following disclaimer. 15 * Redistributions in binary form must reproduce the above 16 copyright notice, this list of conditions and the following disclaimer 17 in the documentation and/or other materials provided with the 18 distribution. 19 20 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 23 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 24 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 25 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 26 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 27 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 28 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 32 You can contact the author at : 33 - Lizard source repository : https://github.com/inikep/lizard 34 */ 35 #ifndef LIZARD_H_2983 36 #define LIZARD_H_2983 37 38 #if defined (__cplusplus) 39 extern "C" { 40 #endif 41 42 /* 43 * lizard_compress.h provides block compression functions. It gives full buffer control to user. 44 * Block compression functions are not-enough to send information, 45 * since it's still necessary to provide metadata (such as compressed size), 46 * and each application can do it in whichever way it wants. 47 * For interoperability, there is Lizard frame specification (lizard_Frame_format.md). 48 * A library is provided to take care of it, see lizard_frame.h. 49 */ 50 51 52 /*^*************************************************************** 53 * Export parameters 54 *****************************************************************/ 55 /* 56 * LIZARD_DLL_EXPORT : 57 * Enable exporting of functions when building a Windows DLL 58 */ 59 #if defined(LIZARD_DLL_EXPORT) && (LIZARD_DLL_EXPORT==1) 60 # define LIZARDLIB_API __declspec(dllexport) 61 #elif defined(LIZARD_DLL_IMPORT) && (LIZARD_DLL_IMPORT==1) 62 # define LIZARDLIB_API __declspec(dllimport) /* It isn't required but allows to generate better code, saving a function pointer load from the IAT and an indirect jump.*/ 63 #else 64 # define LIZARDLIB_API 65 #endif 66 67 68 /*-************************************ 69 * Version 70 **************************************/ 71 #define LIZARD_VERSION_MAJOR 1 /* for breaking interface changes */ 72 #define LIZARD_VERSION_MINOR 0 /* for new (non-breaking) interface capabilities */ 73 #define LIZARD_VERSION_RELEASE 0 /* for tweaks, bug-fixes, or development */ 74 75 #define LIZARD_VERSION_NUMBER (LIZARD_VERSION_MAJOR *100*100 + LIZARD_VERSION_MINOR *100 + LIZARD_VERSION_RELEASE) 76 int Lizard_versionNumber (void); 77 78 #define LIZARD_LIB_VERSION LIZARD_VERSION_MAJOR.LIZARD_VERSION_MINOR.LIZARD_VERSION_RELEASE 79 #define LIZARD_QUOTE(str) #str 80 #define LIZARD_EXPAND_AND_QUOTE(str) LIZARD_QUOTE(str) 81 #define LIZARD_VERSION_STRING LIZARD_EXPAND_AND_QUOTE(LIZARD_LIB_VERSION) 82 const char* Lizard_versionString (void); 83 84 typedef struct Lizard_stream_s Lizard_stream_t; 85 86 #define LIZARD_MIN_CLEVEL 10 /* minimum compression level */ 87 #ifndef LIZARD_NO_HUFFMAN 88 #define LIZARD_MAX_CLEVEL 49 /* maximum compression level */ 89 #else 90 #define LIZARD_MAX_CLEVEL 29 /* maximum compression level */ 91 #endif 92 #define LIZARD_DEFAULT_CLEVEL 17 93 94 95 /*-************************************ 96 * Simple Functions 97 **************************************/ 98 99 LIZARDLIB_API int Lizard_compress (const char* src, char* dst, int srcSize, int maxDstSize, int compressionLevel); 100 101 /* 102 Lizard_compress() : 103 Compresses 'sourceSize' bytes from buffer 'source' 104 into already allocated 'dest' buffer of size 'maxDestSize'. 105 Compression is guaranteed to succeed if 'maxDestSize' >= Lizard_compressBound(sourceSize). 106 It also runs faster, so it's a recommended setting. 107 If the function cannot compress 'source' into a more limited 'dest' budget, 108 compression stops *immediately*, and the function result is zero. 109 As a consequence, 'dest' content is not valid. 110 This function never writes outside 'dest' buffer, nor read outside 'source' buffer. 111 sourceSize : Max supported value is LIZARD_MAX_INPUT_VALUE 112 maxDestSize : full or partial size of buffer 'dest' (which must be already allocated) 113 return : the number of bytes written into buffer 'dest' (necessarily <= maxOutputSize) 114 or 0 if compression fails 115 */ 116 117 118 /*-************************************ 119 * Advanced Functions 120 **************************************/ 121 #define LIZARD_MAX_INPUT_SIZE 0x7E000000 /* 2 113 929 216 bytes */ 122 #define LIZARD_BLOCK_SIZE (1<<17) 123 #define LIZARD_BLOCK64K_SIZE (1<<16) 124 #define LIZARD_COMPRESSBOUND(isize) ((unsigned)(isize) > (unsigned)LIZARD_MAX_INPUT_SIZE ? 0 : (isize) + 1 + 1 + ((isize/LIZARD_BLOCK_SIZE)+1)*4) 125 126 127 /*! 128 Lizard_compressBound() : 129 Provides the maximum size that Lizard compression may output in a "worst case" scenario (input data not compressible) 130 This function is primarily useful for memory allocation purposes (destination buffer size). 131 Macro LIZARD_COMPRESSBOUND() is also provided for compilation-time evaluation (stack memory allocation for example). 132 Note that Lizard_compress() compress faster when dest buffer size is >= Lizard_compressBound(srcSize) 133 inputSize : max supported value is LIZARD_MAX_INPUT_SIZE 134 return : maximum output size in a "worst case" scenario 135 or 0, if input size is too large ( > LIZARD_MAX_INPUT_SIZE) 136 */ 137 LIZARDLIB_API int Lizard_compressBound(int inputSize); 138 139 140 /*! 141 Lizard_compress_extState() : 142 Same compression function, just using an externally allocated memory space to store compression state. 143 Use Lizard_sizeofState() to know how much memory must be allocated, 144 and allocate it on 8-bytes boundaries (using malloc() typically). 145 Then, provide it as 'void* state' to compression function. 146 */ 147 LIZARDLIB_API int Lizard_sizeofState(int compressionLevel); 148 149 LIZARDLIB_API int Lizard_compress_extState(void* state, const char* src, char* dst, int srcSize, int maxDstSize, int compressionLevel); 150 151 152 153 /*-********************************************* 154 * Streaming Compression Functions 155 ***********************************************/ 156 157 /*! Lizard_createStream() will allocate and initialize an `Lizard_stream_t` structure. 158 * Lizard_freeStream() releases its memory. 159 * In the context of a DLL (liblizard), please use these methods rather than the static struct. 160 * They are more future proof, in case of a change of `Lizard_stream_t` size. 161 */ 162 LIZARDLIB_API Lizard_stream_t* Lizard_createStream(int compressionLevel); 163 LIZARDLIB_API int Lizard_freeStream (Lizard_stream_t* streamPtr); 164 165 166 /*! Lizard_resetStream() : 167 * Use this function to reset/reuse an allocated `Lizard_stream_t` structure 168 */ 169 LIZARDLIB_API Lizard_stream_t* Lizard_resetStream (Lizard_stream_t* streamPtr, int compressionLevel); 170 171 172 /*! Lizard_loadDict() : 173 * Use this function to load a static dictionary into Lizard_stream. 174 * Any previous data will be forgotten, only 'dictionary' will remain in memory. 175 * Loading a size of 0 is allowed. 176 * Return : dictionary size, in bytes (necessarily <= LIZARD_DICT_SIZE) 177 */ 178 LIZARDLIB_API int Lizard_loadDict (Lizard_stream_t* streamPtr, const char* dictionary, int dictSize); 179 180 181 /*! Lizard_compress_continue() : 182 * Compress buffer content 'src', using data from previously compressed blocks as dictionary to improve compression ratio. 183 * Important : Previous data blocks are assumed to still be present and unmodified ! 184 * 'dst' buffer must be already allocated. 185 * If maxDstSize >= Lizard_compressBound(srcSize), compression is guaranteed to succeed, and runs faster. 186 * If not, and if compressed data cannot fit into 'dst' buffer size, compression stops, and function returns a zero. 187 */ 188 LIZARDLIB_API int Lizard_compress_continue (Lizard_stream_t* streamPtr, const char* src, char* dst, int srcSize, int maxDstSize); 189 190 191 /*! Lizard_saveDict() : 192 * If previously compressed data block is not guaranteed to remain available at its memory location, 193 * save it into a safer place (char* safeBuffer). 194 * Note : you don't need to call Lizard_loadDict() afterwards, 195 * dictionary is immediately usable, you can therefore call Lizard_compress_continue(). 196 * Return : saved dictionary size in bytes (necessarily <= dictSize), or 0 if error. 197 */ 198 LIZARDLIB_API int Lizard_saveDict (Lizard_stream_t* streamPtr, char* safeBuffer, int dictSize); 199 200 201 202 203 204 #if defined (__cplusplus) 205 } 206 #endif 207 208 #endif /* LIZARD_H_2983827168210 */ 209