1 /* 2 3 Copyright (c) 2011, 2012, Simon Howard 4 5 Permission to use, copy, modify, and/or distribute this software 6 for any purpose with or without fee is hereby granted, provided 7 that the above copyright notice and this permission notice appear 8 in all copies. 9 10 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL 11 WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED 12 WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE 13 AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR 14 CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM 15 LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, 16 NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN 17 CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 18 19 */ 20 21 #ifndef LHASA_PUBLIC_LHA_DECODER_H 22 #define LHASA_PUBLIC_LHA_DECODER_H 23 24 #include <stdlib.h> 25 #include <inttypes.h> 26 27 #ifdef __cplusplus 28 extern "C" { 29 #endif 30 31 /** 32 * @file lha_decoder.h 33 * 34 * @brief Raw LHA data decoder. 35 * 36 * This file defines the interface to the decompression code, which can 37 * be used to decompress the raw compressed data from an LZH file. 38 * 39 * Implementations of the various compression algorithms used in LZH 40 * archives are provided - these are represented by the 41 * @ref LHADecoderType structure, and can be retrieved using the 42 * @ref lha_decoder_for_name function. One of these can then be passed to 43 * the @ref lha_decoder_new function to create a @ref LHADecoder structure 44 * and decompress the data. 45 */ 46 47 /** 48 * Opaque type representing a type of decoder. 49 * 50 * This is an implementation of the decompression code for one of the 51 * algorithms used in LZH archive files. Pointers to these structures are 52 * retrieved by using the @ref lha_decoder_for_name function. 53 */ 54 55 typedef struct _LHADecoderType LHADecoderType; 56 57 /** 58 * Opaque type representing an instance of a decoder. 59 * 60 * This is a decoder structure being used to decompress a stream of 61 * compressed data. Instantiated using the @ref lha_decoder_new 62 * function and freed using the @ref lha_decoder_free function. 63 */ 64 65 typedef struct _LHADecoder LHADecoder; 66 67 /** 68 * Callback function invoked when a decoder wants to read more compressed 69 * data. 70 * 71 * @param buf Pointer to the buffer in which to store the data. 72 * @param buf_len Size of the buffer, in bytes. 73 * @param user_data Extra pointer to pass to the decoder. 74 * @return Number of bytes read. 75 */ 76 77 typedef size_t (*LHADecoderCallback)(void *buf, size_t buf_len, 78 void *user_data); 79 80 /** 81 * Callback function used for monitoring decode progress. 82 * The callback is invoked for every block processed (block size depends on 83 * decode algorithm). 84 * 85 * @param num_blocks Number of blocks processed so far. 86 * @param total_blocks Total number of blocks to process. 87 * @paaram callback_data Extra user-specified data passed to the callback. 88 */ 89 90 typedef void (*LHADecoderProgressCallback)(unsigned int num_blocks, 91 unsigned int total_blocks, 92 void *callback_data); 93 94 /** 95 * Get the decoder type for the specified name. 96 * 97 * @param name String identifying the decoder type, for 98 * example, "-lh1-". 99 * @return Pointer to the decoder type, or NULL if there 100 * is no decoder type for the specified name. 101 */ 102 103 LHADecoderType *lha_decoder_for_name(char *name); 104 105 /** 106 * Allocate a new decoder for the specified type. 107 * 108 * @param dtype The decoder type. 109 * @param callback Callback function for the decoder to call to read 110 * more compressed data. 111 * @param callback_data Extra data to pass to the callback function. 112 * @param stream_length Length of the uncompressed data, in bytes. When 113 * this point is reached, decompression will stop. 114 * @return Pointer to the new decoder, or NULL for failure. 115 */ 116 117 LHADecoder *lha_decoder_new(LHADecoderType *dtype, 118 LHADecoderCallback callback, 119 void *callback_data, 120 size_t stream_length); 121 122 /** 123 * Free a decoder. 124 * 125 * @param decoder The decoder to free. 126 */ 127 128 void lha_decoder_free(LHADecoder *decoder); 129 130 /** 131 * Set a callback function to monitor decode progress. 132 * 133 * @param decoder The decoder. 134 * @param callback Callback function to monitor decode progress. 135 * @param callback_data Extra data to pass to the decoder. 136 */ 137 138 void lha_decoder_monitor(LHADecoder *decoder, 139 LHADecoderProgressCallback callback, 140 void *callback_data); 141 142 /** 143 * Decode (decompress) more data. 144 * 145 * @param decoder The decoder. 146 * @param buf Pointer to buffer to store decompressed data. 147 * @param buf_len Size of the buffer, in bytes. 148 * @return Number of bytes decompressed. 149 */ 150 151 size_t lha_decoder_read(LHADecoder *decoder, uint8_t *buf, size_t buf_len); 152 153 /** 154 * Get the current 16-bit CRC of the decompressed data. 155 * 156 * This should be called at the end of decompression to check that the 157 * data was extracted correctly, and the value compared against the CRC 158 * from the file header. 159 * 160 * @param decoder The decoder. 161 * @return 16-bit CRC of the data decoded so far. 162 */ 163 164 uint16_t lha_decoder_get_crc(LHADecoder *decoder); 165 166 /** 167 * Get the count of the number of bytes decoded. 168 * 169 * This should be called at the end of decompression, and the value 170 * compared against the file length from the file header. 171 * 172 * @param decoder The decoder. 173 * @return The number of decoded bytes. 174 */ 175 176 size_t lha_decoder_get_length(LHADecoder *decoder); 177 178 #ifdef __cplusplus 179 } 180 #endif 181 182 #endif /* #ifndef LHASA_LHA_DECODER_H */ 183 184