1 /** 2 * @file libcomprex/archive.h Archive API 3 * 4 * $Id: archive.h,v 1.22 2003/01/02 02:49:38 chipx86 Exp $ 5 * 6 * @Copyright (C) 2001-2003 The GNUpdate Project. 7 * 8 * This library is free software; you can redistribute it and/or 9 * modify it under the terms of the GNU Library General Public 10 * License as published by the Free Software Foundation; either 11 * version 2 of the License, or (at your option) any later version. 12 * 13 * This library is distributed in the hope that it will be useful, 14 * but WITHOUT ANY WARRANTY; without even the implied warranty of 15 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 16 * Library General Public License for more details. 17 * 18 * You should have received a copy of the GNU Library General Public 19 * License along with this library; if not, write to the 20 * Free Software Foundation, Inc., 59 Temple Place - Suite 330, 21 * Boston, MA 02111-1307, USA. 22 */ 23 #ifndef _LIBCOMPREX_ARCHIVE_H_ 24 #define _LIBCOMPREX_ARCHIVE_H_ 25 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 typedef struct _CxArchive CxArchive; /**< An archive. */ 31 32 #include <libcomprex/directory.h> 33 #include <libcomprex/file.h> 34 #include <libcomprex/fp.h> 35 #include <libcomprex/module.h> 36 #include <libcomprex/types.h> 37 38 /** 39 * @struct _CxArchive archive.h libcomprex/archive.h 40 * 41 * A representation of an archive of files. 42 */ 43 struct _CxArchive 44 { 45 CxModule *module; /**< The module. */ 46 CxArchiveType type; /**< The archive type. */ 47 CxAccessMode accessMode; /**< The file access mode. */ 48 49 CxArchive *parent; /**< The parent archive. */ 50 CxFP *fp; /**< The associated file pointer. */ 51 52 char *name; /**< The base filename. */ 53 54 /** 55 * The full path to the archive. This may include a non-physical path 56 * (FTP site, archive, etc.) in the path. 57 */ 58 char *path; 59 60 /** 61 * The full physical path to the archive. If the file is non-local, 62 * this will be a temporary filename. 63 */ 64 char *physPath; 65 66 /** Non-zero if the archive is stored locally. */ 67 char isLocal; 68 69 unsigned int fileSize; /**< The size of the archive file. */ 70 unsigned int archiveSize; /**< The total size of all contents. */ 71 72 size_t fileCount; /**< Total number of files in the archive. */ 73 74 CxDirectory *root; /**< The root directory in the archive. */ 75 76 void *moduleData; /**< Module-specific data. */ 77 78 unsigned int refCount; /**< The reference count. */ 79 80 /** 81 * The archive specific callback that will be called upon the extraction 82 * of each file within the archive 83 */ 84 void (*ex_callback) (CxArchive *, CxFile *, size_t onFile, size_t fileCount); 85 }; 86 87 88 /**************************************************************************/ 89 /** @name Structure (De)allocation Functions */ 90 /**************************************************************************/ 91 /*@{*/ 92 93 /** 94 * Creates a new CxArchive structure. 95 * 96 * @return A new, empty CxArchive structure. 97 * 98 * @see cxDestroyArchive() 99 */ 100 CxArchive *cxNewArchive(void); 101 102 /** 103 * Destroys a CxArchive structure. 104 * 105 * @param archive The structure to destroy. 106 * 107 * @see cxNewArchive() 108 */ 109 void cxDestroyArchive(CxArchive *archive); 110 111 /*@}*/ 112 113 /**************************************************************************/ 114 /** @name Attribute Modification Functions */ 115 /**************************************************************************/ 116 /*@{*/ 117 118 /** 119 * Sets the archive's asssociated module. 120 * 121 * This should really only be used by libcomprex. 122 * 123 * @param archive The archive. 124 * @param module The associated module. 125 * 126 * @see cxGetArchiveModule() 127 */ 128 void cxSetArchiveModule(CxArchive *archive, CxModule *module); 129 130 /** 131 * Sets the archive type. 132 * 133 * @param archive The archive. 134 * @param type The archive type. 135 * 136 * @see cxGetArchiveType() 137 */ 138 void cxSetArchiveType(CxArchive *archive, CxArchiveType type); 139 140 /** 141 * Sets the archive's file access mode. 142 * 143 * @param archive The archive. 144 * @param mode The access mode. 145 * 146 * @see cxGetArchiveAccessMode() 147 */ 148 void cxSetArchiveAccessMode(CxArchive *archive, CxAccessMode mode); 149 150 /** 151 * Sets the archive's physical filename. 152 * 153 * @param archive The archive. 154 * @param filename The physical filename. 155 * 156 * @see cxGetArchiveFileName() 157 */ 158 void cxSetArchiveFileName(CxArchive *archive, const char *filename); 159 160 /** 161 * Sets the full path to the archive. 162 * 163 * This may include such non-physical elements as FTP sites, archives, 164 * etc. in the path. 165 * 166 * @param archive The archive. 167 * @param path The path to the archive. 168 * 169 * @see cxSetArchivePath() 170 * @see cxGetArchivePhysicalPath() 171 * @see cxSetArchivePhysicalPath() 172 */ 173 void cxSetArchivePath(CxArchive *archive, const char *path); 174 175 /** 176 * Sets the full physical path to the archive. 177 * 178 * If the archive is non-local, this should be a temporary file. 179 * 180 * @param archive The archive. 181 * @param path The physical path to the file. 182 * 183 * @see cxGetArchivePhysicalPath() 184 * @see cxGetArchivePath() 185 * @see cxSetArchivePath() 186 */ 187 void cxSetArchivePhysicalPath(CxArchive *archive, const char *path); 188 189 /** 190 * Sets the archive's physical file size. 191 * 192 * @param archive The archive. 193 * @param fileSize The physical size of the archive. 194 * 195 * @see cxGetArchiveFileSize() 196 */ 197 void cxSetArchiveFileSize(CxArchive *archive, unsigned int fileSize); 198 199 /** 200 * Sets the total size of the archive's contents. 201 * 202 * @param archive The archive. 203 * @param archiveSize The total size of the archive's contents. 204 * 205 * @see cxGetArchiveSize() 206 */ 207 void cxSetArchiveSize(CxArchive *archive, unsigned int archiveSize); 208 209 /** 210 * Sets whether or not the archive is stored locally. 211 * 212 * If the archive is located online, or within another archive, this 213 * should be 0. Otherwise, this should be 1. 214 * 215 * @param archive The archive. 216 * @param isLocal 1 if the archive is stored locally; 0 otherwise. 217 * 218 * @see cxIsArchiveLocal() 219 */ 220 void cxSetArchiveLocal(CxArchive *archive, char isLocal); 221 222 /** 223 * Sets the archive specific extraction callback. 224 * 225 * @param archive The archive. 226 * @param callback The callback function. 227 */ 228 void cxSetArchiveExtractCallback(CxArchive *archive, 229 void (*callback)(CxArchive *, CxFile *, 230 size_t, size_t)); 231 232 /*@}*/ 233 234 235 /**************************************************************************/ 236 /** @name Attribute Retrieval Functions */ 237 /**************************************************************************/ 238 /*@{*/ 239 240 /** 241 * Returns the archive's associated module. 242 * 243 * @param archive The archive. 244 * 245 * @return The archive's associated module. 246 * 247 * @see cxSetArchiveModule() 248 */ 249 CxModule *cxGetArchiveModule(CxArchive *archive); 250 251 /** 252 * Returns the archive type. 253 * 254 * @param archive The archive. 255 * 256 * @return The archive's type. 257 * 258 * @see cxSetArchiveType() 259 */ 260 CxArchiveType cxGetArchiveType(CxArchive *archive); 261 262 /** 263 * Returns the archive's file access mode. 264 * 265 * @param archive The archive. 266 * 267 * @return The archive's file access mode. 268 * 269 * @see cxSetArchiveAccessMode() 270 */ 271 CxAccessMode cxGetArchiveAccessMode(CxArchive *archive); 272 273 /** 274 * Returns the archive's physical filename. 275 * 276 * @param archive The archive. 277 * 278 * @return The archive's physical filename. 279 * 280 * @see cxSetArchiveFileName() 281 */ 282 const char *cxGetArchiveFileName(CxArchive *archive); 283 284 /** 285 * Returns the full path to the specified archive. 286 * 287 * This may include such non-physical elements as FTP sites, archives, 288 * etc. in the path. 289 * 290 * @param archive The archive. 291 * 292 * @return The path to the archive. 293 * 294 * @see cxSetArchivePath() 295 * @see cxGetArchivePhysicalPath() 296 * @see cxSetArchivePhysicalPath() 297 */ 298 const char *cxGetArchivePath(CxArchive *archive); 299 300 /** 301 * Returns the full physical path to the file. 302 * 303 * If the archive is non-local, this will be a temporary file. 304 * 305 * @param archive The archive. 306 * 307 * @return The physical path to the file. 308 * 309 * @see cxSetArchivePhysicalPath() 310 * @see cxGetArchivePath() 311 * @see cxSetArchivePath() 312 */ 313 const char *cxGetArchivePhysicalPath(CxArchive *archive); 314 315 /** 316 * Returns the total number of files in the archive. 317 * 318 * @param archive The archive. 319 * 320 * @return The total number of files in the archive. 321 */ 322 size_t cxGetArchiveFileCount(CxArchive *archive); 323 324 /** 325 * Returns the archive's physical file size. 326 * 327 * @param archive The archive. 328 * 329 * @return The archive's physical file size. 330 * 331 * @see cxSetArchiveFileSize() 332 */ 333 unsigned int cxGetArchiveFileSize(CxArchive *archive); 334 335 /** 336 * Returns the total size of the archive's contents. 337 * 338 * @param archive The archive. 339 * 340 * @return The total size of the archive's contents. 341 * 342 * @see cxSetArchiveSize() 343 */ 344 unsigned int cxGetArchiveSize(CxArchive *archive); 345 346 /** 347 * Returns whether or not the archive is stored locally. 348 * 349 * If the archive is located online, or within another archive, 350 * this will be 0. Otherwise, this will be 1. 351 * 352 * @param archive The archive. 353 * 354 * @return 1 if the archive is stored locally; 0 otherwise. 355 * 356 * @see cxSetArchiveLocal() 357 */ 358 char cxIsArchiveLocal(CxArchive *archive); 359 360 /** 361 * Returns the root directory in the archive. 362 * 363 * @param archive The archive. 364 * 365 * @return The archive's root directory. 366 */ 367 CxDirectory *cxGetArchiveRoot(CxArchive *archive); 368 369 /*@}*/ 370 371 #ifdef __cplusplus 372 } 373 #endif 374 375 #endif /* _LIBCOMPREX_ARCHIVE_H_ */ 376 377