src/zipios/zipios++/fcoll.h

   1 #ifndef fcoll_H
   2 #define fcoll_H
   3
   4 #include "zipios++/zipios-config.h"
   5
   6 #include <vector>
   7 #include <string>
   8
   9 #include "zipios++/fcollexceptions.h"
  10 #include "zipios++/fileentry.h"
  11
  12 namespace zipios {
  13
  14 using std::vector;
  15
  16 /** \anchor fcoll_anchor
  17     FileCollection is an abstract baseclass that represents a
  18     collection of files. The specializations of FileCollection
  19     represents different origins of file collections, such as
  20     directories, simple filename lists and compressed archives. */
  21 class FileCollection {
  22 public:
  23   /** FileCollection constructor. */
  24   explicit FileCollection()
  25     : _filename( "-"   ),
  26       _entries ( 0     ),
  27       _valid   ( false ) {}
  28
  29   /** Copy constructor. */
  30   inline FileCollection( const FileCollection &src ) ;
  31
  32   /** Copy assignment operator. */
  33   inline const FileCollection &operator= ( const FileCollection &src ) ;
  34
  35   /** Closes the FileCollection. */
  36   virtual void close() = 0 ;
  37
  38   /** \anchor fcoll_entries_anchor
  39       Returns a vector of const pointers to the entries in the
  40       FileCollection.
  41       @return a ConstEntries
  42       containing the entries of the FileCollection.
  43       @throw InvalidStateException Thrown if the collection is invalid. */
  44   virtual ConstEntries entries() const ;
  45
  46   enum MatchPath { IGNORE, MATCH } ;
  47
  48   /** \anchor fcoll_getentry_anchor
  49       Returns a ConstEntryPointer to a FileEntry object for the entry
  50       with the specified name. To ignore the path part of the filename in search of a
  51       match, specify FileCollection::IGNORE as the second argument.
  52       @param name A string containing the name of the entry to get.
  53       @param matchpath Speficy MATCH, if the path should match as well,
  54       specify IGNORE, if the path should be ignored.
  55       @return A ConstEntryPointer to the found entry. The returned pointer
  56       equals zero if no entry is found.
  57       @throw InvalidStateException Thrown if the collection is invalid. */
  58   virtual ConstEntryPointer getEntry( const string &name,
  59                                      MatchPath matchpath = MATCH ) const ;
  60   /** \anchor fcoll_getinputstream
  61       Returns a pointer to an opened istream for the specified
  62       FileEntry. It is the callers responsibility to delete the stream
  63       when he is done with it. Returns 0, if there is no such
  64       FileEntry in the FileCollection.
  65       @param entry A ConstEntryPointer to the FileEntry to get an istream to.
  66       @return an open istream for the specified entry. The istream is allocated on
  67       heap and it is the users responsibility to delete it when he is done with it.
  68       @throw InvalidStateException Thrown if the collection is invalid. */
  69   virtual istream *getInputStream( const ConstEntryPointer &entry ) = 0 ;
  70   /** Returns a pointer to an opened istream for the specified
  71       entry name. It is the callers responsibility to delete the stream
  72       when he is done with it. Returns 0, if there is no entry with the specified
  73       name in the FileCollection.
  74       @param matchpath Speficy MATCH, if the path should match as well,
  75       specify IGNORE, if the path should be ignored.
  76       @return an open istream for the specified entry. The istream is allocated on
  77       heap and it is the users responsibility to delete it when he is done with it.
  78       @throw InvalidStateException Thrown if the collection is invalid. */
  79   virtual istream *getInputStream( const string &entry_name,
  80                                      MatchPath matchpath = MATCH ) = 0 ;
  81   /** Returns the name of the FileCollection.
  82       @return the name of the FileCollection.
  83       @throw InvalidStateException Thrown if the collection is invalid. */
  84   virtual string getName() const ;
  85   /** Returns the number of entries in the FileCollection.
  86       @return the number of entries in the FileCollection.
  87       @throw InvalidStateException Thrown if the collection is invalid. */
  88   virtual int size() const ;
  89
  90   /** The member function returns true if the collection is valid.
  91       @return true if the collection is valid.
  92    */
  93   bool isValid() const { return _valid ; }
  94
  95   /** Create a heap allocated clone of the object this method is called for. The
  96       caller is responsible for deallocating the clone when he is done with it.
  97       @return A heap allocated copy of the object this method is called for.
  98   */
  99   virtual FileCollection *clone() const = 0 ;
 100
 101
 102   /** FileCollection destructor. */
 103   virtual ~FileCollection () ;
 104 protected:
 105   string _filename ;
 106   Entries _entries ;
 107   bool _valid ;
 108 };
 109
 110
 111 //
 112 // Inline methods
 113 //
 114
 115 FileCollection::FileCollection( const FileCollection &src )
 116   : _filename( src._filename ),
 117     _valid   ( src._valid    )
 118 {
 119   _entries.reserve( src._entries.size() ) ;
 120   Entries::const_iterator it ;
 121   for ( it = src._entries.begin() ; it != src._entries.end() ; ++it )
 122     _entries.push_back( (*it)->clone() ) ;
 123 }
 124
 125 const FileCollection &FileCollection::operator= ( const FileCollection &src ) {
 126   if ( this != &src ) {
 127     _filename = src._filename ;
 128     _valid    = src._valid    ;
 129     _entries.clear() ;
 130     _entries.reserve( src._entries.size() ) ;
 131
 132     Entries::const_iterator it ;
 133     for ( it = src._entries.begin() ; it != src._entries.end() ; ++it )
 134       _entries.push_back( (*it)->clone() ) ;
 135   }
 136   return *this ;
 137 }
 138
 139 inline ostream & operator<< (ostream &os, const FileCollection& collection) {
 140         os << "collection '" << collection.getName() << "' {" ;
 141         ConstEntries entries = collection.entries();
 142         ConstEntries::const_iterator it;
 143         bool isFirst=true;
 144         for (it=entries.begin(); it != entries.end(); ++it) {
 145                 if(! isFirst)
 146                         os << ", ";
 147                 isFirst = false;
 148                 os << (*it)->getName();
 149         }
 150         os << "}";
 151         return os;
 152 }
 153
 154
 155 } // namespace
 156
 157 #endif
 158
 159
 160 /**
 161    \mainpage Zipios++
 162
 163    \image html   zipios++.jpg
 164    \image latex  zipios++.eps width=10cm
 165
 166    \section intro Introduction
 167
 168    Zipios++ is a java.util.zip-like C++ library for reading and
 169    writing Zip files. Access to individual entries is provided through
 170    standard C++ iostreams. A simple read-only virtual file system that
 171    mounts regular directories and zip files is also provided.
 172
 173    The source code is released under the <A
 174    HREF="http://www.gnu.org/copyleft/lesser.html">GNU Lesser General Public
 175    License</A>.
 176
 177    \section status Status
 178
 179    Spanned archives are not supported, and support is not planned.
 180
 181
 182    The library has been tested and appears to be working with
 183    <UL>
 184    <LI><A HREF="http://www.freebsd.org/ports/archivers.html#zipios++-0.1.5">FreeBSD stable and current / gcc 2.95.3</A></LI>
 185    <LI>Red Hat Linux release 7.0  / gcc 2.96</LI>
 186    <LI>Red Hat Linux release 6.2 (Zoot) / egcs-2.91.66</LI>
 187    <LI>Linux Mandrake release 7.0 (Air) / gcc 2.95.2</LI>
 188    <LI>SGI IRIX64 6.5 / gcc 2.95.2</LI>
 189    <LI>SGI IRIX64 6.5 / MIPSpro Compilers: Version 7.30</LI>
 190    </UL>
 191
 192    If you are aware of any other platforms that Zipios++ works on,
 193    please let me know (thomass@deltadata.dk).
 194
 195    \section documentation Documentation
 196    This web page is the front page to the library documentation which
 197    is generated from the source files using <A
 198    HREF="http://www.stack.nl/~dimitri/doxygen/index.html">Doxygen</A>. Use
 199    the links at the top of the page to browse the API
 200    documentation. The documentation is also available in
 201    a printer-friendly format <A HREF="refman.pdf">[pdf]</A>.
 202
 203    \subsection zipfiles Zip file access
 204    The two most important classes are \ref zipfile_anchor "ZipFile" and
 205    \ref ZipInputStream_anchor "ZipInputStream". ZipInputStream is an istream
 206    for reading zipfiles. It can be instantiated directly, without the
 207    use of ZipFile. \ref ZipInputStream_getnextentry_anchor
 208    "ZipInputStream::getNextEntry()" positions the new ZipInputStream at the
 209    first entry. The following entry can be accessed by calling
 210    \ref ZipInputStream_getnextentry_anchor "ZipInputStream::getNextEntry()"
 211    again.
 212
 213    ZipFile scans the central directory of a zipfile and provides an
 214    interface to access that directory. The user may search for entries
 215    with a particular filename using \ref fcoll_getentry_anchor "ZipFile::getEntry()",
 216    or simply get the complete list of entries
 217    with \ref fcoll_entries_anchor "ZipFile::entries()". To get an
 218    istream (ZipInputStream) to a particular entry simply use
 219    \ref fcoll_getinputstream "ZipFile::getInputStream()".
 220
 221    \ref example_zip_anchor "example_zip.cpp" demonstrates the central
 222    elements of Zipios++.
 223
 224    A Zip file appended to another file, e.g. a binary program, with the program
 225    \ref appendzip_anchor "appendzip", can be read with
 226    \ref zipfile_openembeddedzipfile "ZipFile::openEmbeddedZipFile()".
 227
 228    \subsection filecollections FileCollections
 229
 230    A ZipFile is actually just a special kind of
 231    \ref fcoll_anchor "FileCollection" that
 232    obtains its entries from a .zip Zip archive. Zipios++ also implements
 233    a \ref dircol_anchor "DirectoryCollection" that obtains its entries
 234    from a specified directory, and a \ref collcoll_anchor "CollectionCollection"
 235    that obtains its entries from
 236    other collections. Using a single CollectionCollection any number of
 237    other FileCollections can be placed under its control and accessed
 238    through the same single interface that is used to access a ZipFile or
 239    a DirectoryCollection. A singleton (a unique global instance)
 240    CollectionCollection can be obtained through
 241
 242    \ref collcoll_inst_anchor "CollectionCollection::inst()" ;
 243
 244    To save typing CollectionCollection has been typedef'ed to CColl. In
 245    the initialization part of an application FileCollections can be
 246    created, and placed under CColll::inst()'s control using
 247
 248    \ref collcoll_addcoll_anchor "CColl::inst().addCollection()"
 249
 250    and later an istream can be obtained using
 251
 252    \ref fcoll_getinputstream "CColl::inst().getInputStream()".
 253
 254    \section download Download
 255    Go to Zipios++ project page on SourceForge for tar balls and ChangeLog.
 256    <A HREF="http://sourceforge.net/project/?group_id=5418" >
 257    http://sourceforge.net/project/?group_id=5418</A>
 258
 259    \section links Links
 260    <A HREF="ftp://ftp.freesoftware.com/pub/infozip/zlib/zlib.html">zlib</A>.
 261    The compression library that Zipios++ uses to perform the actual
 262    decompression.
 263
 264    <A HREF="http://java.sun.com/products/jdk/1.3/docs/api/index.html">
 265    Java 2 Platform, Standard Edition, v 1.3 API Specification
 266    </A>. Zipios++ is heavily inspired by the java.util.zip package.
 267
 268    <A
 269    HREF="http://www.geocities.com/SiliconValley/Lakes/2160/fformats/files/zip.txt">
 270    PKWARE zip format
 271    </A>. A description of the zip file format.
 272
 273    \section bugs Bugs
 274    Submit bug reports and patches to thomass@deltadata.dk
 275
 276
 277
 278    \htmlonly
 279    Project hosted by <A HREF="http://sourceforge.net">
 280    <img src="http://sourceforge.net/sflogo.php?group_id=5418&type=1" >
 281    </A><p>
 282    Logo created with <A HREF="http://www.webgfx.ch/titlepic.htm">
 283    <img src="webgfx.gif" >
 284    </A>
 285    \endhtmlonly */
 286
 287
 288 /** \file
 289     Header file that defines FileCollection.
 290 */
 291
 292 /*
 293   Zipios++ - a small C++ library that provides easy access to .zip files.
 294   Copyright (C) 2000  Thomas Søndergaard
 295
 296   This library is free software; you can redistribute it and/or
 297   modify it under the terms of the GNU Lesser General Public
 298   License as published by the Free Software Foundation; either
 299   version 2 of the License, or (at your option) any later version.
 300
 301   This library is distributed in the hope that it will be useful,
 302   but WITHOUT ANY WARRANTY; without even the implied warranty of
 303   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 304   Lesser General Public License for more details.
 305
 306   You should have received a copy of the GNU Lesser General Public
 307   License along with this library; if not, write to the Free Software
 308   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
 309 */