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