include/brotli/shared_dictionary.h

0001 /* Copyright 2017 Google Inc. All Rights Reserved.
0002
0003    Distributed under MIT license.
0004    See file LICENSE for detail or copy at https://opensource.org/licenses/MIT
0005 */
0006
0007 /* (Opaque) Shared Dictionary definition and utilities. */
0008
0009 #ifndef BROTLI_COMMON_SHARED_DICTIONARY_H_
0010 #define BROTLI_COMMON_SHARED_DICTIONARY_H_
0011
0012 #include <brotli/port.h>
0013 #include <brotli/types.h>
0014
0015 #if defined(__cplusplus) || defined(c_plusplus)
0016 extern "C" {
0017 #endif
0018
0019 #define SHARED_BROTLI_MIN_DICTIONARY_WORD_LENGTH 4
0020 #define SHARED_BROTLI_MAX_DICTIONARY_WORD_LENGTH 31
0021 #define SHARED_BROTLI_NUM_DICTIONARY_CONTEXTS 64
0022 #define SHARED_BROTLI_MAX_COMPOUND_DICTS 15
0023
0024 /**
0025  * Opaque structure that holds shared dictionary data.
0026  *
0027  * Allocated and initialized with ::BrotliSharedDictionaryCreateInstance.
0028  * Cleaned up and deallocated with ::BrotliSharedDictionaryDestroyInstance.
0029  */
0030 typedef struct BrotliSharedDictionaryStruct BrotliSharedDictionary;
0031
0032 /**
0033  * Input data type for ::BrotliSharedDictionaryAttach.
0034  */
0035 typedef enum BrotliSharedDictionaryType {
0036   /** Raw LZ77 prefix dictionary. */
0037   BROTLI_SHARED_DICTIONARY_RAW = 0,
0038   /** Serialized shared dictionary.
0039    *
0040    * DO NOT USE: methods accepting this value will fail.
0041    */
0042   BROTLI_SHARED_DICTIONARY_SERIALIZED = 1
0043 } BrotliSharedDictionaryType;
0044
0045 /**
0046  * Creates an instance of ::BrotliSharedDictionary.
0047  *
0048  * Fresh instance has default word dictionary and transforms
0049  * and no LZ77 prefix dictionary.
0050  *
0051  * @p alloc_func and @p free_func @b MUST be both zero or both non-zero. In the
0052  * case they are both zero, default memory allocators are used. @p opaque is
0053  * passed to @p alloc_func and @p free_func when they are called. @p free_func
0054  * has to return without doing anything when asked to free a NULL pointer.
0055  *
0056  * @param alloc_func custom memory allocation function
0057  * @param free_func custom memory free function
0058  * @param opaque custom memory manager handle
0059  * @returns @c 0 if instance can not be allocated or initialized
0060  * @returns pointer to initialized ::BrotliSharedDictionary otherwise
0061  */
0062 BROTLI_COMMON_API BrotliSharedDictionary* BrotliSharedDictionaryCreateInstance(
0063     brotli_alloc_func alloc_func, brotli_free_func free_func, void* opaque);
0064
0065 /**
0066  * Deinitializes and frees ::BrotliSharedDictionary instance.
0067  *
0068  * @param dict shared dictionary instance to be cleaned up and deallocated
0069  */
0070 BROTLI_COMMON_API void BrotliSharedDictionaryDestroyInstance(
0071     BrotliSharedDictionary* dict);
0072
0073 /**
0074  * Attaches dictionary to a given instance of ::BrotliSharedDictionary.
0075  *
0076  * Dictionary to be attached is represented in a serialized format as a region
0077  * of memory.
0078  *
0079  * Provided data it partially referenced by a resulting (compound) dictionary,
0080  * and should be kept untouched, while at least one compound dictionary uses it.
0081  * This way memory overhead is kept minimal by the cost of additional resource
0082  * management.
0083  *
0084  * @param dict dictionary to extend
0085  * @param type type of dictionary to attach
0086  * @param data_size size of @p data
0087  * @param data serialized dictionary of type @p type, with at least @p data_size
0088  *        addressable bytes
0089  * @returns ::BROTLI_TRUE if provided dictionary is successfully attached
0090  * @returns ::BROTLI_FALSE otherwise
0091  */
0092 BROTLI_COMMON_API BROTLI_BOOL BrotliSharedDictionaryAttach(
0093     BrotliSharedDictionary* dict, BrotliSharedDictionaryType type,
0094     size_t data_size, const uint8_t data[BROTLI_ARRAY_PARAM(data_size)]);
0095
0096 #if defined(__cplusplus) || defined(c_plusplus)
0097 }  /* extern "C" */
0098 #endif
0099
0100 #endif  /* BROTLI_COMMON_SHARED_DICTIONARY_H_ */