diff --git a/doomsday/engine/portable/include/zipfile.h b/doomsday/engine/portable/include/zipfile.h index 732d4bb976..225f7fc38e 100644 --- a/doomsday/engine/portable/include/zipfile.h +++ b/doomsday/engine/portable/include/zipfile.h @@ -1,60 +1,108 @@ -/**\file zipfile.h - *\section License - * License: GPL - * Online License Link: http://www.gnu.org/licenses/gpl.html - * - *\author Copyright © 2003-2012 Jaakko Keränen - *\author Copyright © 2005-2012 Daniel Swanson - * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this program; if not, write to the Free Software - * Foundation, Inc., 51 Franklin St, Fifth Floor, - * Boston, MA 02110-1301 USA +/** + * @file zipfile.h + * Specialization of AbstractFile for working with Zip archives. + * + * @note Presently only the zlib method (Deflate) of compression is supported. + * + * @ingroup fs + * + * @see abstractfile.h, AbstractFile + * + * @authors Copyright © 2003-2012 Jaakko Keränen + * @authors Copyright © 2005-2012 Daniel Swanson + * + * @par License + * GPL: http://www.gnu.org/licenses/gpl.html + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by the + * Free Software Foundation; either version 2 of the License, or (at your + * option) any later version. This program is distributed in the hope that it + * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty + * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General + * Public License for more details. You should have received a copy of the GNU + * General Public License along with this program; if not, write to the Free + * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA + * 02110-1301 USA */ #ifndef LIBDENG_FILESYS_ZIPFILE_H #define LIBDENG_FILESYS_ZIPFILE_H -#include "lumpinfo.h" #include "abstractfile.h" +#include "lumpinfo.h" +#include "lumpdirectory.h" -struct lumpdirectory_s; struct pathdirectorynode_s; +struct zipfile_s; /** - * ZipFile. Runtime representation of Zip files. - * - * Uses zlib for decompression of "Deflated" files. - * - * @ingroup FS + * ZipFile instance. Constructed with ZipFile_New(). */ -struct zipfile_s; // The zipfile instance (opaque) typedef struct zipfile_s ZipFile; +/** + * Constructs a new zipfile. The zipfile has to be destroyed with ZipFile_Delete() + * after it is not needed any more. + * + * @param file Virtual file handle to the underlying file resource. + * @param path Virtual file system path to associate with the resultant zipfile. + * @param info File info descriptor for the resultant zipfile. A copy is made. + */ ZipFile* ZipFile_New(DFile* file, const char* path, const LumpInfo* info); + +/** + * Destroys the zipfile. + */ void ZipFile_Delete(ZipFile* zip); -int ZipFile_PublishLumpsToDirectory(ZipFile* zip, struct lumpdirectory_s* directory); +/** + * Publish lumps to the end of the specified @a directory and prune any duplicates + * (see LumpDirectory_PruneDuplicateRecords()). + * + * @param zip ZipFile instance. + * @param directory Directory to publish to. + * @return Number of lumps published to the directory (not necessarily the same as + * ZipFile_LumpCount()). + */ +int ZipFile_PublishLumpsToDirectory(ZipFile* zip, LumpDirectory* directory); +/** + * Lookup a directory node for a lump contained by this zipfile. + * + * @param zip ZipFile instance. + * @param lumpIdx Logical index for the lump within the zipfile's internal directory. + * @return Found directory node else @c NULL if @a lumpIdx is not valid. + */ struct pathdirectorynode_s* ZipFile_LumpDirectoryNode(ZipFile* zip, int lumpIdx); -ddstring_t* ZipFile_ComposeLumpPath(ZipFile* zip, int lumpIdx, char delimiter); - +/** + * Lookup a lump info descriptor for a lump contained by this zipfile. + * + * @param zip ZipFile instance. + * @param lumpIdx Logical index for the lump within the zipfile's internal directory. + * @return Found lump info else @c NULL if @a lumpIdx is not valid. + */ const LumpInfo* ZipFile_LumpInfo(ZipFile* zip, int lumpIdx); +/** + * Compose the full virtual file system path to a lump contained by this zipfile. + * + * @note Always runs a valid string object. In the case of an invalid @a lumpIdx + * a zero-length string is returned. + * + * @param zip ZipFile instance. + * @param lumpIdx Logical index for the lump. + * @param delimiter Delimit directory separators using this character (default: '/'). + * @return String containing the full path. Has to be destroyed with Str_Delete() + * once it is no longer needed. + */ +ddstring_t* ZipFile_ComposeLumpPath(ZipFile* zip, int lumpIdx, char delimiter); + /** * Read the data associated with the specified lump index into @a buffer. * + * @param zip ZipFile instance. * @param lumpIdx Lump index associated with the data being read. * @param buffer Buffer to read into. Must be at least W_LumpLength() bytes. * @param tryCache @c true = try the lump cache first. @@ -66,6 +114,7 @@ size_t ZipFile_ReadLump(ZipFile* zip, int lumpIdx, uint8_t* buffer); /** * Read a subsection of the data associated with the specified lump index into @a buffer. * + * @param zip ZipFile instance. * @param lumpIdx Lump index associated with the data being read. * @param buffer Buffer to read into. Must be at least W_LumpLength() bytes. * @param startOffset Offset from the beginning of the lump to start reading. @@ -81,6 +130,7 @@ size_t ZipFile_ReadLumpSection(ZipFile* zip, int lumpIdx, uint8_t* buffer, /** * Read the data associated with the specified lump index into the cache. * + * @param zip ZipFile instance. * @param lumpIdx Lump index associated with the data being read. * @param tag Zone purge level/cache tag to use. * @return Ptr to the cached copy of the associated data. @@ -90,6 +140,7 @@ const uint8_t* ZipFile_CacheLump(ZipFile* zip, int lumpIdx, int tag); /** * Change the Zone purge level/cache tag associated with a cached data lump. * + * @param zip ZipFile instance. * @param lumpIdx Lump index associated with the cached data being changed. * @param tag Zone purge level/cache tag to use. */ @@ -109,10 +160,11 @@ int ZipFile_LumpCount(ZipFile* zip); */ /** - * Does the specified file appear to be in Zip format. + * Does the specified file appear to be in a format recognised by ZipFile? + * * @param file Stream file handle/wrapper to the file being interpreted. * @return @c true iff this is a file that can be represented using ZipFile. */ boolean ZipFile_Recognise(DFile* file); -#endif +#endif // LIBDENG_FILESYS_ZIPFILE_H