1 /* Copyright 2013 Google Inc. All Rights Reserved. 2 3 Distributed under MIT license. 4 See file LICENSE for detail or copy at https://opensource.org/licenses/MIT 5 */ 6 7 /** 8 * @file 9 * API for Brotli decompression. 10 */ 11 12 #ifndef BROTLI_DEC_DECODE_H_ 13 #define BROTLI_DEC_DECODE_H_ 14 15 #include <brotli/port.h> 16 #include <brotli/shared_dictionary.h> 17 #include <brotli/types.h> 18 19 #if defined(__cplusplus) || defined(c_plusplus) 20 extern "C" { 21 #endif 22 23 /** 24 * Opaque structure that holds decoder state. 25 * 26 * Allocated and initialized with ::BrotliDecoderCreateInstance. 27 * Cleaned up and deallocated with ::BrotliDecoderDestroyInstance. 28 */ 29 typedef struct BrotliDecoderStateStruct BrotliDecoderState; 30 31 /** 32 * Result type for ::BrotliDecoderDecompress and 33 * ::BrotliDecoderDecompressStream functions. 34 */ 35 typedef enum { 36 /** Decoding error, e.g. corrupted input or memory allocation problem. */ 37 BROTLI_DECODER_RESULT_ERROR = 0, 38 /** Decoding successfully completed. */ 39 BROTLI_DECODER_RESULT_SUCCESS = 1, 40 /** Partially done; should be called again with more input. */ 41 BROTLI_DECODER_RESULT_NEEDS_MORE_INPUT = 2, 42 /** Partially done; should be called again with more output. */ 43 BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT = 3 44 } BrotliDecoderResult; 45 46 /** 47 * Template that evaluates items of ::BrotliDecoderErrorCode. 48 * 49 * Example: @code {.cpp} 50 * // Log Brotli error code. 51 * switch (brotliDecoderErrorCode) { 52 * #define CASE_(PREFIX, NAME, CODE) \ 53 * case BROTLI_DECODER ## PREFIX ## NAME: \ 54 * LOG(INFO) << "error code:" << #NAME; \ 55 * break; 56 * #define NEWLINE_ 57 * BROTLI_DECODER_ERROR_CODES_LIST(CASE_, NEWLINE_) 58 * #undef CASE_ 59 * #undef NEWLINE_ 60 * default: LOG(FATAL) << "unknown brotli error code"; 61 * } 62 * @endcode 63 */ 64 #define BROTLI_DECODER_ERROR_CODES_LIST(BROTLI_ERROR_CODE, SEPARATOR) \ 65 BROTLI_ERROR_CODE(_, NO_ERROR, 0) SEPARATOR \ 66 /* Same as BrotliDecoderResult values */ \ 67 BROTLI_ERROR_CODE(_, SUCCESS, 1) SEPARATOR \ 68 BROTLI_ERROR_CODE(_, NEEDS_MORE_INPUT, 2) SEPARATOR \ 69 BROTLI_ERROR_CODE(_, NEEDS_MORE_OUTPUT, 3) SEPARATOR \ 70 \ 71 /* Errors caused by invalid input */ \ 72 BROTLI_ERROR_CODE(_ERROR_FORMAT_, EXUBERANT_NIBBLE, -1) SEPARATOR \ 73 BROTLI_ERROR_CODE(_ERROR_FORMAT_, RESERVED, -2) SEPARATOR \ 74 BROTLI_ERROR_CODE(_ERROR_FORMAT_, EXUBERANT_META_NIBBLE, -3) SEPARATOR \ 75 BROTLI_ERROR_CODE(_ERROR_FORMAT_, SIMPLE_HUFFMAN_ALPHABET, -4) SEPARATOR \ 76 BROTLI_ERROR_CODE(_ERROR_FORMAT_, SIMPLE_HUFFMAN_SAME, -5) SEPARATOR \ 77 BROTLI_ERROR_CODE(_ERROR_FORMAT_, CL_SPACE, -6) SEPARATOR \ 78 BROTLI_ERROR_CODE(_ERROR_FORMAT_, HUFFMAN_SPACE, -7) SEPARATOR \ 79 BROTLI_ERROR_CODE(_ERROR_FORMAT_, CONTEXT_MAP_REPEAT, -8) SEPARATOR \ 80 BROTLI_ERROR_CODE(_ERROR_FORMAT_, BLOCK_LENGTH_1, -9) SEPARATOR \ 81 BROTLI_ERROR_CODE(_ERROR_FORMAT_, BLOCK_LENGTH_2, -10) SEPARATOR \ 82 BROTLI_ERROR_CODE(_ERROR_FORMAT_, TRANSFORM, -11) SEPARATOR \ 83 BROTLI_ERROR_CODE(_ERROR_FORMAT_, DICTIONARY, -12) SEPARATOR \ 84 BROTLI_ERROR_CODE(_ERROR_FORMAT_, WINDOW_BITS, -13) SEPARATOR \ 85 BROTLI_ERROR_CODE(_ERROR_FORMAT_, PADDING_1, -14) SEPARATOR \ 86 BROTLI_ERROR_CODE(_ERROR_FORMAT_, PADDING_2, -15) SEPARATOR \ 87 BROTLI_ERROR_CODE(_ERROR_FORMAT_, DISTANCE, -16) SEPARATOR \ 88 \ 89 /* -17 code is reserved */ \ 90 \ 91 BROTLI_ERROR_CODE(_ERROR_, COMPOUND_DICTIONARY, -18) SEPARATOR \ 92 BROTLI_ERROR_CODE(_ERROR_, DICTIONARY_NOT_SET, -19) SEPARATOR \ 93 BROTLI_ERROR_CODE(_ERROR_, INVALID_ARGUMENTS, -20) SEPARATOR \ 94 \ 95 /* Memory allocation problems */ \ 96 BROTLI_ERROR_CODE(_ERROR_ALLOC_, CONTEXT_MODES, -21) SEPARATOR \ 97 /* Literal, insert and distance trees together */ \ 98 BROTLI_ERROR_CODE(_ERROR_ALLOC_, TREE_GROUPS, -22) SEPARATOR \ 99 /* -23..-24 codes are reserved for distinct tree groups */ \ 100 BROTLI_ERROR_CODE(_ERROR_ALLOC_, CONTEXT_MAP, -25) SEPARATOR \ 101 BROTLI_ERROR_CODE(_ERROR_ALLOC_, RING_BUFFER_1, -26) SEPARATOR \ 102 BROTLI_ERROR_CODE(_ERROR_ALLOC_, RING_BUFFER_2, -27) SEPARATOR \ 103 /* -28..-29 codes are reserved for dynamic ring-buffer allocation */ \ 104 BROTLI_ERROR_CODE(_ERROR_ALLOC_, BLOCK_TYPE_TREES, -30) SEPARATOR \ 105 \ 106 /* "Impossible" states */ \ 107 BROTLI_ERROR_CODE(_ERROR_, UNREACHABLE, -31) 108 109 /** 110 * Error code for detailed logging / production debugging. 111 * 112 * See ::BrotliDecoderGetErrorCode and ::BROTLI_LAST_ERROR_CODE. 113 */ 114 typedef enum { 115 #define BROTLI_COMMA_ , 116 #define BROTLI_ERROR_CODE_ENUM_ITEM_(PREFIX, NAME, CODE) \ 117 BROTLI_DECODER ## PREFIX ## NAME = CODE 118 BROTLI_DECODER_ERROR_CODES_LIST(BROTLI_ERROR_CODE_ENUM_ITEM_, BROTLI_COMMA_) 119 } BrotliDecoderErrorCode; 120 #undef BROTLI_ERROR_CODE_ENUM_ITEM_ 121 #undef BROTLI_COMMA_ 122 123 /** 124 * The value of the last error code, negative integer. 125 * 126 * All other error code values are in the range from ::BROTLI_LAST_ERROR_CODE 127 * to @c -1. There are also 4 other possible non-error codes @c 0 .. @c 3 in 128 * ::BrotliDecoderErrorCode enumeration. 129 */ 130 #define BROTLI_LAST_ERROR_CODE BROTLI_DECODER_ERROR_UNREACHABLE 131 132 /** Options to be used with ::BrotliDecoderSetParameter. */ 133 typedef enum BrotliDecoderParameter { 134 /** 135 * Disable "canny" ring buffer allocation strategy. 136 * 137 * Ring buffer is allocated according to window size, despite the real size of 138 * the content. 139 */ 140 BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION = 0, 141 /** 142 * Flag that determines if "Large Window Brotli" is used. 143 */ 144 BROTLI_DECODER_PARAM_LARGE_WINDOW = 1 145 } BrotliDecoderParameter; 146 147 /** 148 * Sets the specified parameter to the given decoder instance. 149 * 150 * @param state decoder instance 151 * @param param parameter to set 152 * @param value new parameter value 153 * @returns ::BROTLI_FALSE if parameter is unrecognized, or value is invalid 154 * @returns ::BROTLI_TRUE if value is accepted 155 */ 156 BROTLI_DEC_API BROTLI_BOOL BrotliDecoderSetParameter( 157 BrotliDecoderState* state, BrotliDecoderParameter param, uint32_t value); 158 159 /** 160 * Adds LZ77 prefix dictionary, adds or replaces built-in static dictionary and 161 * transforms. 162 * 163 * Attached dictionary ownership is not transferred. 164 * Data provided to this method should be kept accessible until 165 * decoding is finished and decoder instance is destroyed. 166 * 167 * @note Dictionaries can NOT be attached after actual decoding is started. 168 * 169 * @param state decoder instance 170 * @param type dictionary data format 171 * @param data_size length of memory region pointed by @p data 172 * @param data dictionary data in format corresponding to @p type 173 * @returns ::BROTLI_FALSE if dictionary is corrupted, 174 * or dictionary count limit is reached 175 * @returns ::BROTLI_TRUE if dictionary is accepted / attached 176 */ 177 BROTLI_DEC_API BROTLI_BOOL BrotliDecoderAttachDictionary( 178 BrotliDecoderState* state, BrotliSharedDictionaryType type, 179 size_t data_size, const uint8_t data[BROTLI_ARRAY_PARAM(data_size)]); 180 181 /** 182 * Creates an instance of ::BrotliDecoderState and initializes it. 183 * 184 * The instance can be used once for decoding and should then be destroyed with 185 * ::BrotliDecoderDestroyInstance, it cannot be reused for a new decoding 186 * session. 187 * 188 * @p alloc_func and @p free_func @b MUST be both zero or both non-zero. In the 189 * case they are both zero, default memory allocators are used. @p opaque is 190 * passed to @p alloc_func and @p free_func when they are called. @p free_func 191 * has to return without doing anything when asked to free a NULL pointer. 192 * 193 * @param alloc_func custom memory allocation function 194 * @param free_func custom memory free function 195 * @param opaque custom memory manager handle 196 * @returns @c 0 if instance can not be allocated or initialized 197 * @returns pointer to initialized ::BrotliDecoderState otherwise 198 */ 199 BROTLI_DEC_API BrotliDecoderState* BrotliDecoderCreateInstance( 200 brotli_alloc_func alloc_func, brotli_free_func free_func, void* opaque); 201 202 /** 203 * Deinitializes and frees ::BrotliDecoderState instance. 204 * 205 * @param state decoder instance to be cleaned up and deallocated 206 */ 207 BROTLI_DEC_API void BrotliDecoderDestroyInstance(BrotliDecoderState* state); 208 209 /** 210 * Performs one-shot memory-to-memory decompression. 211 * 212 * Decompresses the data in @p encoded_buffer into @p decoded_buffer, and sets 213 * @p *decoded_size to the decompressed length. 214 * 215 * @param encoded_size size of @p encoded_buffer 216 * @param encoded_buffer compressed data buffer with at least @p encoded_size 217 * addressable bytes 218 * @param[in, out] decoded_size @b in: size of @p decoded_buffer; \n 219 * @b out: length of decompressed data written to 220 * @p decoded_buffer 221 * @param decoded_buffer decompressed data destination buffer 222 * @returns ::BROTLI_DECODER_RESULT_ERROR if input is corrupted, memory 223 * allocation failed, or @p decoded_buffer is not large enough; 224 * @returns ::BROTLI_DECODER_RESULT_SUCCESS otherwise 225 */ 226 BROTLI_DEC_API BrotliDecoderResult BrotliDecoderDecompress( 227 size_t encoded_size, 228 const uint8_t encoded_buffer[BROTLI_ARRAY_PARAM(encoded_size)], 229 size_t* decoded_size, 230 uint8_t decoded_buffer[BROTLI_ARRAY_PARAM(*decoded_size)]); 231 232 /** 233 * Decompresses the input stream to the output stream. 234 * 235 * The values @p *available_in and @p *available_out must specify the number of 236 * bytes addressable at @p *next_in and @p *next_out respectively. 237 * When @p *available_out is @c 0, @p next_out is allowed to be @c NULL. 238 * 239 * After each call, @p *available_in will be decremented by the amount of input 240 * bytes consumed, and the @p *next_in pointer will be incremented by that 241 * amount. Similarly, @p *available_out will be decremented by the amount of 242 * output bytes written, and the @p *next_out pointer will be incremented by 243 * that amount. 244 * 245 * @p total_out, if it is not a null-pointer, will be set to the number 246 * of bytes decompressed since the last @p state initialization. 247 * 248 * @note Input is never overconsumed, so @p next_in and @p available_in could be 249 * passed to the next consumer after decoding is complete. 250 * 251 * @param state decoder instance 252 * @param[in, out] available_in @b in: amount of available input; \n 253 * @b out: amount of unused input 254 * @param[in, out] next_in pointer to the next compressed byte 255 * @param[in, out] available_out @b in: length of output buffer; \n 256 * @b out: remaining size of output buffer 257 * @param[in, out] next_out output buffer cursor; 258 * can be @c NULL if @p available_out is @c 0 259 * @param[out] total_out number of bytes decompressed so far; can be @c NULL 260 * @returns ::BROTLI_DECODER_RESULT_ERROR if input is corrupted, memory 261 * allocation failed, arguments were invalid, etc.; 262 * use ::BrotliDecoderGetErrorCode to get detailed error code 263 * @returns ::BROTLI_DECODER_RESULT_NEEDS_MORE_INPUT decoding is blocked until 264 * more input data is provided 265 * @returns ::BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT decoding is blocked until 266 * more output space is provided 267 * @returns ::BROTLI_DECODER_RESULT_SUCCESS decoding is finished, no more 268 * input might be consumed and no more output will be produced 269 */ 270 BROTLI_DEC_API BrotliDecoderResult BrotliDecoderDecompressStream( 271 BrotliDecoderState* state, size_t* available_in, const uint8_t** next_in, 272 size_t* available_out, uint8_t** next_out, size_t* total_out); 273 274 /** 275 * Checks if decoder has more output. 276 * 277 * @param state decoder instance 278 * @returns ::BROTLI_TRUE, if decoder has some unconsumed output 279 * @returns ::BROTLI_FALSE otherwise 280 */ 281 BROTLI_DEC_API BROTLI_BOOL BrotliDecoderHasMoreOutput( 282 const BrotliDecoderState* state); 283 284 /** 285 * Acquires pointer to internal output buffer. 286 * 287 * This method is used to make language bindings easier and more efficient: 288 * -# push data to ::BrotliDecoderDecompressStream, 289 * until ::BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT is reported 290 * -# use ::BrotliDecoderTakeOutput to peek bytes and copy to language-specific 291 * entity 292 * 293 * Also this could be useful if there is an output stream that is able to 294 * consume all the provided data (e.g. when data is saved to file system). 295 * 296 * @attention After every call to ::BrotliDecoderTakeOutput @p *size bytes of 297 * output are considered consumed for all consecutive calls to the 298 * instance methods; returned pointer becomes invalidated as well. 299 * 300 * @note Decoder output is not guaranteed to be contiguous. This means that 301 * after the size-unrestricted call to ::BrotliDecoderTakeOutput, 302 * immediate next call to ::BrotliDecoderTakeOutput may return more data. 303 * 304 * @param state decoder instance 305 * @param[in, out] size @b in: number of bytes caller is ready to take, @c 0 if 306 * any amount could be handled; \n 307 * @b out: amount of data pointed by returned pointer and 308 * considered consumed; \n 309 * out value is never greater than in value, unless it is @c 0 310 * @returns pointer to output data 311 */ 312 BROTLI_DEC_API const uint8_t* BrotliDecoderTakeOutput( 313 BrotliDecoderState* state, size_t* size); 314 315 /** 316 * Checks if instance has already consumed input. 317 * 318 * Instance that returns ::BROTLI_FALSE is considered "fresh" and could be 319 * reused. 320 * 321 * @param state decoder instance 322 * @returns ::BROTLI_TRUE if decoder has already used some input bytes 323 * @returns ::BROTLI_FALSE otherwise 324 */ 325 BROTLI_DEC_API BROTLI_BOOL BrotliDecoderIsUsed(const BrotliDecoderState* state); 326 327 /** 328 * Checks if decoder instance reached the final state. 329 * 330 * @param state decoder instance 331 * @returns ::BROTLI_TRUE if decoder is in a state where it reached the end of 332 * the input and produced all of the output 333 * @returns ::BROTLI_FALSE otherwise 334 */ 335 BROTLI_DEC_API BROTLI_BOOL BrotliDecoderIsFinished( 336 const BrotliDecoderState* state); 337 338 /** 339 * Acquires a detailed error code. 340 * 341 * Should be used only after ::BrotliDecoderDecompressStream returns 342 * ::BROTLI_DECODER_RESULT_ERROR. 343 * 344 * See also ::BrotliDecoderErrorString 345 * 346 * @param state decoder instance 347 * @returns last saved error code 348 */ 349 BROTLI_DEC_API BrotliDecoderErrorCode BrotliDecoderGetErrorCode( 350 const BrotliDecoderState* state); 351 352 /** 353 * Converts error code to a c-string. 354 */ 355 BROTLI_DEC_API const char* BrotliDecoderErrorString(BrotliDecoderErrorCode c); 356 357 /** 358 * Gets a decoder library version. 359 * 360 * Look at BROTLI_VERSION for more information. 361 */ 362 BROTLI_DEC_API uint32_t BrotliDecoderVersion(void); 363 364 #if defined(__cplusplus) || defined(c_plusplus) 365 } /* extern "C" */ 366 #endif 367 368 #endif /* BROTLI_DEC_DECODE_H_ */ 369