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_READER_H 22 #define LHASA_PUBLIC_LHA_READER_H 23 24 #include "lha_decoder.h" 25 #include "lha_input_stream.h" 26 #include "lha_file_header.h" 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /** 33 * @file lha_reader.h 34 * 35 * @brief LHA file reader. 36 * 37 * This file contains the interface functions for the @ref LHAReader 38 * structure, used to decode data from a compressed LZH file and 39 * extract compressed files. 40 */ 41 42 /** 43 * Opaque structure used to decode the contents of an LZH file. 44 */ 45 46 typedef struct _LHAReader LHAReader; 47 48 /** 49 * Policy for extracting directories. 50 * 51 * When extracting a directory, some of the metadata associated with 52 * it needs to be set after the contents of the directory have been 53 * extracted. This includes the modification time (which would 54 * otherwise be reset to the current time) and the permissions (which 55 * can affect the ability to extract files into the directory). 56 * To work around this problem there are several ways of handling 57 * directory extraction. 58 */ 59 60 typedef enum { 61 62 /** 63 * "Plain" policy. In this mode, the metadata is set at the 64 * same time that the directory is created. This is the 65 * simplest to comprehend, and the files returned from 66 * @ref lha_reader_next_file will match the files in the 67 * archive, but it is not recommended. 68 */ 69 70 LHA_READER_DIR_PLAIN, 71 72 /** 73 * "End of directory" policy. In this mode, if a directory 74 * is extracted, the directory name will be saved. Once the 75 * contents of the directory appear to have been extracted 76 * (ie. a file is found that is not within the directory), 77 * the directory will be returned again by 78 * @ref lha_reader_next_file. This time, when the directory 79 * is "extracted" (via @ref lha_reader_extract), the metadata 80 * will be set. 81 * 82 * This method uses less memory than 83 * @ref LHA_READER_DIR_END_OF_FILE, but there is the risk 84 * that a file will appear within the archive after the 85 * metadata has been set for the directory. However, this is 86 * not normally the case, as files and directories typically 87 * appear within an archive in order. GNU tar uses the same 88 * method to address this problem with tar files. 89 * 90 * This is the default policy. 91 */ 92 93 LHA_READER_DIR_END_OF_DIR, 94 95 /** 96 * "End of file" policy. In this mode, each directory that 97 * is extracted is recorded in a list. When the end of the 98 * archive is reached, these directories are returned again by 99 * @ref lha_reader_next_file. When the directories are 100 * "extracted" again (via @ref lha_reader_extract), the 101 * metadata is set. 102 * 103 * This avoids the problems that can potentially occur with 104 * @ref LHA_READER_DIR_END_OF_DIR, but uses more memory. 105 */ 106 107 LHA_READER_DIR_END_OF_FILE 108 109 } LHAReaderDirPolicy; 110 111 /** 112 * Create a new @ref LHAReader to read data from an @ref LHAInputStream. 113 * 114 * @param stream The input stream to read data from. 115 * @return Pointer to a new @ref LHAReader structure, 116 * or NULL for error. 117 */ 118 119 LHAReader *lha_reader_new(LHAInputStream *stream); 120 121 /** 122 * Free a @ref LHAReader structure. 123 * 124 * @param reader The @ref LHAReader structure. 125 */ 126 127 void lha_reader_free(LHAReader *reader); 128 129 /** 130 * Set the @ref LHAReaderDirPolicy used to extract directories. 131 * 132 * @param reader The @ref LHAReader structure. 133 * @param policy The policy to use for directories. 134 */ 135 136 void lha_reader_set_dir_policy(LHAReader *reader, 137 LHAReaderDirPolicy policy); 138 139 /** 140 * Read the header of the next archived file from the input stream. 141 * 142 * @param reader The @ref LHAReader structure. 143 * @return Pointer to an @ref LHAFileHeader structure, or NULL if 144 * an error occurred. This pointer is only valid until 145 * the next time that lha_reader_next_file is called. 146 */ 147 148 LHAFileHeader *lha_reader_next_file(LHAReader *reader); 149 150 /** 151 * Read some of the (decompresed) data for the current archived file, 152 * decompressing as appropriate. 153 * 154 * @param reader The @ref LHAReader structure. 155 * @param buf Pointer to a buffer in which to store the data. 156 * @param buf_len Size of the buffer, in bytes. 157 * @return Number of bytes stored in the buffer, or zero if 158 * there is no more data to decompress. 159 */ 160 161 size_t lha_reader_read(LHAReader *reader, void *buf, size_t buf_len); 162 163 /** 164 * Decompress the contents of the current archived file, and check 165 * that the checksum matches correctly. 166 * 167 * @param reader The @ref LHAReader structure. 168 * @param callback Callback function to invoke to monitor progress (or 169 * NULL if progress does not need to be monitored). 170 * @param callback_data Extra data to pass to the callback function. 171 * @return Non-zero if the checksum matches. 172 */ 173 174 int lha_reader_check(LHAReader *reader, 175 LHADecoderProgressCallback callback, 176 void *callback_data); 177 178 /** 179 * Extract the contents of the current archived file. 180 * 181 * @param reader The @ref LHAReader structure. 182 * @param filename Filename to extract the archived file to, or NULL 183 * to use the path and filename from the header. 184 * @param callback Callback function to invoke to monitor progress (or 185 * NULL if progress does not need to be monitored). 186 * @param callback_data Extra data to pass to the callback function. 187 * @return Non-zero for success, or zero for failure (including 188 * CRC error). 189 */ 190 191 int lha_reader_extract(LHAReader *reader, 192 char *filename, 193 LHADecoderProgressCallback callback, 194 void *callback_data); 195 196 /** 197 * Check if the current file (last returned by @ref lha_reader_next_file) 198 * was generated internally by the extract process. This occurs when a 199 * directory or symbolic link must be created as a two-stage process, with 200 * some of the extraction process deferred to later in the stream. 201 * 202 * These "fake" duplicates should usually be hidden in the user interface 203 * when a summary of extraction is presented. 204 * 205 * @param reader The @ref LHAReader structure. 206 * @return Non-zero if the current file is a "fake", or zero 207 * for a normal file. 208 */ 209 210 int lha_reader_current_is_fake(LHAReader *reader); 211 212 #ifdef __cplusplus 213 } 214 #endif 215 216 #endif /* #ifndef LHASA_PUBLIC_LHA_READER_H */ 217 218