lz4hc.h (11596B)
1 /* 2 LZ4 HC - High Compression Mode of LZ4 3 Header File 4 Copyright (C) 2011-2016, Yann Collet. 5 BSD 2-Clause License (http://www.opensource.org/licenses/bsd-license.php) 6 7 Redistribution and use in source and binary forms, with or without 8 modification, are permitted provided that the following conditions are 9 met: 10 11 * Redistributions of source code must retain the above copyright 12 notice, this list of conditions and the following disclaimer. 13 * Redistributions in binary form must reproduce the above 14 copyright notice, this list of conditions and the following disclaimer 15 in the documentation and/or other materials provided with the 16 distribution. 17 18 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 19 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 20 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 21 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 22 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 23 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 24 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 25 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 26 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 27 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 28 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 29 30 You can contact the author at : 31 - LZ4 source repository : https://github.com/lz4/lz4 32 - LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c 33 */ 34 #ifndef LZ4_HC_H_19834876238432 35 #define LZ4_HC_H_19834876238432 36 37 #if defined (__cplusplus) 38 extern "C" { 39 #endif 40 41 /* --- Dependency --- */ 42 /* note : lz4hc is not an independent module, it requires lz4.h/lz4.c for proper compilation */ 43 #include "lz4.h" /* stddef, LZ4LIB_API, LZ4_DEPRECATED */ 44 45 46 /* --- Useful constants --- */ 47 #define LZ4HC_MIN_CLEVEL 3 48 #define LZ4HC_DEFAULT_CLEVEL 9 49 #define LZ4HC_MAX_CLEVEL 16 50 51 52 /*-************************************ 53 * Block Compression 54 **************************************/ 55 /*! LZ4_compress_HC() : 56 * Compress data from `src` into `dst`, using the more powerful but slower "HC" algorithm. 57 * `dst` must be already allocated. 58 * Compression is guaranteed to succeed if `dstCapacity >= LZ4_compressBound(srcSize)` (see "lz4.h") 59 * Max supported `srcSize` value is LZ4_MAX_INPUT_SIZE (see "lz4.h") 60 * `compressionLevel` : Recommended values are between 4 and 9, although any value between 1 and LZ4HC_MAX_CLEVEL will work. 61 * Values >LZ4HC_MAX_CLEVEL behave the same as 16. 62 * @return : the number of bytes written into 'dst' 63 * or 0 if compression fails. 64 */ 65 LZ4LIB_API int LZ4_compress_HC (const char* src, char* dst, int srcSize, int dstCapacity, int compressionLevel); 66 67 68 /* Note : 69 * Decompression functions are provided within "lz4.h" (BSD license) 70 */ 71 72 73 /*! LZ4_compress_HC_extStateHC() : 74 * Same as LZ4_compress_HC(), but using an externally allocated memory segment for `state`. 75 * `state` size is provided by LZ4_sizeofStateHC(). 76 * Memory segment must be aligned on 8-bytes boundaries (which a normal malloc() will do properly). 77 */ 78 LZ4LIB_API int LZ4_compress_HC_extStateHC(void* state, const char* src, char* dst, int srcSize, int maxDstSize, int compressionLevel); 79 LZ4LIB_API int LZ4_sizeofStateHC(void); 80 81 82 /*-************************************ 83 * Streaming Compression 84 * Bufferless synchronous API 85 **************************************/ 86 typedef union LZ4_streamHC_u LZ4_streamHC_t; /* incomplete type (defined later) */ 87 88 /*! LZ4_createStreamHC() and LZ4_freeStreamHC() : 89 * These functions create and release memory for LZ4 HC streaming state. 90 * Newly created states are automatically initialized. 91 * Existing states can be re-used several times, using LZ4_resetStreamHC(). 92 * These methods are API and ABI stable, they can be used in combination with a DLL. 93 */ 94 LZ4LIB_API LZ4_streamHC_t* LZ4_createStreamHC(void); 95 LZ4LIB_API int LZ4_freeStreamHC (LZ4_streamHC_t* streamHCPtr); 96 97 LZ4LIB_API void LZ4_resetStreamHC (LZ4_streamHC_t* streamHCPtr, int compressionLevel); 98 LZ4LIB_API int LZ4_loadDictHC (LZ4_streamHC_t* streamHCPtr, const char* dictionary, int dictSize); 99 100 LZ4LIB_API int LZ4_compress_HC_continue (LZ4_streamHC_t* streamHCPtr, const char* src, char* dst, int srcSize, int maxDstSize); 101 102 LZ4LIB_API int LZ4_saveDictHC (LZ4_streamHC_t* streamHCPtr, char* safeBuffer, int maxDictSize); 103 104 /* 105 These functions compress data in successive blocks of any size, using previous blocks as dictionary. 106 One key assumption is that previous blocks (up to 64 KB) remain read-accessible while compressing next blocks. 107 There is an exception for ring buffers, which can be smaller than 64 KB. 108 Ring buffers scenario is automatically detected and handled by LZ4_compress_HC_continue(). 109 110 Before starting compression, state must be properly initialized, using LZ4_resetStreamHC(). 111 A first "fictional block" can then be designated as initial dictionary, using LZ4_loadDictHC() (Optional). 112 113 Then, use LZ4_compress_HC_continue() to compress each successive block. 114 Previous memory blocks (including initial dictionary when present) must remain accessible and unmodified during compression. 115 'dst' buffer should be sized to handle worst case scenarios, using LZ4_compressBound(), to ensure operation success. 116 117 If, for any reason, previous data blocks can't be preserved unmodified in memory during next compression block, 118 you must save it to a safer memory space, using LZ4_saveDictHC(). 119 Return value of LZ4_saveDictHC() is the size of dictionary effectively saved into 'safeBuffer'. 120 */ 121 122 123 /*-****************************************** 124 * !!!!! STATIC LINKING ONLY !!!!! 125 *******************************************/ 126 127 /*-************************************* 128 * PRIVATE DEFINITIONS : 129 * Do not use these definitions. 130 * They are exposed to allow static allocation of `LZ4_streamHC_t`. 131 * Using these definitions makes the code vulnerable to potential API break when upgrading LZ4 132 **************************************/ 133 #define LZ4HC_DICTIONARY_LOGSIZE 16 134 #define LZ4HC_MAXD (1<<LZ4HC_DICTIONARY_LOGSIZE) 135 #define LZ4HC_MAXD_MASK (LZ4HC_MAXD - 1) 136 137 #define LZ4HC_HASH_LOG (LZ4HC_DICTIONARY_LOGSIZE-1) 138 #define LZ4HC_HASHTABLESIZE (1 << LZ4HC_HASH_LOG) 139 #define LZ4HC_HASH_MASK (LZ4HC_HASHTABLESIZE - 1) 140 141 142 #if defined(__cplusplus) || (defined (__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 */) 143 #include <stdint.h> 144 145 typedef struct 146 { 147 uint32_t hashTable[LZ4HC_HASHTABLESIZE]; 148 uint16_t chainTable[LZ4HC_MAXD]; 149 const uint8_t* end; /* next block here to continue on current prefix */ 150 const uint8_t* base; /* All index relative to this position */ 151 const uint8_t* dictBase; /* alternate base for extDict */ 152 uint8_t* inputBuffer; /* deprecated */ 153 uint32_t dictLimit; /* below that point, need extDict */ 154 uint32_t lowLimit; /* below that point, no more dict */ 155 uint32_t nextToUpdate; /* index from which to continue dictionary update */ 156 uint32_t compressionLevel; 157 } LZ4HC_CCtx_internal; 158 159 #else 160 161 typedef struct 162 { 163 unsigned int hashTable[LZ4HC_HASHTABLESIZE]; 164 unsigned short chainTable[LZ4HC_MAXD]; 165 const unsigned char* end; /* next block here to continue on current prefix */ 166 const unsigned char* base; /* All index relative to this position */ 167 const unsigned char* dictBase; /* alternate base for extDict */ 168 unsigned char* inputBuffer; /* deprecated */ 169 unsigned int dictLimit; /* below that point, need extDict */ 170 unsigned int lowLimit; /* below that point, no more dict */ 171 unsigned int nextToUpdate; /* index from which to continue dictionary update */ 172 unsigned int compressionLevel; 173 } LZ4HC_CCtx_internal; 174 175 #endif 176 177 #define LZ4_STREAMHCSIZE 262192 178 #define LZ4_STREAMHCSIZE_SIZET (LZ4_STREAMHCSIZE / sizeof(size_t)) 179 union LZ4_streamHC_u { 180 size_t table[LZ4_STREAMHCSIZE_SIZET]; 181 LZ4HC_CCtx_internal internal_donotuse; 182 }; /* previously typedef'd to LZ4_streamHC_t */ 183 /* 184 LZ4_streamHC_t : 185 This structure allows static allocation of LZ4 HC streaming state. 186 State must be initialized using LZ4_resetStreamHC() before first use. 187 188 Static allocation shall only be used in combination with static linking. 189 When invoking LZ4 from a DLL, use create/free functions instead, which are API and ABI stable. 190 */ 191 192 193 /*-************************************ 194 * Deprecated Functions 195 **************************************/ 196 /* see lz4.h LZ4_DISABLE_DEPRECATE_WARNINGS to turn off deprecation warnings */ 197 198 /* deprecated compression functions */ 199 /* these functions will trigger warning messages in future releases */ 200 LZ4_DEPRECATED("use LZ4_compress_HC() instead") int LZ4_compressHC (const char* source, char* dest, int inputSize); 201 LZ4_DEPRECATED("use LZ4_compress_HC() instead") int LZ4_compressHC_limitedOutput (const char* source, char* dest, int inputSize, int maxOutputSize); 202 LZ4_DEPRECATED("use LZ4_compress_HC() instead") int LZ4_compressHC2 (const char* source, char* dest, int inputSize, int compressionLevel); 203 LZ4_DEPRECATED("use LZ4_compress_HC() instead") int LZ4_compressHC2_limitedOutput (const char* source, char* dest, int inputSize, int maxOutputSize, int compressionLevel); 204 LZ4_DEPRECATED("use LZ4_compress_HC_extStateHC() instead") int LZ4_compressHC_withStateHC (void* state, const char* source, char* dest, int inputSize); 205 LZ4_DEPRECATED("use LZ4_compress_HC_extStateHC() instead") int LZ4_compressHC_limitedOutput_withStateHC (void* state, const char* source, char* dest, int inputSize, int maxOutputSize); 206 LZ4_DEPRECATED("use LZ4_compress_HC_extStateHC() instead") int LZ4_compressHC2_withStateHC (void* state, const char* source, char* dest, int inputSize, int compressionLevel); 207 LZ4_DEPRECATED("use LZ4_compress_HC_extStateHC() instead") int LZ4_compressHC2_limitedOutput_withStateHC(void* state, const char* source, char* dest, int inputSize, int maxOutputSize, int compressionLevel); 208 LZ4_DEPRECATED("use LZ4_compress_HC_continue() instead") int LZ4_compressHC_continue (LZ4_streamHC_t* LZ4_streamHCPtr, const char* source, char* dest, int inputSize); 209 LZ4_DEPRECATED("use LZ4_compress_HC_continue() instead") int LZ4_compressHC_limitedOutput_continue (LZ4_streamHC_t* LZ4_streamHCPtr, const char* source, char* dest, int inputSize, int maxOutputSize); 210 211 /* Deprecated Streaming functions using older model; should no longer be used */ 212 LZ4_DEPRECATED("use LZ4_createStreamHC() instead") void* LZ4_createHC (char* inputBuffer); 213 LZ4_DEPRECATED("use LZ4_saveDictHC() instead") char* LZ4_slideInputBufferHC (void* LZ4HC_Data); 214 LZ4_DEPRECATED("use LZ4_freeStreamHC() instead") int LZ4_freeHC (void* LZ4HC_Data); 215 LZ4_DEPRECATED("use LZ4_compress_HC_continue() instead") int LZ4_compressHC2_continue (void* LZ4HC_Data, const char* source, char* dest, int inputSize, int compressionLevel); 216 LZ4_DEPRECATED("use LZ4_compress_HC_continue() instead") int LZ4_compressHC2_limitedOutput_continue (void* LZ4HC_Data, const char* source, char* dest, int inputSize, int maxOutputSize, int compressionLevel); 217 LZ4_DEPRECATED("use LZ4_createStreamHC() instead") int LZ4_sizeofStreamStateHC(void); 218 LZ4_DEPRECATED("use LZ4_resetStreamHC() instead") int LZ4_resetStreamStateHC(void* state, char* inputBuffer); 219 220 221 #if defined (__cplusplus) 222 } 223 #endif 224 225 #endif /* LZ4_HC_H_19834876238432 */