third_party/brotli/dec/decode.h

   1 /* Copyright 2013 Google Inc. All Rights Reserved.
   2
   3    Licensed under the Apache License, Version 2.0 (the "License");
   4    you may not use this file except in compliance with the License.
   5    You may obtain a copy of the License at
   6
   7    http://www.apache.org/licenses/LICENSE-2.0
   8
   9    Unless required by applicable law or agreed to in writing, software
  10    distributed under the License is distributed on an "AS IS" BASIS,
  11    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12    See the License for the specific language governing permissions and
  13    limitations under the License.
  14 */
  15
  16 /* API for Brotli decompression */
  17
  18 #ifndef BROTLI_DEC_DECODE_H_
  19 #define BROTLI_DEC_DECODE_H_
  20
  21 #include "./state.h"
  22 #include "./streams.h"
  23 #include "./types.h"
  24
  25 #if defined(__cplusplus) || defined(c_plusplus)
  26 extern "C" {
  27 #endif
  28
  29 typedef enum {
  30   /* Decoding error, e.g. corrupt input or no memory */
  31   BROTLI_RESULT_ERROR = 0,
  32   /* Successfully completely done */
  33   BROTLI_RESULT_SUCCESS = 1,
  34   /* Partially done, but must be called again with more input */
  35   BROTLI_RESULT_NEEDS_MORE_INPUT = 2,
  36   /* Partially done, but must be called again with more output */
  37   BROTLI_RESULT_NEEDS_MORE_OUTPUT = 3
  38 } BrotliResult;
  39
  40 /* Sets *decoded_size to the decompressed size of the given encoded stream. */
  41 /* This function only works if the encoded buffer has a single meta block, */
  42 /* or if it has two meta-blocks, where the first is uncompressed and the */
  43 /* second is empty. */
  44 /* Returns 1 on success, 0 on failure. */
  45 BrotliResult BrotliDecompressedSize(size_t encoded_size,
  46                                     const uint8_t* encoded_buffer,
  47                                     size_t* decoded_size);
  48
  49 /* Decompresses the data in encoded_buffer into decoded_buffer, and sets */
  50 /* *decoded_size to the decompressed length. */
  51 /* Returns 0 if there was either a bit stream error or memory allocation */
  52 /* error, and 1 otherwise. */
  53 /* If decoded size is zero, returns 1 and keeps decoded_buffer unchanged. */
  54 BrotliResult BrotliDecompressBuffer(size_t encoded_size,
  55                                     const uint8_t* encoded_buffer,
  56                                     size_t* decoded_size,
  57                                     uint8_t* decoded_buffer);
  58
  59 /* Same as above, but uses the specified input and output callbacks instead */
  60 /* of reading from and writing to pre-allocated memory buffers. */
  61 BrotliResult BrotliDecompress(BrotliInput input, BrotliOutput output);
  62
  63 /* Same as above, but supports the caller to call the decoder repeatedly with
  64    partial data to support streaming. The state must be initialized with
  65    BrotliStateInit and reused with every call for the same stream.
  66    Return values:
  67    0: failure.
  68    1: success, and done.
  69    2: success so far, end not reached so should call again with more input.
  70    The finish parameter is used as follows, for a series of calls with the
  71    same state:
  72    0: Every call except the last one must be called with finish set to 0. The
  73       last call may have finish set to either 0 or 1. Only if finish is 0, can
  74       the function return 2. It may also return 0 or 1, in that case no more
  75       calls (even with finish 1) may be made.
  76    1: Only the last call may have finish set to 1. It's ok to give empty input
  77       if all input was already given to previous calls. It is also ok to have
  78       only one single call in total, with finish 1, and with all input
  79       available immediately. That matches the non-streaming case. If finish is
  80       1, the function can only return 0 or 1, never 2. After a finish, no more
  81       calls may be done.
  82    After everything is done, the state must be cleaned with BrotliStateCleanup
  83    to free allocated resources.
  84    The given BrotliOutput must always accept all output and make enough space,
  85    it returning a smaller value than the amount of bytes to write always results
  86    in an error.
  87 */
  88 BrotliResult BrotliDecompressStreaming(BrotliInput input, BrotliOutput output,
  89                                        int finish, BrotliState* s);
  90
  91 /* Same as above, but with memory buffers.
  92    Must be called with an allocated input buffer in *next_in and an allocated
  93    output buffer in *next_out. The values *available_in and *available_out
  94    must specify the allocated size in *next_in and *next_out respectively.
  95    The value *total_out must be 0 initially, and will be summed with the
  96    amount of output bytes written after each call, so that at the end it
  97    gives the complete decoded size.
  98    After each call, *available_in will be decremented by the amount of input
  99    bytes consumed, and the *next_in pointer will be incremented by that amount.
 100    Similarly, *available_out will be decremented by the amount of output
 101    bytes written, and the *next_out pointer will be incremented by that
 102    amount.
 103
 104    The input may be partial. With each next function call, *next_in and
 105    *available_in must be updated to point to a next part of the compressed
 106    input. The current implementation will always consume all input unless
 107    an error occurs, so normally *available_in will always be 0 after
 108    calling this function and the next adjacent part of input is desired.
 109
 110    In the current implementation, the function requires that there is enough
 111    output buffer size to write all currently processed input, so
 112    *available_out must be large enough. Since the function updates *next_out
 113    each time, as long as the output buffer is large enough you can keep
 114    reusing this variable. It is also possible to update *next_out and
 115    *available_out yourself before a next call, e.g. to point to a new larger
 116    buffer.
 117 */
 118 BrotliResult BrotliDecompressBufferStreaming(size_t* available_in,
 119                                              const uint8_t** next_in,
 120                                              int finish,
 121                                              size_t* available_out,
 122                                              uint8_t** next_out,
 123                                              size_t* total_out,
 124                                              BrotliState* s);
 125
 126 #if defined(__cplusplus) || defined(c_plusplus)
 127 } /* extern "C" */
 128 #endif
 129
 130 #endif  /* BROTLI_DEC_DECODE_H_ */