4 #include "zipios++/zipios-config.h"
9 #include "zipios++/fcollexceptions.h"
10 #include "zipios++/fileentry.h"
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 {
23 /** FileCollection constructor. */
24 explicit FileCollection()
29 /** Copy constructor. */
30 inline FileCollection( const FileCollection &src ) ;
32 /** Copy assignment operator. */
33 inline const FileCollection &operator= ( const FileCollection &src ) ;
35 /** Closes the FileCollection. */
36 virtual void close() = 0 ;
38 /** \anchor fcoll_entries_anchor
39 Returns a vector of const pointers to the entries in the
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 ;
46 enum MatchPath { IGNORE, MATCH } ;
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 ;
90 /** The member function returns true if the collection is valid.
91 @return true if the collection is valid.
93 bool isValid() const { return _valid ; }
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.
99 virtual FileCollection *clone() const = 0 ;
102 /** FileCollection destructor. */
103 virtual ~FileCollection () ;
115 FileCollection::FileCollection( const FileCollection &src )
116 : _filename( src._filename ),
117 _valid ( src._valid )
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() ) ;
125 const FileCollection &FileCollection::operator= ( const FileCollection &src ) {
126 if ( this != &src ) {
127 _filename = src._filename ;
128 _valid = src._valid ;
130 _entries.reserve( src._entries.size() ) ;
132 Entries::const_iterator it ;
133 for ( it = src._entries.begin() ; it != src._entries.end() ; ++it )
134 _entries.push_back( (*it)->clone() ) ;
139 inline ostream & operator<< (ostream &os, const FileCollection& collection) {
140 os << "collection '" << collection.getName() << "' {" ;
141 ConstEntries entries = collection.entries();
142 ConstEntries::const_iterator it;
144 for (it=entries.begin(); it != entries.end(); ++it) {
148 os << (*it)->getName();
163 \image html zipios++.jpg
164 \image latex zipios++.eps width=10cm
166 \section intro Introduction
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.
173 The source code is released under the <A
174 HREF="http://www.gnu.org/copyleft/lesser.html">GNU Lesser General Public
177 \section status Status
179 Spanned archives are not supported, and support is not planned.
182 The library has been tested and appears to be working with
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>
192 If you are aware of any other platforms that Zipios++ works on,
193 please let me know (thomass@deltadata.dk).
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>.
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()"
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()".
221 \ref example_zip_anchor "example_zip.cpp" demonstrates the central
222 elements of Zipios++.
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()".
228 \subsection filecollections FileCollections
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
242 \ref collcoll_inst_anchor "CollectionCollection::inst()" ;
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
248 \ref collcoll_addcoll_anchor "CColl::inst().addCollection()"
250 and later an istream can be obtained using
252 \ref fcoll_getinputstream "CColl::inst().getInputStream()".
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>
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
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.
269 HREF="http://www.geocities.com/SiliconValley/Lakes/2160/fformats/files/zip.txt">
271 </A>. A description of the zip file format.
274 Submit bug reports and patches to thomass@deltadata.dk
279 Project hosted by <A HREF="http://sourceforge.net">
280 <img src="http://sourceforge.net/sflogo.php?group_id=5418&type=1" >
282 Logo created with <A HREF="http://www.webgfx.ch/titlepic.htm">
283 <img src="webgfx.gif" >
289 Header file that defines FileCollection.
293 Zipios++ - a small C++ library that provides easy access to .zip files.
294 Copyright (C) 2000 Thomas Søndergaard
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.
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.
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