1/*
2Copyright (c) 2015-2016, Apple Inc. All rights reserved.
3
4Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
5
61. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
7
82. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer
9 in the documentation and/or other materials provided with the distribution.
10
113. Neither the name of the copyright holder(s) nor the names of any contributors may be used to endorse or promote products derived
12 from this software without specific prior written permission.
13
14THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
15LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
16COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
17(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
18HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
19ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
20*/
21
22#ifndef LZFSE_H
23#define LZFSE_H
24
25#include <stddef.h>
26#include <stdint.h>
27
28#define LZFSE_LIB_API __attribute__((visibility("default")))
29
30/*! @abstract Get the required scratch buffer size to compress using LZFSE. */
31size_t lzfse_encode_scratch_size() LZFSE_LIB_API;
32
33/*! @abstract Compress a buffer using LZFSE.
34 *
35 * @param dst_buffer
36 * Pointer to the first byte of the destination buffer.
37 *
38 * @param dst_size
39 * Size of the destination buffer in bytes.
40 *
41 * @param src_buffer
42 * Pointer to the first byte of the source buffer.
43 *
44 * @param src_size
45 * Size of the source buffer in bytes.
46 *
47 * @param scratch_buffer
48 * If non-NULL, a pointer to scratch space for the routine to use as workspace;
49 * the routine may use up to lzfse_encode_scratch_size( ) bytes of workspace
50 * during its operation, and will not perform any internal allocations. If
51 * NULL, the routine may allocate its own memory to use during operation via
52 * a single call to malloc( ), and will release it by calling free( ) prior
53 * to returning. For most use, passing NULL is perfectly satisfactory, but if
54 * you require strict control over allocation, you will want to pass an
55 * explicit scratch buffer.
56 *
57 * @return
58 * The number of bytes written to the destination buffer if the input is
59 * successfully compressed. If the input cannot be compressed to fit into
60 * the provided buffer, or an error occurs, zero is returned, and the
61 * contents of dst_buffer are unspecified. */
62size_t lzfse_encode_buffer(uint8_t *__restrict dst_buffer,
63 size_t dst_size,
64 const uint8_t *__restrict src_buffer,
65 size_t src_size,
66 void *__restrict scratch_buffer) LZFSE_LIB_API;
67
68/*! @abstract Get the required scratch buffer size to decompress using LZFSE. */
69size_t lzfse_decode_scratch_size() LZFSE_LIB_API;
70
71/*! @abstract Decompress a buffer using LZFSE.
72 *
73 * @param dst_buffer
74 * Pointer to the first byte of the destination buffer.
75 *
76 * @param dst_size
77 * Size of the destination buffer in bytes.
78 *
79 * @param src_buffer
80 * Pointer to the first byte of the source buffer.
81 *
82 * @param src_size
83 * Size of the source buffer in bytes.
84 *
85 * @param scratch_buffer
86 * If non-NULL, a pointer to scratch space for the routine to use as workspace;
87 * the routine may use up to lzfse_decode_scratch_size( ) bytes of workspace
88 * during its operation, and will not perform any internal allocations. If
89 * NULL, the routine may allocate its own memory to use during operation via
90 * a single call to malloc( ), and will release it by calling free( ) prior
91 * to returning. For most use, passing NULL is perfectly satisfactory, but if
92 * you require strict control over allocation, you will want to pass an
93 * explicit scratch buffer.
94 *
95 * @return
96 * The number of bytes written to the destination buffer if the input is
97 * successfully decompressed. If there is not enough space in the destination
98 * buffer to hold the entire expanded output, only the first dst_size bytes
99 * will be written to the buffer and dst_size is returned. Note that this
100 * behavior differs from that of lzfse_encode_buffer. */
101size_t lzfse_decode_buffer(uint8_t *__restrict dst_buffer,
102 size_t dst_size,
103 const uint8_t *__restrict src_buffer,
104 size_t src_size,
105 void *__restrict scratch_buffer) LZFSE_LIB_API;
106
107#endif // LZFSE_H
108