1/*
2 * Copyright 2017-present Facebook, Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#pragma once
18
19#include <folly/Portability.h>
20#include <folly/compression/Compression.h>
21
22#if FOLLY_HAVE_LIBZ
23
24#include <zlib.h>
25
26/**
27 * Interface for Zlib-specific codec initialization.
28 */
29namespace folly {
30namespace io {
31namespace zlib {
32
33struct Options {
34 /**
35 * ZLIB: default option -- write a zlib wrapper as documented in RFC 1950.
36 *
37 * GZIP: write a simple gzip header and trailer around the compressed data
38 * instead of a zlib wrapper.
39 *
40 * RAW: deflate will generate raw deflate data with no zlib header or
41 * trailer, and will not compute a check value.
42 *
43 * AUTO: enable automatic header detection for decoding gzip or zlib data.
44 * For deflation, ZLIB will be used.
45 */
46 enum class Format { ZLIB, GZIP, RAW, AUTO };
47
48 explicit Options(
49 Format format_ = Format::ZLIB,
50 int windowSize_ = 15,
51 int memLevel_ = 8,
52 int strategy_ = Z_DEFAULT_STRATEGY)
53 : format(format_),
54 windowSize(windowSize_),
55 memLevel(memLevel_),
56 strategy(strategy_) {}
57
58 Format format;
59
60 /**
61 * windowSize is the base two logarithm of the window size (the size of the
62 * history buffer). It should be in the range 9..15. Larger values of this
63 * parameter result in better compression at the expense of memory usage.
64 *
65 * The default value is 15.
66 *
67 * NB: when inflating/uncompressing data, the windowSize must be greater than
68 * or equal to the size used when deflating/compressing.
69 */
70 int windowSize;
71
72 /**
73 * "The memLevel parameter specifies how much memory should be allocated for
74 * the internal compression state. memLevel=1 uses minimum memory but is slow
75 * and reduces compression ratio; memLevel=9 uses maximum memory for optimal
76 * speed. The default value is 8."
77 */
78 int memLevel;
79
80 /**
81 * The strategy parameter is used to tune the compression algorithm.
82 * Supported values:
83 * - Z_DEFAULT_STRATEGY: normal data
84 * - Z_FILTERED: data produced by a filter (or predictor)
85 * - Z_HUFFMAN_ONLY: force Huffman encoding only (no string match)
86 * - Z_RLE: limit match distances to one
87 * - Z_FIXED: prevents the use of dynamic Huffman codes
88 *
89 * The strategy parameter only affects the compression ratio but not the
90 * correctness of the compressed output.
91 */
92 int strategy;
93};
94
95/**
96 * Get the default options for gzip compression.
97 * A codec created with these options will have type CodecType::GZIP.
98 */
99Options defaultGzipOptions();
100
101/**
102 * Get the default options for zlib compression.
103 * A codec created with these options will have type CodecType::ZLIB.
104 */
105Options defaultZlibOptions();
106
107/**
108 * Get a codec with the given options and compression level.
109 *
110 * If the windowSize is 15 and the format is Format::ZLIB or Format::GZIP, then
111 * the type of the codec will be CodecType::ZLIB or CodecType::GZIP
112 * respectively. Otherwise, the type will be CodecType::USER_DEFINED.
113 *
114 * Automatic uncompression is not supported with USER_DEFINED codecs.
115 *
116 * Levels supported: 0 = no compression, 1 = fast, ..., 9 = best; default = 6
117 */
118std::unique_ptr<Codec> getCodec(
119 Options options = Options(),
120 int level = COMPRESSION_LEVEL_DEFAULT);
121std::unique_ptr<StreamCodec> getStreamCodec(
122 Options options = Options(),
123 int level = COMPRESSION_LEVEL_DEFAULT);
124
125} // namespace zlib
126} // namespace io
127} // namespace folly
128
129#endif // FOLLY_HAVE_LIBZ
130