chiroptera/pack/libxpack.d

   1 /*
   2 libxpack.h - public header for libxpack
   3
   4 Copyright 2016 Eric Biggers
   5
   6 Permission is hereby granted, free of charge, to any person
   7 obtaining a copy of this software and associated documentation files
   8 (the "Software"), to deal in the Software without restriction,
   9 including without limitation the rights to use, copy, modify, merge,
  10 publish, distribute, sublicense, and/or sell copies of the Software,
  11 and to permit persons to whom the Software is furnished to do so,
  12 subject to the following conditions:
  13
  14 The above copyright notice and this permission notice shall be
  15 included in all copies or substantial portions of the Software.
  16
  17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  18 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  19 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  20 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
  21 BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
  22 ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  23 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  24 SOFTWARE.
  25 */
  26 module chiroptera.pack.libxpack;
  27 pragma(lib, "xpackzng");
  28 extern(C):
  29 public nothrow @nogc @trusted:
  30
  31
  32 /* ========================================================================== */
  33 /*                               Compression                                  */
  34 /* ========================================================================== */
  35
  36 struct xpack_compressor;
  37
  38 /*
  39  * xpack_alloc_compressor() allocates a new compressor.
  40  *
  41  * 'max_buffer_size' is the maximum size of any buffer which will be compressed
  42  * by the compressor.  This specifies the maximum allowed value for the
  43  * 'uncompressed_size' parameter of xpack_compress() when called using this
  44  * compressor.
  45  *
  46  * 'compression_level' is the compression level on a zlib-like scale (1 =
  47  * fastest, 6 = medium/default, 9 = slowest).
  48  *
  49  * Returns a pointer to the new compressor, or NULL if out of memory or the
  50  * maximum buffer size or compression level is not supported.
  51  */
  52 xpack_compressor* xpack_alloc_compressor (usize max_buffer_size, int compression_level);
  53
  54 /*
  55  * xpack_compress() compresses a buffer of data.  The function attempts to
  56  * compress 'in_nbytes' bytes of data located at 'in' and write the results to
  57  * 'out', which has space for 'out_nbytes_avail' bytes.  The return value is the
  58  * compressed size in bytes, or 0 if the data could not be compressed to
  59  * 'out_nbytes_avail' bytes or fewer.
  60  */
  61 usize xpack_compress (xpack_compressor* compressor,
  62                       const(void)* input, usize in_nbytes,
  63                       void *output, usize out_nbytes_avail);
  64
  65 /*
  66  * xpack_free_compressor() frees a compressor allocated with
  67  * xpack_alloc_compressor().  If NULL is passed, then no action is taken.
  68  */
  69 void xpack_free_compressor (xpack_compressor* compressor);
  70
  71
  72 /* ========================================================================== */
  73 /*                               Decompression                                */
  74 /* ========================================================================== */
  75
  76 struct xpack_decompressor;
  77
  78 /*
  79  * xpack_alloc_decompressor() allocates a new decompressor.
  80  *
  81  * Returns a pointer to the new decompressor, or NULL if out of memory.
  82  */
  83 xpack_decompressor* xpack_alloc_decompressor ();
  84
  85 /* Result of a call to xpack_decompress() */
  86 alias decompress_result = int;
  87 enum /*decompress_result*/ {
  88   /* Decompression was successful */
  89   DECOMPRESS_SUCCESS = 0,
  90
  91   /* Decompressed failed because the compressed data was invalid, corrupt,
  92    * or otherwise unsupported */
  93   DECOMPRESS_BAD_DATA = 1,
  94
  95   /* A NULL 'actual_out_nbytes_ret' was provided, but the data would have
  96    * decompressed to fewer than 'out_nbytes_avail' bytes */
  97   DECOMPRESS_SHORT_OUTPUT = 2,
  98
  99   /* The data would have decompressed to more than 'out_nbytes_avail'
 100    * bytes */
 101   DECOMPRESS_INSUFFICIENT_SPACE = 3,
 102 }
 103
 104 /*
 105  * xpack_decompress() decompresses 'in_nbytes' bytes of compressed data at 'in'
 106  * and writes the uncompressed data to 'out', which is a buffer of at least
 107  * 'out_nbytes_avail' bytes.  If decompression was successful, then 0
 108  * (DECOMPRESS_SUCCESS) is returned; otherwise, a nonzero result code such as
 109  * DECOMPRESS_BAD_DATA is returned.  If a nonzero result code is returned, then
 110  * the contents of the output buffer are undefined.
 111  *
 112  * xpack_decompress() can be used in cases where the actual uncompressed size is
 113  * known (recommended) or unknown (not recommended):
 114  *
 115  *   - If the actual uncompressed size is known, then pass the actual
 116  *     uncompressed size as 'out_nbytes_avail' and pass NULL for
 117  *     'actual_out_nbytes_ret'.  This makes xpack_decompress() fail with
 118  *     DECOMPRESS_SHORT_OUTPUT if the data decompressed to fewer than the
 119  *     specified number of bytes.
 120  *
 121  *   - If the actual uncompressed size is unknown, then provide a non-NULL
 122  *     'actual_out_nbytes_ret' and provide a buffer with some size
 123  *     'out_nbytes_avail' that you think is large enough to hold all the
 124  *     uncompressed data.  In this case, if the data decompresses to less than
 125  *     or equal to 'out_nbytes_avail' bytes, then xpack_decompress() will write
 126  *     the actual uncompressed size to *actual_out_nbytes_ret and return 0
 127  *     (DECOMPRESS_SUCCESS).  Otherwise, it will return
 128  *     DECOMPRESS_INSUFFICIENT_SPACE if the provided buffer was not large enough
 129  *     but no other problems were encountered, or another nonzero result code if
 130  *     decompression failed for another reason.
 131  */
 132 decompress_result xpack_decompress (xpack_decompressor* decompressor,
 133                                     const(void)* input, usize in_nbytes,
 134                                     void *output, usize out_nbytes_avail,
 135                                     usize* actual_out_nbytes_ret);
 136
 137 /*
 138  * xpack_free_decompressor() frees a decompressor allocated with
 139  * xpack_alloc_decompressor().  If NULL is passed, no action is taken.
 140  */
 141 void xpack_free_decompressor (xpack_decompressor* decompressor);