MdeModulePkg/Library/BrotliCustomDecompressLib/dec/decode.h

   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 /* API for Brotli decompression */
   8
   9 #ifndef BROTLI_DEC_DECODE_H_
  10 #define BROTLI_DEC_DECODE_H_
  11
  12 #include "../common/types.h"
  13
  14 #if defined(__cplusplus) || defined(c_plusplus)
  15 extern "C" {
  16 #endif
  17
  18 typedef struct BrotliDecoderStateStruct BrotliDecoderState;
  19
  20 typedef enum {
  21   /* Decoding error, e.g. corrupt input or memory allocation problem */
  22   BROTLI_DECODER_RESULT_ERROR = 0,
  23   /* Decoding successfully completed */
  24   BROTLI_DECODER_RESULT_SUCCESS = 1,
  25   /* Partially done; should be called again with more input */
  26   BROTLI_DECODER_RESULT_NEEDS_MORE_INPUT = 2,
  27   /* Partially done; should be called again with more output */
  28   BROTLI_DECODER_RESULT_NEEDS_MORE_OUTPUT = 3
  29 } BrotliDecoderResult;
  30
  31 #define BROTLI_DECODER_ERROR_CODES_LIST(BROTLI_ERROR_CODE, SEPARATOR)      \
  32   BROTLI_ERROR_CODE(_, NO_ERROR, 0) SEPARATOR                              \
  33   /* Same as BrotliDecoderResult values */                                 \
  34   BROTLI_ERROR_CODE(_, SUCCESS, 1) SEPARATOR                               \
  35   BROTLI_ERROR_CODE(_, NEEDS_MORE_INPUT, 2) SEPARATOR                      \
  36   BROTLI_ERROR_CODE(_, NEEDS_MORE_OUTPUT, 3) SEPARATOR                     \
  37                                                                            \
  38   /* Errors caused by invalid input */                                     \
  39   BROTLI_ERROR_CODE(_ERROR_FORMAT_, EXUBERANT_NIBBLE, -1) SEPARATOR        \
  40   BROTLI_ERROR_CODE(_ERROR_FORMAT_, RESERVED, -2) SEPARATOR                \
  41   BROTLI_ERROR_CODE(_ERROR_FORMAT_, EXUBERANT_META_NIBBLE, -3) SEPARATOR   \
  42   BROTLI_ERROR_CODE(_ERROR_FORMAT_, SIMPLE_HUFFMAN_ALPHABET, -4) SEPARATOR \
  43   BROTLI_ERROR_CODE(_ERROR_FORMAT_, SIMPLE_HUFFMAN_SAME, -5) SEPARATOR     \
  44   BROTLI_ERROR_CODE(_ERROR_FORMAT_, CL_SPACE, -6) SEPARATOR                \
  45   BROTLI_ERROR_CODE(_ERROR_FORMAT_, HUFFMAN_SPACE, -7) SEPARATOR           \
  46   BROTLI_ERROR_CODE(_ERROR_FORMAT_, CONTEXT_MAP_REPEAT, -8) SEPARATOR      \
  47   BROTLI_ERROR_CODE(_ERROR_FORMAT_, BLOCK_LENGTH_1, -9) SEPARATOR          \
  48   BROTLI_ERROR_CODE(_ERROR_FORMAT_, BLOCK_LENGTH_2, -10) SEPARATOR         \
  49   BROTLI_ERROR_CODE(_ERROR_FORMAT_, TRANSFORM, -11) SEPARATOR              \
  50   BROTLI_ERROR_CODE(_ERROR_FORMAT_, DICTIONARY, -12) SEPARATOR             \
  51   BROTLI_ERROR_CODE(_ERROR_FORMAT_, WINDOW_BITS, -13) SEPARATOR            \
  52   BROTLI_ERROR_CODE(_ERROR_FORMAT_, PADDING_1, -14) SEPARATOR              \
  53   BROTLI_ERROR_CODE(_ERROR_FORMAT_, PADDING_2, -15) SEPARATOR              \
  54                                                                            \
  55   /* -16..-20 codes are reserved */                                        \
  56                                                                            \
  57   /* Memory allocation problems */                                         \
  58   BROTLI_ERROR_CODE(_ERROR_ALLOC_, CONTEXT_MODES, -21) SEPARATOR           \
  59   /* Literal, insert and distance trees together */                        \
  60   BROTLI_ERROR_CODE(_ERROR_ALLOC_, TREE_GROUPS, -22) SEPARATOR             \
  61   /* -23..-24 codes are reserved for distinct tree groups */               \
  62   BROTLI_ERROR_CODE(_ERROR_ALLOC_, CONTEXT_MAP, -25) SEPARATOR             \
  63   BROTLI_ERROR_CODE(_ERROR_ALLOC_, RING_BUFFER_1, -26) SEPARATOR           \
  64   BROTLI_ERROR_CODE(_ERROR_ALLOC_, RING_BUFFER_2, -27) SEPARATOR           \
  65   /* -28..-29 codes are reserved for dynamic ringbuffer allocation */      \
  66   BROTLI_ERROR_CODE(_ERROR_ALLOC_, BLOCK_TYPE_TREES, -30) SEPARATOR        \
  67                                                                            \
  68   /* "Impossible" states */                                                \
  69   BROTLI_ERROR_CODE(_ERROR_, UNREACHABLE, -31)
  70
  71 typedef enum {
  72 #define _BROTLI_COMMA ,
  73 #define _BROTLI_ERROR_CODE_ENUM_ITEM(PREFIX, NAME, CODE) \
  74     BROTLI_DECODER ## PREFIX ## NAME = CODE
  75   BROTLI_DECODER_ERROR_CODES_LIST(_BROTLI_ERROR_CODE_ENUM_ITEM, _BROTLI_COMMA)
  76 #undef _BROTLI_ERROR_CODE_ENUM_ITEM
  77 #undef _BROTLI_COMMA
  78 } BrotliDecoderErrorCode;
  79
  80 #define BROTLI_LAST_ERROR_CODE BROTLI_DECODER_ERROR_UNREACHABLE
  81
  82 /* Creates the instance of BrotliDecoderState and initializes it. |alloc_func|
  83    and |free_func| MUST be both zero or both non-zero. In the case they are both
  84    zero, default memory allocators are used. |opaque| is passed to |alloc_func|
  85    and |free_func| when they are called. */
  86 BrotliDecoderState* BrotliDecoderCreateInstance(
  87     brotli_alloc_func alloc_func, brotli_free_func free_func, void* opaque);
  88
  89 /* Deinitializes and frees BrotliDecoderState instance. */
  90 void BrotliDecoderDestroyInstance(BrotliDecoderState* state);
  91
  92 /* Decompresses the data in |encoded_buffer| into |decoded_buffer|, and sets
  93    |*decoded_size| to the decompressed length. */
  94 BrotliDecoderResult BrotliDecoderDecompress(
  95     size_t encoded_size, const uint8_t* encoded_buffer, size_t* decoded_size,
  96     uint8_t* decoded_buffer);
  97
  98 /* Decompresses the data. Supports partial input and output.
  99
 100    Must be called with an allocated input buffer in |*next_in| and an allocated
 101    output buffer in |*next_out|. The values |*available_in| and |*available_out|
 102    must specify the allocated size in |*next_in| and |*next_out| respectively.
 103
 104    After each call, |*available_in| will be decremented by the amount of input
 105    bytes consumed, and the |*next_in| pointer will be incremented by that
 106    amount. Similarly, |*available_out| will be decremented by the amount of
 107    output bytes written, and the |*next_out| pointer will be incremented by that
 108    amount. |total_out|, if it is not a null-pointer, will be set to the number
 109    of bytes decompressed since the last state initialization.
 110
 111    Input is never overconsumed, so |next_in| and |available_in| could be passed
 112    to the next consumer after decoding is complete. */
 113 BrotliDecoderResult BrotliDecoderDecompressStream(
 114   BrotliDecoderState* s, size_t* available_in, const uint8_t** next_in,
 115   size_t* available_out, uint8_t** next_out, size_t* total_out);
 116
 117 /* Fills the new state with a dictionary for LZ77, warming up the ringbuffer,
 118    e.g. for custom static dictionaries for data formats.
 119    Not to be confused with the built-in transformable dictionary of Brotli.
 120    |size| should be less or equal to 2^24 (16MiB), otherwise the dictionary will
 121    be ignored. The dictionary must exist in memory until decoding is done and
 122    is owned by the caller. To use:
 123     1) Allocate and initialize state with BrotliCreateInstance
 124     2) Use BrotliSetCustomDictionary
 125     3) Use BrotliDecompressStream
 126     4) Clean up and free state with BrotliDestroyState
 127 */
 128 void BrotliDecoderSetCustomDictionary(
 129     BrotliDecoderState* s, size_t size, const uint8_t* dict);
 130
 131 /* Returns true, if decoder has some unconsumed output.
 132    Otherwise returns false. */
 133 BROTLI_BOOL BrotliDecoderHasMoreOutput(const BrotliDecoderState* s);
 134
 135 /* Returns true, if decoder has already received some input bytes.
 136    Otherwise returns false. */
 137 BROTLI_BOOL BrotliDecoderIsUsed(const BrotliDecoderState* s);
 138
 139 /* Returns true, if decoder is in a state where we reached the end of the input
 140    and produced all of the output; returns false otherwise. */
 141 BROTLI_BOOL BrotliDecoderIsFinished(const BrotliDecoderState* s);
 142
 143 /* Returns detailed error code after BrotliDecompressStream returns
 144    BROTLI_DECODER_RESULT_ERROR. */
 145 BrotliDecoderErrorCode BrotliDecoderGetErrorCode(const BrotliDecoderState* s);
 146
 147 const char* BrotliDecoderErrorString(BrotliDecoderErrorCode c);
 148
 149 /* DEPRECATED >>> */
 150 typedef enum {
 151   BROTLI_RESULT_ERROR = 0,
 152   BROTLI_RESULT_SUCCESS = 1,
 153   BROTLI_RESULT_NEEDS_MORE_INPUT = 2,
 154   BROTLI_RESULT_NEEDS_MORE_OUTPUT = 3
 155 } BrotliResult;
 156 typedef enum {
 157 #define _BROTLI_COMMA ,
 158 #define _BROTLI_ERROR_CODE_ENUM_ITEM(PREFIX, NAME, CODE) \
 159     BROTLI ## PREFIX ## NAME = CODE
 160   BROTLI_DECODER_ERROR_CODES_LIST(_BROTLI_ERROR_CODE_ENUM_ITEM, _BROTLI_COMMA)
 161 #undef _BROTLI_ERROR_CODE_ENUM_ITEM
 162 #undef _BROTLI_COMMA
 163 } BrotliErrorCode;
 164 typedef struct BrotliStateStruct BrotliState;
 165 BrotliState* BrotliCreateState(
 166     brotli_alloc_func alloc, brotli_free_func free, void* opaque);
 167 void BrotliDestroyState(BrotliState* state);
 168 BROTLI_BOOL BrotliDecompressedSize(
 169     size_t encoded_size, const uint8_t* encoded_buffer, size_t* decoded_size);
 170 BrotliResult BrotliDecompressBuffer(
 171     size_t encoded_size, const uint8_t* encoded_buffer, size_t* decoded_size,
 172     uint8_t* decoded_buffer);
 173 BrotliResult BrotliDecompressStream(
 174     size_t* available_in, const uint8_t** next_in, size_t* available_out,
 175     uint8_t** next_out, size_t* total_out, BrotliState* s);
 176 void BrotliSetCustomDictionary(
 177     size_t size, const uint8_t* dict, BrotliState* s);
 178 BROTLI_BOOL BrotliStateIsStreamStart(const BrotliState* s);
 179 BROTLI_BOOL BrotliStateIsStreamEnd(const BrotliState* s);
 180 BrotliErrorCode BrotliGetErrorCode(const BrotliState* s);
 181 const char* BrotliErrorString(BrotliErrorCode c);
 182 /* <<< DEPRECATED */
 183
 184 #if defined(__cplusplus) || defined(c_plusplus)
 185 } /* extern "C" */
 186 #endif
 187
 188 #endif  /* BROTLI_DEC_DECODE_H_ */