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 "./state.h"
  13 #include "./streams.h"
  14 #include "./types.h"
  15
  16 #if defined(__cplusplus) || defined(c_plusplus)
  17 extern "C" {
  18 #endif
  19
  20 typedef enum {
  21   /* Decoding error, e.g. corrupt input or no memory */
  22   BROTLI_RESULT_ERROR = 0,
  23   /* Successfully completely done */
  24   BROTLI_RESULT_SUCCESS = 1,
  25   /* Partially done, but must be called again with more input */
  26   BROTLI_RESULT_NEEDS_MORE_INPUT = 2,
  27   /* Partially done, but must be called again with more output */
  28   BROTLI_RESULT_NEEDS_MORE_OUTPUT = 3
  29 } BrotliResult;
  30
  31 /* BROTLI_FAILURE macro unwraps to BROTLI_RESULT_ERROR in non-debug build. */
  32 /* In debug build it dumps file name, line and pretty function name. */
  33 #if defined(_MSC_VER) || !defined(BROTLI_DEBUG)
  34 #define BROTLI_FAILURE() BROTLI_RESULT_ERROR
  35 #else
  36 #define BROTLI_FAILURE() \
  37     BrotliFailure(__FILE__, __LINE__, __PRETTY_FUNCTION__)
  38 static inline BrotliResult BrotliFailure(const char *f, int l, const char *fn) {
  39   fprintf(stderr, "ERROR at %s:%d (%s)\n", f, l, fn);
  40   fflush(stderr);
  41   return BROTLI_RESULT_ERROR;
  42 }
  43 #endif
  44
  45 /* Creates the instance of BrotliState and initializes it. alloc_func and
  46    free_func MUST be both zero or both non-zero. In the case they are both zero,
  47    default memory allocators are used. opaque parameter is passed to alloc_func
  48    and free_func when they are called. */
  49 BrotliState* BrotliCreateState(
  50     brotli_alloc_func alloc_func, brotli_free_func free_func, void* opaque);
  51
  52 /* Deinitializes and frees BrotliState instance. */
  53 void BrotliDestroyState(BrotliState* state);
  54
  55 /* Sets *decoded_size to the decompressed size of the given encoded stream. */
  56 /* This function only works if the encoded buffer has a single meta block, */
  57 /* or if it has two meta-blocks, where the first is uncompressed and the */
  58 /* second is empty. */
  59 /* Returns 1 on success, 0 on failure. */
  60 int BrotliDecompressedSize(size_t encoded_size,
  61                            const uint8_t* encoded_buffer,
  62                            size_t* decoded_size);
  63
  64 /* Decompresses the data in encoded_buffer into decoded_buffer, and sets */
  65 /* *decoded_size to the decompressed length. */
  66 BrotliResult BrotliDecompressBuffer(size_t encoded_size,
  67                                     const uint8_t* encoded_buffer,
  68                                     size_t* decoded_size,
  69                                     uint8_t* decoded_buffer);
  70
  71 /* Same as above, but uses the specified input and output callbacks instead */
  72 /* of reading from and writing to pre-allocated memory buffers. */
  73 /* DEPRECATED */
  74 BrotliResult BrotliDecompress(BrotliInput input, BrotliOutput output);
  75
  76 /* Same as above, but supports the caller to call the decoder repeatedly with
  77    partial data to support streaming. The state must be initialized with
  78    BrotliStateInit and reused with every call for the same stream.
  79    Return values:
  80    0: failure.
  81    1: success, and done.
  82    2: success so far, end not reached so should call again with more input.
  83    The finish parameter is used as follows, for a series of calls with the
  84    same state:
  85    0: Every call except the last one must be called with finish set to 0. The
  86       last call may have finish set to either 0 or 1. Only if finish is 0, can
  87       the function return 2. It may also return 0 or 1, in that case no more
  88       calls (even with finish 1) may be made.
  89    1: Only the last call may have finish set to 1. It's ok to give empty input
  90       if all input was already given to previous calls. It is also ok to have
  91       only one single call in total, with finish 1, and with all input
  92       available immediately. That matches the non-streaming case. If finish is
  93       1, the function can only return 0 or 1, never 2. After a finish, no more
  94       calls may be done.
  95    After everything is done, the state must be cleaned with BrotliStateCleanup
  96    to free allocated resources.
  97    The given BrotliOutput must always accept all output and make enough space,
  98    it returning a smaller value than the amount of bytes to write always results
  99    in an error.
 100 */
 101 /* DEPRECATED */
 102 BrotliResult BrotliDecompressStreaming(BrotliInput input, BrotliOutput output,
 103                                        int finish, BrotliState* s);
 104
 105 /* Same as above, but with memory buffers.
 106    Must be called with an allocated input buffer in *next_in and an allocated
 107    output buffer in *next_out. The values *available_in and *available_out
 108    must specify the allocated size in *next_in and *next_out respectively.
 109    The value *total_out must be 0 initially, and will be summed with the
 110    amount of output bytes written after each call, so that at the end it
 111    gives the complete decoded size.
 112    After each call, *available_in will be decremented by the amount of input
 113    bytes consumed, and the *next_in pointer will be incremented by that amount.
 114    Similarly, *available_out will be decremented by the amount of output
 115    bytes written, and the *next_out pointer will be incremented by that
 116    amount.
 117
 118    The input may be partial. With each next function call, *next_in and
 119    *available_in must be updated to point to a next part of the compressed
 120    input. The current implementation will always consume all input unless
 121    an error occurs, so normally *available_in will always be 0 after
 122    calling this function and the next adjacent part of input is desired.
 123
 124    In the current implementation, the function requires that there is enough
 125    output buffer size to write all currently processed input, so
 126    *available_out must be large enough. Since the function updates *next_out
 127    each time, as long as the output buffer is large enough you can keep
 128    reusing this variable. It is also possible to update *next_out and
 129    *available_out yourself before a next call, e.g. to point to a new larger
 130    buffer.
 131 */
 132 /* DEPRECATED */
 133 BrotliResult BrotliDecompressBufferStreaming(size_t* available_in,
 134                                              const uint8_t** next_in,
 135                                              int finish,
 136                                              size_t* available_out,
 137                                              uint8_t** next_out,
 138                                              size_t* total_out,
 139                                              BrotliState* s);
 140
 141 BrotliResult BrotliDecompressStream(size_t* available_in,
 142                                     const uint8_t** next_in,
 143                                     size_t* available_out,
 144                                     uint8_t** next_out,
 145                                     size_t* total_out,
 146                                     BrotliState* s);
 147
 148 /* Fills the new state with a dictionary for LZ77, warming up the ringbuffer,
 149    e.g. for custom static dictionaries for data formats.
 150    Not to be confused with the built-in transformable dictionary of Brotli.
 151    The dictionary must exist in memory until decoding is done and is owned by
 152    the caller. To use:
 153    -initialize state with BrotliStateInit
 154    -use BrotliSetCustomDictionary
 155    -use BrotliDecompressBufferStreaming
 156    -clean up with BrotliStateCleanup
 157 */
 158 void BrotliSetCustomDictionary(
 159     size_t size, const uint8_t* dict, BrotliState* s);
 160
 161
 162 #if defined(__cplusplus) || defined(c_plusplus)
 163 } /* extern "C" */
 164 #endif
 165
 166 #endif  /* BROTLI_DEC_DECODE_H_ */