1/* Copyright 2017 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/* (Opaque) Shared Dictionary definition and utilities. */
8
9#ifndef BROTLI_COMMON_SHARED_DICTIONARY_H_
10#define BROTLI_COMMON_SHARED_DICTIONARY_H_
11
12#include <brotli/port.h>
13#include <brotli/types.h>
14
15#if defined(__cplusplus) || defined(c_plusplus)
16extern "C" {
17#endif
18
19#define SHARED_BROTLI_MIN_DICTIONARY_WORD_LENGTH 4
20#define SHARED_BROTLI_MAX_DICTIONARY_WORD_LENGTH 31
21#define SHARED_BROTLI_NUM_DICTIONARY_CONTEXTS 64
22#define SHARED_BROTLI_MAX_COMPOUND_DICTS 15
23
24/**
25 * Opaque structure that holds shared dictionary data.
26 *
27 * Allocated and initialized with ::BrotliSharedDictionaryCreateInstance.
28 * Cleaned up and deallocated with ::BrotliSharedDictionaryDestroyInstance.
29 */
30typedef struct BrotliSharedDictionaryStruct BrotliSharedDictionary;
31
32/**
33 * Input data type for ::BrotliSharedDictionaryAttach.
34 */
35typedef enum BrotliSharedDictionaryType {
36 /** Raw LZ77 prefix dictionary. */
37 BROTLI_SHARED_DICTIONARY_RAW = 0,
38 /** Serialized shared dictionary.
39 *
40 * DO NOT USE: methods accepting this value will fail.
41 */
42 BROTLI_SHARED_DICTIONARY_SERIALIZED = 1
43} BrotliSharedDictionaryType;
44
45/**
46 * Creates an instance of ::BrotliSharedDictionary.
47 *
48 * Fresh instance has default word dictionary and transforms
49 * and no LZ77 prefix dictionary.
50 *
51 * @p alloc_func and @p free_func @b MUST be both zero or both non-zero. In the
52 * case they are both zero, default memory allocators are used. @p opaque is
53 * passed to @p alloc_func and @p free_func when they are called. @p free_func
54 * has to return without doing anything when asked to free a NULL pointer.
55 *
56 * @param alloc_func custom memory allocation function
57 * @param free_func custom memory free function
58 * @param opaque custom memory manager handle
59 * @returns @c 0 if instance can not be allocated or initialized
60 * @returns pointer to initialized ::BrotliSharedDictionary otherwise
61 */
62BROTLI_COMMON_API BrotliSharedDictionary* BrotliSharedDictionaryCreateInstance(
63 brotli_alloc_func alloc_func, brotli_free_func free_func, void* opaque);
64
65/**
66 * Deinitializes and frees ::BrotliSharedDictionary instance.
67 *
68 * @param dict shared dictionary instance to be cleaned up and deallocated
69 */
70BROTLI_COMMON_API void BrotliSharedDictionaryDestroyInstance(
71 BrotliSharedDictionary* dict);
72
73/**
74 * Attaches dictionary to a given instance of ::BrotliSharedDictionary.
75 *
76 * Dictionary to be attached is represented in a serialized format as a region
77 * of memory.
78 *
79 * Provided data it partially referenced by a resulting (compound) dictionary,
80 * and should be kept untouched, while at least one compound dictionary uses it.
81 * This way memory overhead is kept minimal by the cost of additional resource
82 * management.
83 *
84 * @param dict dictionary to extend
85 * @param type type of dictionary to attach
86 * @param data_size size of @p data
87 * @param data serialized dictionary of type @p type, with at least @p data_size
88 * addressable bytes
89 * @returns ::BROTLI_TRUE if provided dictionary is successfully attached
90 * @returns ::BROTLI_FALSE otherwise
91 */
92BROTLI_COMMON_API BROTLI_BOOL BrotliSharedDictionaryAttach(
93 BrotliSharedDictionary* dict, BrotliSharedDictionaryType type,
94 size_t data_size, const uint8_t data[BROTLI_ARRAY_PARAM(data_size)]);
95
96#if defined(__cplusplus) || defined(c_plusplus)
97} /* extern "C" */
98#endif
99
100#endif /* BROTLI_COMMON_SHARED_DICTIONARY_H_ */
101

source code of include/brotli/shared_dictionary.h