| 1 |
/* |
| 2 |
LZ4 - Fast LZ compression algorithm |
| 3 |
Header File |
| 4 |
Copyright (C) 2011-2014, 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 : http://code.google.com/p/lz4/ |
| 32 |
- LZ4 public forum : https://groups.google.com/forum/#!forum/lz4c |
| 33 |
*/ |
| 34 |
#pragma once |
| 35 |
|
| 36 |
#if defined (__cplusplus) |
| 37 |
extern "C" { |
| 38 |
#endif |
| 39 |
|
| 40 |
|
| 41 |
/************************************** |
| 42 |
Version |
| 43 |
**************************************/ |
| 44 |
#define LZ4_VERSION_MAJOR 1 /* for major interface/format changes */ |
| 45 |
#define LZ4_VERSION_MINOR 2 /* for minor interface/format changes */ |
| 46 |
#define LZ4_VERSION_RELEASE 0 /* for tweaks, bug-fixes, or development */ |
| 47 |
|
| 48 |
|
| 49 |
/************************************** |
| 50 |
Tuning parameter |
| 51 |
**************************************/ |
| 52 |
/* |
| 53 |
* LZ4_MEMORY_USAGE : |
| 54 |
* Memory usage formula : N->2^N Bytes (examples : 10 -> 1KB; 12 -> 4KB ; 16 -> 64KB; 20 -> 1MB; etc.) |
| 55 |
* Increasing memory usage improves compression ratio |
| 56 |
* Reduced memory usage can improve speed, due to cache effect |
| 57 |
* Default value is 14, for 16KB, which nicely fits into Intel x86 L1 cache |
| 58 |
*/ |
| 59 |
#define LZ4_MEMORY_USAGE 14 |
| 60 |
|
| 61 |
|
| 62 |
/************************************** |
| 63 |
Simple Functions |
| 64 |
**************************************/ |
| 65 |
|
| 66 |
int LZ4_compress (const char* source, char* dest, int inputSize); |
| 67 |
int LZ4_decompress_safe (const char* source, char* dest, int compressedSize, int maxOutputSize); |
| 68 |
|
| 69 |
/* |
| 70 |
LZ4_compress() : |
| 71 |
Compresses 'inputSize' bytes from 'source' into 'dest'. |
| 72 |
Destination buffer must be already allocated, |
| 73 |
and must be sized to handle worst cases situations (input data not compressible) |
| 74 |
Worst case size evaluation is provided by function LZ4_compressBound() |
| 75 |
inputSize : Max supported value is LZ4_MAX_INPUT_VALUE |
| 76 |
return : the number of bytes written in buffer dest |
| 77 |
or 0 if the compression fails |
| 78 |
|
| 79 |
LZ4_decompress_safe() : |
| 80 |
compressedSize : is obviously the source size |
| 81 |
maxOutputSize : is the size of the destination buffer, which must be already allocated. |
| 82 |
return : the number of bytes decoded in the destination buffer (necessarily <= maxOutputSize) |
| 83 |
If the destination buffer is not large enough, decoding will stop and output an error code (<0). |
| 84 |
If the source stream is detected malformed, the function will stop decoding and return a negative result. |
| 85 |
This function is protected against buffer overflow exploits : |
| 86 |
it never writes outside of output buffer, and never reads outside of input buffer. |
| 87 |
Therefore, it is protected against malicious data packets. |
| 88 |
*/ |
| 89 |
|
| 90 |
|
| 91 |
/* |
| 92 |
Note : |
| 93 |
Should you prefer to explicitly allocate compression-table memory using your own allocation method, |
| 94 |
use the streaming functions provided below, simply reset the memory area between each call to LZ4_compress_continue() |
| 95 |
*/ |
| 96 |
|
| 97 |
|
| 98 |
/************************************** |
| 99 |
Advanced Functions |
| 100 |
**************************************/ |
| 101 |
#define LZ4_MAX_INPUT_SIZE 0x7E000000 /* 2 113 929 216 bytes */ |
| 102 |
#define LZ4_COMPRESSBOUND(isize) ((unsigned int)(isize) > (unsigned int)LZ4_MAX_INPUT_SIZE ? 0 : (isize) + ((isize)/255) + 16) |
| 103 |
|
| 104 |
/* |
| 105 |
LZ4_compressBound() : |
| 106 |
Provides the maximum size that LZ4 may output in a "worst case" scenario (input data not compressible) |
| 107 |
primarily useful for memory allocation of output buffer. |
| 108 |
macro is also provided when result needs to be evaluated at compilation (such as stack memory allocation). |
| 109 |
|
| 110 |
isize : is the input size. Max supported value is LZ4_MAX_INPUT_SIZE |
| 111 |
return : maximum output size in a "worst case" scenario |
| 112 |
or 0, if input size is too large ( > LZ4_MAX_INPUT_SIZE) |
| 113 |
*/ |
| 114 |
int LZ4_compressBound(int isize); |
| 115 |
|
| 116 |
|
| 117 |
/* |
| 118 |
LZ4_compress_limitedOutput() : |
| 119 |
Compress 'inputSize' bytes from 'source' into an output buffer 'dest' of maximum size 'maxOutputSize'. |
| 120 |
If it cannot achieve it, compression will stop, and result of the function will be zero. |
| 121 |
This function never writes outside of provided output buffer. |
| 122 |
|
| 123 |
inputSize : Max supported value is LZ4_MAX_INPUT_VALUE |
| 124 |
maxOutputSize : is the size of the destination buffer (which must be already allocated) |
| 125 |
return : the number of bytes written in buffer 'dest' |
| 126 |
or 0 if the compression fails |
| 127 |
*/ |
| 128 |
int LZ4_compress_limitedOutput (const char* source, char* dest, int inputSize, int maxOutputSize); |
| 129 |
|
| 130 |
|
| 131 |
/* |
| 132 |
LZ4_decompress_fast() : |
| 133 |
originalSize : is the original and therefore uncompressed size |
| 134 |
return : the number of bytes read from the source buffer (in other words, the compressed size) |
| 135 |
If the source stream is malformed, the function will stop decoding and return a negative result. |
| 136 |
Destination buffer must be already allocated. Its size must be a minimum of 'originalSize' bytes. |
| 137 |
note : This function is a bit faster than LZ4_decompress_safe() |
| 138 |
It provides fast decompression and fully respect memory boundaries for properly formed compressed data. |
| 139 |
It does not provide full protection against intentionnally modified data stream. |
| 140 |
Use this function in a trusted environment (data to decode comes from a trusted source). |
| 141 |
*/ |
| 142 |
int LZ4_decompress_fast (const char* source, char* dest, int originalSize); |
| 143 |
|
| 144 |
|
| 145 |
/* |
| 146 |
LZ4_decompress_safe_partial() : |
| 147 |
This function decompress a compressed block of size 'compressedSize' at position 'source' |
| 148 |
into output buffer 'dest' of size 'maxOutputSize'. |
| 149 |
The function tries to stop decompressing operation as soon as 'targetOutputSize' has been reached, |
| 150 |
reducing decompression time. |
| 151 |
return : the number of bytes decoded in the destination buffer (necessarily <= maxOutputSize) |
| 152 |
Note : this number can be < 'targetOutputSize' should the compressed block to decode be smaller. |
| 153 |
Always control how many bytes were decoded. |
| 154 |
If the source stream is detected malformed, the function will stop decoding and return a negative result. |
| 155 |
This function never writes outside of output buffer, and never reads outside of input buffer. It is therefore protected against malicious data packets |
| 156 |
*/ |
| 157 |
int LZ4_decompress_safe_partial (const char* source, char* dest, int compressedSize, int targetOutputSize, int maxOutputSize); |
| 158 |
|
| 159 |
|
| 160 |
/*********************************************** |
| 161 |
Experimental Streaming Compression Functions |
| 162 |
***********************************************/ |
| 163 |
|
| 164 |
#define LZ4_STREAMSIZE_U32 ((1 << (LZ4_MEMORY_USAGE-2)) + 8) |
| 165 |
#define LZ4_STREAMSIZE (LZ4_STREAMSIZE_U32 * sizeof(unsigned int)) |
| 166 |
/* |
| 167 |
* LZ4_stream_t |
| 168 |
* information structure to track an LZ4 stream. |
| 169 |
* important : set this structure content to zero before first use ! |
| 170 |
*/ |
| 171 |
typedef struct { unsigned int table[LZ4_STREAMSIZE_U32]; } LZ4_stream_t; |
| 172 |
|
| 173 |
/* |
| 174 |
* If you prefer dynamic allocation methods, |
| 175 |
* LZ4_createStream |
| 176 |
* provides a pointer (void*) towards an initialized LZ4_stream_t structure. |
| 177 |
* LZ4_free just frees it. |
| 178 |
*/ |
| 179 |
void* LZ4_createStream(); |
| 180 |
int LZ4_free (void* LZ4_stream); |
| 181 |
|
| 182 |
|
| 183 |
/* |
| 184 |
* LZ4_loadDict |
| 185 |
* Use this function to load a static dictionary into LZ4_stream. |
| 186 |
* Any previous data will be forgotten, only 'dictionary' will remain in memory. |
| 187 |
* Loading a size of 0 is allowed (same effect as init). |
| 188 |
* Return : 1 if OK, 0 if error |
| 189 |
*/ |
| 190 |
int LZ4_loadDict (void* LZ4_stream, const char* dictionary, int dictSize); |
| 191 |
|
| 192 |
/* |
| 193 |
* LZ4_compress_continue |
| 194 |
* Compress data block 'source', using blocks compressed before as dictionary to improve compression ratio |
| 195 |
* Previous data blocks are assumed to still be present at their previous location. |
| 196 |
*/ |
| 197 |
int LZ4_compress_continue (void* LZ4_stream, const char* source, char* dest, int inputSize); |
| 198 |
|
| 199 |
/* |
| 200 |
* LZ4_compress_limitedOutput_continue |
| 201 |
* Same as before, but also specify a maximum target compressed size (maxOutputSize) |
| 202 |
* If objective cannot be met, compression exits, and returns a zero. |
| 203 |
*/ |
| 204 |
int LZ4_compress_limitedOutput_continue (void* LZ4_stream, const char* source, char* dest, int inputSize, int maxOutputSize); |
| 205 |
|
| 206 |
/* |
| 207 |
* LZ4_saveDict |
| 208 |
* If previously compressed data block is not guaranteed to remain at its previous memory location |
| 209 |
* save it into a safe place (char* safeBuffer) |
| 210 |
* Note : you don't need to call LZ4_loadDict() afterwards, |
| 211 |
* dictionary is immediately usable, you can therefore call again LZ4_compress_continue() |
| 212 |
* Return : 1 if OK, 0 if error |
| 213 |
* Note : any dictSize > 64 KB will be interpreted as 64KB. |
| 214 |
*/ |
| 215 |
int LZ4_saveDict (void* LZ4_stream, char* safeBuffer, int dictSize); |
| 216 |
|
| 217 |
|
| 218 |
/************************************************ |
| 219 |
Experimental Streaming Decompression Functions |
| 220 |
************************************************/ |
| 221 |
|
| 222 |
#define LZ4_STREAMDECODESIZE_U32 4 |
| 223 |
#define LZ4_STREAMDECODESIZE (LZ4_STREAMDECODESIZE_U32 * sizeof(unsigned int)) |
| 224 |
/* |
| 225 |
* LZ4_streamDecode_t |
| 226 |
* information structure to track an LZ4 stream. |
| 227 |
* important : set this structure content to zero before first use ! |
| 228 |
*/ |
| 229 |
typedef struct { unsigned int table[LZ4_STREAMDECODESIZE_U32]; } LZ4_streamDecode_t; |
| 230 |
|
| 231 |
/* |
| 232 |
* If you prefer dynamic allocation methods, |
| 233 |
* LZ4_createStreamDecode() |
| 234 |
* provides a pointer (void*) towards an initialized LZ4_streamDecode_t structure. |
| 235 |
* LZ4_free just frees it. |
| 236 |
*/ |
| 237 |
void* LZ4_createStreamDecode(); |
| 238 |
int LZ4_free (void* LZ4_stream); /* yes, it's the same one as for compression */ |
| 239 |
|
| 240 |
/* |
| 241 |
*_continue() : |
| 242 |
These decoding functions allow decompression of multiple blocks in "streaming" mode. |
| 243 |
Previously decoded blocks must still be available at the memory position where they were decoded. |
| 244 |
If it's not possible, save the relevant part of decoded data into a safe buffer, |
| 245 |
and indicate where it stands using LZ4_setDictDecode() |
| 246 |
*/ |
| 247 |
int LZ4_decompress_safe_continue (void* LZ4_streamDecode, const char* source, char* dest, int compressedSize, int maxOutputSize); |
| 248 |
int LZ4_decompress_fast_continue (void* LZ4_streamDecode, const char* source, char* dest, int originalSize); |
| 249 |
|
| 250 |
/* |
| 251 |
* LZ4_setDictDecode |
| 252 |
* Use this function to instruct where to find the dictionary. |
| 253 |
* This function can be used to specify a static dictionary, |
| 254 |
* or to instruct where to find some previously decoded data saved into a different memory space. |
| 255 |
* Setting a size of 0 is allowed (same effect as no dictionary). |
| 256 |
* Return : 1 if OK, 0 if error |
| 257 |
*/ |
| 258 |
int LZ4_setDictDecode (void* LZ4_streamDecode, const char* dictionary, int dictSize); |
| 259 |
|
| 260 |
|
| 261 |
/* |
| 262 |
Advanced decoding functions : |
| 263 |
*_usingDict() : |
| 264 |
These decoding functions work the same as |
| 265 |
a combination of LZ4_setDictDecode() followed by LZ4_decompress_x_continue() |
| 266 |
all together into a single function call. |
| 267 |
It doesn't use nor update an LZ4_streamDecode_t structure. |
| 268 |
*/ |
| 269 |
int LZ4_decompress_safe_usingDict (const char* source, char* dest, int compressedSize, int maxOutputSize, const char* dictStart, int dictSize); |
| 270 |
int LZ4_decompress_fast_usingDict (const char* source, char* dest, int originalSize, const char* dictStart, int dictSize); |
| 271 |
|
| 272 |
|
| 273 |
|
| 274 |
|
| 275 |
/************************************** |
| 276 |
Obsolete Functions |
| 277 |
**************************************/ |
| 278 |
/* |
| 279 |
Obsolete decompression functions |
| 280 |
These function names are deprecated and should no longer be used. |
| 281 |
They are only provided here for compatibility with older user programs. |
| 282 |
- LZ4_uncompress is the same as LZ4_decompress_fast |
| 283 |
- LZ4_uncompress_unknownOutputSize is the same as LZ4_decompress_safe |
| 284 |
*/ |
| 285 |
int LZ4_uncompress (const char* source, char* dest, int outputSize); |
| 286 |
int LZ4_uncompress_unknownOutputSize (const char* source, char* dest, int isize, int maxOutputSize); |
| 287 |
|
| 288 |
/* Obsolete functions for externally allocated state; use streaming interface instead */ |
| 289 |
int LZ4_sizeofState(void); |
| 290 |
int LZ4_compress_withState (void* state, const char* source, char* dest, int inputSize); |
| 291 |
int LZ4_compress_limitedOutput_withState (void* state, const char* source, char* dest, int inputSize, int maxOutputSize); |
| 292 |
|
| 293 |
/* Obsolete streaming functions; use new streaming interface whenever possible */ |
| 294 |
void* LZ4_create (const char* inputBuffer); |
| 295 |
int LZ4_sizeofStreamState(void); |
| 296 |
int LZ4_resetStreamState(void* state, const char* inputBuffer); |
| 297 |
char* LZ4_slideInputBuffer (void* state); |
| 298 |
|
| 299 |
/* Obsolete streaming decoding functions */ |
| 300 |
int LZ4_decompress_safe_withPrefix64k (const char* source, char* dest, int compressedSize, int maxOutputSize); |
| 301 |
int LZ4_decompress_fast_withPrefix64k (const char* source, char* dest, int originalSize); |
| 302 |
|
| 303 |
|
| 304 |
#if defined (__cplusplus) |
| 305 |
} |
| 306 |
#endif |