nlib
lz4hc.h
1 /*
2  LZ4 HC - High Compression Mode of LZ4
3  Header File
4  Copyright (C) 2011-2017, 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 requires lz4.h/lz4.c for compilation */
43 #include "lz4.h" /* stddef, LZ4LIB_API, LZ4_DEPRECATED */
44 
45 
46 /* --- Useful constants --- */
47 #define LZ4HC_CLEVEL_MIN 3
48 #define LZ4HC_CLEVEL_DEFAULT 9
49 #define LZ4HC_CLEVEL_OPT_MIN 10
50 #define LZ4HC_CLEVEL_MAX 12
51 
52 
53 /*-************************************
54  * Block Compression
55  **************************************/
66 LZ4LIB_API int LZ4_compress_HC (const char* src, char* dst, int srcSize, int dstCapacity, int compressionLevel);
67 
68 
69 /* Note :
70  * Decompression functions are provided within "lz4.h" (BSD license)
71  */
72 
73 
79 LZ4LIB_API int LZ4_sizeofStateHC(void);
80 LZ4LIB_API int LZ4_compress_HC_extStateHC(void* state, const char* src, char* dst, int srcSize, int maxDstSize, int compressionLevel);
81 
82 
83 /*-************************************
84  * Streaming Compression
85  * Bufferless synchronous API
86  **************************************/
87  typedef union LZ4_streamHC_u LZ4_streamHC_t; /* incomplete type (defined later) */
88 
95 LZ4LIB_API LZ4_streamHC_t* LZ4_createStreamHC(void);
96 LZ4LIB_API int LZ4_freeStreamHC (LZ4_streamHC_t* streamHCPtr);
97 
98 LZ4LIB_API void LZ4_resetStreamHC (LZ4_streamHC_t* streamHCPtr, int compressionLevel);
99 LZ4LIB_API int LZ4_loadDictHC (LZ4_streamHC_t* streamHCPtr, const char* dictionary, int dictSize);
100 
101 LZ4LIB_API int LZ4_compress_HC_continue (LZ4_streamHC_t* streamHCPtr, const char* src, char* dst, int srcSize, int maxDstSize);
102 
103 LZ4LIB_API int LZ4_saveDictHC (LZ4_streamHC_t* streamHCPtr, char* safeBuffer, int maxDictSize);
104 
105 /*
106  These functions compress data in successive blocks of any size, using previous blocks as dictionary.
107  One key assumption is that previous blocks (up to 64 KB) remain read-accessible while compressing next blocks.
108  There is an exception for ring buffers, which can be smaller than 64 KB.
109  Ring buffers scenario is automatically detected and handled by LZ4_compress_HC_continue().
110 
111  Before starting compression, state must be properly initialized, using LZ4_resetStreamHC().
112  A first "fictional block" can then be designated as initial dictionary, using LZ4_loadDictHC() (Optional).
113 
114  Then, use LZ4_compress_HC_continue() to compress each successive block.
115  Previous memory blocks (including initial dictionary when present) must remain accessible and unmodified during compression.
116  'dst' buffer should be sized to handle worst case scenarios (see LZ4_compressBound()), to ensure operation success.
117  Because in case of failure, the API does not guarantee context recovery, and context will have to be reset.
118  If `dst` buffer budget cannot be >= LZ4_compressBound(), consider using LZ4_compress_HC_continue_destSize() instead.
119 
120  If, for any reason, previous data block can't be preserved unmodified in memory for next compression block,
121  you can save it to a more stable memory space, using LZ4_saveDictHC().
122  Return value of LZ4_saveDictHC() is the size of dictionary effectively saved into 'safeBuffer'.
123 */
124 
125 
126 /*-**************************************************************
127  * PRIVATE DEFINITIONS :
128  * Do not use these definitions.
129  * They are exposed to allow static allocation of `LZ4_streamHC_t`.
130  * Using these definitions makes the code vulnerable to potential API break when upgrading LZ4
131  ****************************************************************/
132 #define LZ4HC_DICTIONARY_LOGSIZE 16
133 #define LZ4HC_MAXD (1<<LZ4HC_DICTIONARY_LOGSIZE)
134 #define LZ4HC_MAXD_MASK (LZ4HC_MAXD - 1)
135 
136 #define LZ4HC_HASH_LOG 15
137 #define LZ4HC_HASHTABLESIZE (1 << LZ4HC_HASH_LOG)
138 #define LZ4HC_HASH_MASK (LZ4HC_HASHTABLESIZE - 1)
139 
140 
141 #if defined(__cplusplus) || (defined (__STDC_VERSION__) && (__STDC_VERSION__ >= 199901L) /* C99 */)
142 #include <stdint.h>
143 
144 typedef struct LZ4HC_CCtx_internal LZ4HC_CCtx_internal;
145 struct LZ4HC_CCtx_internal
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  uint32_t dictLimit; /* below that point, need extDict */
153  uint32_t lowLimit; /* below that point, no more dict */
154  uint32_t nextToUpdate; /* index from which to continue dictionary update */
155  short compressionLevel;
156  short favorDecSpeed;
157  const LZ4HC_CCtx_internal* dictCtx;
158 };
159 
160 #else
161 
162 typedef struct LZ4HC_CCtx_internal LZ4HC_CCtx_internal;
163 struct LZ4HC_CCtx_internal
164 {
165  unsigned int hashTable[LZ4HC_HASHTABLESIZE];
166  unsigned short chainTable[LZ4HC_MAXD];
167  const unsigned char* end; /* next block here to continue on current prefix */
168  const unsigned char* base; /* All index relative to this position */
169  const unsigned char* dictBase; /* alternate base for extDict */
170  unsigned int dictLimit; /* below that point, need extDict */
171  unsigned int lowLimit; /* below that point, no more dict */
172  unsigned int nextToUpdate; /* index from which to continue dictionary update */
173  short compressionLevel;
174  short favorDecSpeed;
175  const LZ4HC_CCtx_internal* dictCtx;
176 };
177 
178 #endif
179 
180 #define LZ4_STREAMHCSIZE (4*LZ4HC_HASHTABLESIZE + 2*LZ4HC_MAXD + 56) /* 262200 */
181 #define LZ4_STREAMHCSIZE_SIZET (LZ4_STREAMHCSIZE / sizeof(size_t))
182 union LZ4_streamHC_u {
183  size_t table[LZ4_STREAMHCSIZE_SIZET];
184  LZ4HC_CCtx_internal internal_donotuse;
185 }; /* previously typedef'd to LZ4_streamHC_t */
186 /*
187  LZ4_streamHC_t :
188  This structure allows static allocation of LZ4 HC streaming state.
189  State must be initialized using LZ4_resetStreamHC() before first use.
190 
191  Static allocation shall only be used in combination with static linking.
192  When invoking LZ4 from a DLL, use create/free functions instead, which are API and ABI stable.
193 */
194 
195 
196 /*-************************************
197 * Deprecated Functions
198 **************************************/
199 /* see lz4.h LZ4_DISABLE_DEPRECATE_WARNINGS to turn off deprecation warnings */
200 
201 /* deprecated compression functions */
202 LZ4_DEPRECATED("use LZ4_compress_HC() instead") LZ4LIB_API int LZ4_compressHC (const char* source, char* dest, int inputSize);
203 LZ4_DEPRECATED("use LZ4_compress_HC() instead") LZ4LIB_API int LZ4_compressHC_limitedOutput (const char* source, char* dest, int inputSize, int maxOutputSize);
204 LZ4_DEPRECATED("use LZ4_compress_HC() instead") LZ4LIB_API int LZ4_compressHC2 (const char* source, char* dest, int inputSize, int compressionLevel);
205 LZ4_DEPRECATED("use LZ4_compress_HC() instead") LZ4LIB_API int LZ4_compressHC2_limitedOutput (const char* source, char* dest, int inputSize, int maxOutputSize, int compressionLevel);
206 LZ4_DEPRECATED("use LZ4_compress_HC_extStateHC() instead") LZ4LIB_API int LZ4_compressHC_withStateHC (void* state, const char* source, char* dest, int inputSize);
207 LZ4_DEPRECATED("use LZ4_compress_HC_extStateHC() instead") LZ4LIB_API int LZ4_compressHC_limitedOutput_withStateHC (void* state, const char* source, char* dest, int inputSize, int maxOutputSize);
208 LZ4_DEPRECATED("use LZ4_compress_HC_extStateHC() instead") LZ4LIB_API int LZ4_compressHC2_withStateHC (void* state, const char* source, char* dest, int inputSize, int compressionLevel);
209 LZ4_DEPRECATED("use LZ4_compress_HC_extStateHC() instead") LZ4LIB_API int LZ4_compressHC2_limitedOutput_withStateHC(void* state, const char* source, char* dest, int inputSize, int maxOutputSize, int compressionLevel);
210 LZ4_DEPRECATED("use LZ4_compress_HC_continue() instead") LZ4LIB_API int LZ4_compressHC_continue (LZ4_streamHC_t* LZ4_streamHCPtr, const char* source, char* dest, int inputSize);
211 LZ4_DEPRECATED("use LZ4_compress_HC_continue() instead") LZ4LIB_API int LZ4_compressHC_limitedOutput_continue (LZ4_streamHC_t* LZ4_streamHCPtr, const char* source, char* dest, int inputSize, int maxOutputSize);
212 
213 /* Obsolete streaming functions; degraded functionality; do not use!
214  *
215  * In order to perform streaming compression, these functions depended on data
216  * that is no longer tracked in the state. They have been preserved as well as
217  * possible: using them will still produce a correct output. However, use of
218  * LZ4_slideInputBufferHC() will truncate the history of the stream, rather
219  * than preserve a window-sized chunk of history.
220  */
221 LZ4_DEPRECATED("use LZ4_createStreamHC() instead") LZ4LIB_API void* LZ4_createHC (const char* inputBuffer);
222 LZ4_DEPRECATED("use LZ4_saveDictHC() instead") LZ4LIB_API char* LZ4_slideInputBufferHC (void* LZ4HC_Data);
223 LZ4_DEPRECATED("use LZ4_freeStreamHC() instead") LZ4LIB_API int LZ4_freeHC (void* LZ4HC_Data);
224 LZ4_DEPRECATED("use LZ4_compress_HC_continue() instead") LZ4LIB_API int LZ4_compressHC2_continue (void* LZ4HC_Data, const char* source, char* dest, int inputSize, int compressionLevel);
225 LZ4_DEPRECATED("use LZ4_compress_HC_continue() instead") LZ4LIB_API int LZ4_compressHC2_limitedOutput_continue (void* LZ4HC_Data, const char* source, char* dest, int inputSize, int maxOutputSize, int compressionLevel);
226 LZ4_DEPRECATED("use LZ4_createStreamHC() instead") LZ4LIB_API int LZ4_sizeofStreamStateHC(void);
227 LZ4_DEPRECATED("use LZ4_resetStreamHC() instead") LZ4LIB_API int LZ4_resetStreamStateHC(void* state, char* inputBuffer);
228 
229 
230 #if defined (__cplusplus)
231 }
232 #endif
233 
234 #endif /* LZ4_HC_H_19834876238432 */
235 
236 
237 /*-**************************************************
238  * !!!!! STATIC LINKING ONLY !!!!!
239  * Following definitions are considered experimental.
240  * They should not be linked from DLL,
241  * as there is no guarantee of API stability yet.
242  * Prototypes will be promoted to "stable" status
243  * after successfull usage in real-life scenarios.
244  ***************************************************/
245 #ifdef LZ4_HC_STATIC_LINKING_ONLY /* protection macro */
246 #ifndef LZ4_HC_SLO_098092834
247 #define LZ4_HC_SLO_098092834
248 
257 int LZ4_compress_HC_destSize(void* LZ4HC_Data,
258  const char* src, char* dst,
259  int* srcSizePtr, int targetDstSize,
260  int compressionLevel);
261 
271 int LZ4_compress_HC_continue_destSize(LZ4_streamHC_t* LZ4_streamHCPtr,
272  const char* src, char* dst,
273  int* srcSizePtr, int targetDstSize);
274 
278 void LZ4_setCompressionLevel(LZ4_streamHC_t* LZ4_streamHCPtr, int compressionLevel);
279 
284 void LZ4_favorDecompressionSpeed(LZ4_streamHC_t* LZ4_streamHCPtr, int favor);
285 
304 void LZ4_resetStreamHC_fast(LZ4_streamHC_t* LZ4_streamHCPtr, int compressionLevel);
305 
317 int LZ4_compress_HC_extStateHC_fastReset (void* state, const char* src, char* dst, int srcSize, int dstCapacity, int compressionLevel);
318 
344 LZ4LIB_API void LZ4_attach_HC_dictionary(LZ4_streamHC_t *working_stream, const LZ4_streamHC_t *dictionary_stream);
345 
346 #endif /* LZ4_HC_SLO_098092834 */
347 #endif /* LZ4_HC_STATIC_LINKING_ONLY */