include/brotli/decode.h

0001 /* Copyright 2013 Google Inc. All Rights Reserved.
0002
0003    Distributed under MIT license.
0004    See file LICENSE for detail or copy at https://opensource.org/licenses/MIT
0005 */
0006
0007 /**
0008  * @file
0009  * API for Brotli decompression.
0010  */
0011
0012 #ifndef BROTLI_DEC_DECODE_H_
0013 #define BROTLI_DEC_DECODE_H_
0014
0015 #include <brotli/port.h>
0016 #include <brotli/shared_dictionary.h>
0017 #include <brotli/types.h>
0018
0019 #if defined(__cplusplus) || defined(c_plusplus)
0020 extern "C" {
0021 #endif
0022
0023 /**
0024  * Opaque structure that holds decoder state.
0025  *
0026  * Allocated and initialized with ::BrotliDecoderCreateInstance.
0027  * Cleaned up and deallocated with ::BrotliDecoderDestroyInstance.
0028  */
0029 typedef struct BrotliDecoderStateStruct BrotliDecoderState;
0030
0031 /**
0032  * Result type for ::BrotliDecoderDecompress and
0033  * ::BrotliDecoderDecompressStream functions.
0034  */
0035 typedef enum {
0036   /** Decoding error, e.g. corrupted input or memory allocation problem. */
0037   BROTLI_DECODER_RESULT_ERROR = 0,
0038   /** Decoding successfully completed. */
0039   BROTLI_DECODER_RESULT_SUCCESS = 1,
0040   /** Partially done; should be called again with more input. */
0041   BROTLI_DECODER_RESULT_NEEDS_MORE_INPUT = 2,
0042   /** Partially done; should be called again with more output. */
0043   BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT = 3
0044 } BrotliDecoderResult;
0045
0046 /**
0047  * Template that evaluates items of ::BrotliDecoderErrorCode.
0048  *
0049  * Example: @code {.cpp}
0050  * // Log Brotli error code.
0051  * switch (brotliDecoderErrorCode) {
0052  * #define CASE_(PREFIX, NAME, CODE) \
0053  *   case BROTLI_DECODER ## PREFIX ## NAME: \
0054  *     LOG(INFO) << "error code:" << #NAME; \
0055  *     break;
0056  * #define NEWLINE_
0057  * BROTLI_DECODER_ERROR_CODES_LIST(CASE_, NEWLINE_)
0058  * #undef CASE_
0059  * #undef NEWLINE_
0060  *   default: LOG(FATAL) << "unknown brotli error code";
0061  * }
0062  * @endcode
0063  */
0064 #define BROTLI_DECODER_ERROR_CODES_LIST(BROTLI_ERROR_CODE, SEPARATOR)      \
0065   BROTLI_ERROR_CODE(_, NO_ERROR, 0) SEPARATOR                              \
0066   /* Same as BrotliDecoderResult values */                                 \
0067   BROTLI_ERROR_CODE(_, SUCCESS, 1) SEPARATOR                               \
0068   BROTLI_ERROR_CODE(_, NEEDS_MORE_INPUT, 2) SEPARATOR                      \
0069   BROTLI_ERROR_CODE(_, NEEDS_MORE_OUTPUT, 3) SEPARATOR                     \
0070                                                                            \
0071   /* Errors caused by invalid input */                                     \
0072   BROTLI_ERROR_CODE(_ERROR_FORMAT_, EXUBERANT_NIBBLE, -1) SEPARATOR        \
0073   BROTLI_ERROR_CODE(_ERROR_FORMAT_, RESERVED, -2) SEPARATOR                \
0074   BROTLI_ERROR_CODE(_ERROR_FORMAT_, EXUBERANT_META_NIBBLE, -3) SEPARATOR   \
0075   BROTLI_ERROR_CODE(_ERROR_FORMAT_, SIMPLE_HUFFMAN_ALPHABET, -4) SEPARATOR \
0076   BROTLI_ERROR_CODE(_ERROR_FORMAT_, SIMPLE_HUFFMAN_SAME, -5) SEPARATOR     \
0077   BROTLI_ERROR_CODE(_ERROR_FORMAT_, CL_SPACE, -6) SEPARATOR                \
0078   BROTLI_ERROR_CODE(_ERROR_FORMAT_, HUFFMAN_SPACE, -7) SEPARATOR           \
0079   BROTLI_ERROR_CODE(_ERROR_FORMAT_, CONTEXT_MAP_REPEAT, -8) SEPARATOR      \
0080   BROTLI_ERROR_CODE(_ERROR_FORMAT_, BLOCK_LENGTH_1, -9) SEPARATOR          \
0081   BROTLI_ERROR_CODE(_ERROR_FORMAT_, BLOCK_LENGTH_2, -10) SEPARATOR         \
0082   BROTLI_ERROR_CODE(_ERROR_FORMAT_, TRANSFORM, -11) SEPARATOR              \
0083   BROTLI_ERROR_CODE(_ERROR_FORMAT_, DICTIONARY, -12) SEPARATOR             \
0084   BROTLI_ERROR_CODE(_ERROR_FORMAT_, WINDOW_BITS, -13) SEPARATOR            \
0085   BROTLI_ERROR_CODE(_ERROR_FORMAT_, PADDING_1, -14) SEPARATOR              \
0086   BROTLI_ERROR_CODE(_ERROR_FORMAT_, PADDING_2, -15) SEPARATOR              \
0087   BROTLI_ERROR_CODE(_ERROR_FORMAT_, DISTANCE, -16) SEPARATOR               \
0088                                                                            \
0089   /* -17 code is reserved */                                               \
0090                                                                            \
0091   BROTLI_ERROR_CODE(_ERROR_, COMPOUND_DICTIONARY, -18) SEPARATOR           \
0092   BROTLI_ERROR_CODE(_ERROR_, DICTIONARY_NOT_SET, -19) SEPARATOR            \
0093   BROTLI_ERROR_CODE(_ERROR_, INVALID_ARGUMENTS, -20) SEPARATOR             \
0094                                                                            \
0095   /* Memory allocation problems */                                         \
0096   BROTLI_ERROR_CODE(_ERROR_ALLOC_, CONTEXT_MODES, -21) SEPARATOR           \
0097   /* Literal, insert and distance trees together */                        \
0098   BROTLI_ERROR_CODE(_ERROR_ALLOC_, TREE_GROUPS, -22) SEPARATOR             \
0099   /* -23..-24 codes are reserved for distinct tree groups */               \
0100   BROTLI_ERROR_CODE(_ERROR_ALLOC_, CONTEXT_MAP, -25) SEPARATOR             \
0101   BROTLI_ERROR_CODE(_ERROR_ALLOC_, RING_BUFFER_1, -26) SEPARATOR           \
0102   BROTLI_ERROR_CODE(_ERROR_ALLOC_, RING_BUFFER_2, -27) SEPARATOR           \
0103   /* -28..-29 codes are reserved for dynamic ring-buffer allocation */     \
0104   BROTLI_ERROR_CODE(_ERROR_ALLOC_, BLOCK_TYPE_TREES, -30) SEPARATOR        \
0105                                                                            \
0106   /* "Impossible" states */                                                \
0107   BROTLI_ERROR_CODE(_ERROR_, UNREACHABLE, -31)
0108
0109 /**
0110  * Error code for detailed logging / production debugging.
0111  *
0112  * See ::BrotliDecoderGetErrorCode and ::BROTLI_LAST_ERROR_CODE.
0113  */
0114 typedef enum {
0115 #define BROTLI_COMMA_ ,
0116 #define BROTLI_ERROR_CODE_ENUM_ITEM_(PREFIX, NAME, CODE) \
0117     BROTLI_DECODER ## PREFIX ## NAME = CODE
0118   BROTLI_DECODER_ERROR_CODES_LIST(BROTLI_ERROR_CODE_ENUM_ITEM_, BROTLI_COMMA_)
0119 } BrotliDecoderErrorCode;
0120 #undef BROTLI_ERROR_CODE_ENUM_ITEM_
0121 #undef BROTLI_COMMA_
0122
0123 /**
0124  * The value of the last error code, negative integer.
0125  *
0126  * All other error code values are in the range from ::BROTLI_LAST_ERROR_CODE
0127  * to @c -1. There are also 4 other possible non-error codes @c 0 .. @c 3 in
0128  * ::BrotliDecoderErrorCode enumeration.
0129  */
0130 #define BROTLI_LAST_ERROR_CODE BROTLI_DECODER_ERROR_UNREACHABLE
0131
0132 /** Options to be used with ::BrotliDecoderSetParameter. */
0133 typedef enum BrotliDecoderParameter {
0134   /**
0135    * Disable "canny" ring buffer allocation strategy.
0136    *
0137    * Ring buffer is allocated according to window size, despite the real size of
0138    * the content.
0139    */
0140   BROTLI_DECODER_PARAM_DISABLE_RING_BUFFER_REALLOCATION = 0,
0141   /**
0142    * Flag that determines if "Large Window Brotli" is used.
0143    */
0144   BROTLI_DECODER_PARAM_LARGE_WINDOW = 1
0145 } BrotliDecoderParameter;
0146
0147 /**
0148  * Sets the specified parameter to the given decoder instance.
0149  *
0150  * @param state decoder instance
0151  * @param param parameter to set
0152  * @param value new parameter value
0153  * @returns ::BROTLI_FALSE if parameter is unrecognized, or value is invalid
0154  * @returns ::BROTLI_TRUE if value is accepted
0155  */
0156 BROTLI_DEC_API BROTLI_BOOL BrotliDecoderSetParameter(
0157     BrotliDecoderState* state, BrotliDecoderParameter param, uint32_t value);
0158
0159 /**
0160  * Adds LZ77 prefix dictionary, adds or replaces built-in static dictionary and
0161  * transforms.
0162  *
0163  * Attached dictionary ownership is not transferred.
0164  * Data provided to this method should be kept accessible until
0165  * decoding is finished and decoder instance is destroyed.
0166  *
0167  * @note Dictionaries can NOT be attached after actual decoding is started.
0168  *
0169  * @param state decoder instance
0170  * @param type dictionary data format
0171  * @param data_size length of memory region pointed by @p data
0172  * @param data dictionary data in format corresponding to @p type
0173  * @returns ::BROTLI_FALSE if dictionary is corrupted,
0174  *          or dictionary count limit is reached
0175  * @returns ::BROTLI_TRUE if dictionary is accepted / attached
0176  */
0177 BROTLI_DEC_API BROTLI_BOOL BrotliDecoderAttachDictionary(
0178     BrotliDecoderState* state, BrotliSharedDictionaryType type,
0179     size_t data_size, const uint8_t data[BROTLI_ARRAY_PARAM(data_size)]);
0180
0181 /**
0182  * Creates an instance of ::BrotliDecoderState and initializes it.
0183  *
0184  * The instance can be used once for decoding and should then be destroyed with
0185  * ::BrotliDecoderDestroyInstance, it cannot be reused for a new decoding
0186  * session.
0187  *
0188  * @p alloc_func and @p free_func @b MUST be both zero or both non-zero. In the
0189  * case they are both zero, default memory allocators are used. @p opaque is
0190  * passed to @p alloc_func and @p free_func when they are called. @p free_func
0191  * has to return without doing anything when asked to free a NULL pointer.
0192  *
0193  * @param alloc_func custom memory allocation function
0194  * @param free_func custom memory free function
0195  * @param opaque custom memory manager handle
0196  * @returns @c 0 if instance can not be allocated or initialized
0197  * @returns pointer to initialized ::BrotliDecoderState otherwise
0198  */
0199 BROTLI_DEC_API BrotliDecoderState* BrotliDecoderCreateInstance(
0200     brotli_alloc_func alloc_func, brotli_free_func free_func, void* opaque);
0201
0202 /**
0203  * Deinitializes and frees ::BrotliDecoderState instance.
0204  *
0205  * @param state decoder instance to be cleaned up and deallocated
0206  */
0207 BROTLI_DEC_API void BrotliDecoderDestroyInstance(BrotliDecoderState* state);
0208
0209 /**
0210  * Performs one-shot memory-to-memory decompression.
0211  *
0212  * Decompresses the data in @p encoded_buffer into @p decoded_buffer, and sets
0213  * @p *decoded_size to the decompressed length.
0214  *
0215  * @param encoded_size size of @p encoded_buffer
0216  * @param encoded_buffer compressed data buffer with at least @p encoded_size
0217  *        addressable bytes
0218  * @param[in, out] decoded_size @b in: size of @p decoded_buffer; \n
0219  *                 @b out: length of decompressed data written to
0220  *                 @p decoded_buffer
0221  * @param decoded_buffer decompressed data destination buffer
0222  * @returns ::BROTLI_DECODER_RESULT_ERROR if input is corrupted, memory
0223  *          allocation failed, or @p decoded_buffer is not large enough;
0224  * @returns ::BROTLI_DECODER_RESULT_SUCCESS otherwise
0225  */
0226 BROTLI_DEC_API BrotliDecoderResult BrotliDecoderDecompress(
0227     size_t encoded_size,
0228     const uint8_t encoded_buffer[BROTLI_ARRAY_PARAM(encoded_size)],
0229     size_t* decoded_size,
0230     uint8_t decoded_buffer[BROTLI_ARRAY_PARAM(*decoded_size)]);
0231
0232 /**
0233  * Decompresses the input stream to the output stream.
0234  *
0235  * The values @p *available_in and @p *available_out must specify the number of
0236  * bytes addressable at @p *next_in and @p *next_out respectively.
0237  * When @p *available_out is @c 0, @p next_out is allowed to be @c NULL.
0238  *
0239  * After each call, @p *available_in will be decremented by the amount of input
0240  * bytes consumed, and the @p *next_in pointer will be incremented by that
0241  * amount. Similarly, @p *available_out will be decremented by the amount of
0242  * output bytes written, and the @p *next_out pointer will be incremented by
0243  * that amount.
0244  *
0245  * @p total_out, if it is not a null-pointer, will be set to the number
0246  * of bytes decompressed since the last @p state initialization.
0247  *
0248  * @note Input is never overconsumed, so @p next_in and @p available_in could be
0249  * passed to the next consumer after decoding is complete.
0250  *
0251  * @param state decoder instance
0252  * @param[in, out] available_in @b in: amount of available input; \n
0253  *                 @b out: amount of unused input
0254  * @param[in, out] next_in pointer to the next compressed byte
0255  * @param[in, out] available_out @b in: length of output buffer; \n
0256  *                 @b out: remaining size of output buffer
0257  * @param[in, out] next_out output buffer cursor;
0258  *                 can be @c NULL if @p available_out is @c 0
0259  * @param[out] total_out number of bytes decompressed so far; can be @c NULL
0260  * @returns ::BROTLI_DECODER_RESULT_ERROR if input is corrupted, memory
0261  *          allocation failed, arguments were invalid, etc.;
0262  *          use ::BrotliDecoderGetErrorCode to get detailed error code
0263  * @returns ::BROTLI_DECODER_RESULT_NEEDS_MORE_INPUT decoding is blocked until
0264  *          more input data is provided
0265  * @returns ::BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT decoding is blocked until
0266  *          more output space is provided
0267  * @returns ::BROTLI_DECODER_RESULT_SUCCESS decoding is finished, no more
0268  *          input might be consumed and no more output will be produced
0269  */
0270 BROTLI_DEC_API BrotliDecoderResult BrotliDecoderDecompressStream(
0271   BrotliDecoderState* state, size_t* available_in, const uint8_t** next_in,
0272   size_t* available_out, uint8_t** next_out, size_t* total_out);
0273
0274 /**
0275  * Checks if decoder has more output.
0276  *
0277  * @param state decoder instance
0278  * @returns ::BROTLI_TRUE, if decoder has some unconsumed output
0279  * @returns ::BROTLI_FALSE otherwise
0280  */
0281 BROTLI_DEC_API BROTLI_BOOL BrotliDecoderHasMoreOutput(
0282     const BrotliDecoderState* state);
0283
0284 /**
0285  * Acquires pointer to internal output buffer.
0286  *
0287  * This method is used to make language bindings easier and more efficient:
0288  *  -# push data to ::BrotliDecoderDecompressStream,
0289  *     until ::BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT is reported
0290  *  -# use ::BrotliDecoderTakeOutput to peek bytes and copy to language-specific
0291  *     entity
0292  *
0293  * Also this could be useful if there is an output stream that is able to
0294  * consume all the provided data (e.g. when data is saved to file system).
0295  *
0296  * @attention After every call to ::BrotliDecoderTakeOutput @p *size bytes of
0297  *            output are considered consumed for all consecutive calls to the
0298  *            instance methods; returned pointer becomes invalidated as well.
0299  *
0300  * @note Decoder output is not guaranteed to be contiguous. This means that
0301  *       after the size-unrestricted call to ::BrotliDecoderTakeOutput,
0302  *       immediate next call to ::BrotliDecoderTakeOutput may return more data.
0303  *
0304  * @param state decoder instance
0305  * @param[in, out] size @b in: number of bytes caller is ready to take, @c 0 if
0306  *                 any amount could be handled; \n
0307  *                 @b out: amount of data pointed by returned pointer and
0308  *                 considered consumed; \n
0309  *                 out value is never greater than in value, unless it is @c 0
0310  * @returns pointer to output data
0311  */
0312 BROTLI_DEC_API const uint8_t* BrotliDecoderTakeOutput(
0313     BrotliDecoderState* state, size_t* size);
0314
0315 /**
0316  * Checks if instance has already consumed input.
0317  *
0318  * Instance that returns ::BROTLI_FALSE is considered "fresh" and could be
0319  * reused.
0320  *
0321  * @param state decoder instance
0322  * @returns ::BROTLI_TRUE if decoder has already used some input bytes
0323  * @returns ::BROTLI_FALSE otherwise
0324  */
0325 BROTLI_DEC_API BROTLI_BOOL BrotliDecoderIsUsed(const BrotliDecoderState* state);
0326
0327 /**
0328  * Checks if decoder instance reached the final state.
0329  *
0330  * @param state decoder instance
0331  * @returns ::BROTLI_TRUE if decoder is in a state where it reached the end of
0332  *          the input and produced all of the output
0333  * @returns ::BROTLI_FALSE otherwise
0334  */
0335 BROTLI_DEC_API BROTLI_BOOL BrotliDecoderIsFinished(
0336     const BrotliDecoderState* state);
0337
0338 /**
0339  * Acquires a detailed error code.
0340  *
0341  * Should be used only after ::BrotliDecoderDecompressStream returns
0342  * ::BROTLI_DECODER_RESULT_ERROR.
0343  *
0344  * See also ::BrotliDecoderErrorString
0345  *
0346  * @param state decoder instance
0347  * @returns last saved error code
0348  */
0349 BROTLI_DEC_API BrotliDecoderErrorCode BrotliDecoderGetErrorCode(
0350     const BrotliDecoderState* state);
0351
0352 /**
0353  * Converts error code to a c-string.
0354  */
0355 BROTLI_DEC_API const char* BrotliDecoderErrorString(BrotliDecoderErrorCode c);
0356
0357 /**
0358  * Gets a decoder library version.
0359  *
0360  * Look at BROTLI_MAKE_HEX_VERSION for more information.
0361  */
0362 BROTLI_DEC_API uint32_t BrotliDecoderVersion(void);
0363
0364 /**
0365  * Callback to fire on metadata block start.
0366  *
0367  * After this callback is fired, if @p size is not @c 0, it is followed by
0368  * ::brotli_decoder_metadata_chunk_func as more metadata block contents become
0369  * accessible.
0370  *
0371  * @param opaque callback handle
0372  * @param size size of metadata block
0373  */
0374 typedef void (*brotli_decoder_metadata_start_func)(void* opaque, size_t size);
0375
0376 /**
0377  * Callback to fire on metadata block chunk becomes available.
0378  *
0379  * This function can be invoked multiple times per metadata block; block should
0380  * be considered finished when sum of @p size matches the announced metadata
0381  * block size. Chunks contents pointed by @p data are transient and shouln not
0382  * be accessed after leaving the callback.
0383  *
0384  * @param opaque callback handle
0385  * @param data pointer to metadata contents
0386  * @param size size of metadata block chunk, at least @c 1
0387  */
0388 typedef void (*brotli_decoder_metadata_chunk_func)(void* opaque,
0389                                                    const uint8_t* data,
0390                                                    size_t size);
0391
0392 /**
0393  * Sets callback for receiving metadata blocks.
0394  *
0395  * @param state decoder instance
0396  * @param start_func callback on metadata block start
0397  * @param chunk_func callback on metadata block chunk
0398  * @param opaque callback handle
0399  */
0400 BROTLI_DEC_API void BrotliDecoderSetMetadataCallbacks(
0401     BrotliDecoderState* state,
0402     brotli_decoder_metadata_start_func start_func,
0403     brotli_decoder_metadata_chunk_func chunk_func, void* opaque);
0404
0405 #if defined(__cplusplus) || defined(c_plusplus)
0406 } /* extern "C" */
0407 #endif
0408
0409 #endif  /* BROTLI_DEC_DECODE_H_ */