4
#include "zipios-config.h"
9
#include "fcollexceptions.h"
10
#include "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 BaseExport FileCollection {
23
/** FileCollection constructor. */
24
explicit FileCollection()
29
/** Copy constructor. */
30
FileCollection( const FileCollection &src ) ;
32
/** Copy assignment operator. */
33
const FileCollection &operator= ( const FileCollection &src ) ;
35
/** Closes the FileCollection. */
36
virtual void close() = 0 ;
42
/** \anchor fcoll_entries_anchor
43
Returns a vector of const pointers to the entries in the
45
@return a ConstEntries
46
containing the entries of the FileCollection.
47
@throw InvalidStateException Thrown if the collection is invalid. */
48
virtual ConstEntries entries() const ;
51
/** \anchor fcoll_getentry_anchor
52
Returns a ConstEntryPointer to a FileEntry object for the entry
53
with the specified name. To ignore the path part of the filename in search of a
54
match, specify FileCollection::IGNORE as the second argument.
55
@param name A string containing the name of the entry to get.
56
@param matchpath Speficy MATCH, if the path should match as well,
57
specify IGNORE, if the path should be ignored.
58
@return A ConstEntryPointer to the found entry. The returned pointer
59
equals zero if no entry is found.
60
@throw InvalidStateException Thrown if the collection is invalid. */
61
virtual ConstEntryPointer getEntry( const string &name,
62
MatchPath matchpath = MATCH ) const ;
63
/** \anchor fcoll_getinputstream
64
Returns a pointer to an opened istream for the specified
65
FileEntry. It is the callers responsibility to delete the stream
66
when he is done with it. Returns 0, if there is no such
67
FileEntry in the FileCollection.
68
@param entry A ConstEntryPointer to the FileEntry to get an istream to.
69
@return an open istream for the specified entry. The istream is allocated on
70
heap and it is the users responsibility to delete it when he is done with it.
71
@throw InvalidStateException Thrown if the collection is invalid. */
72
virtual istream *getInputStream( const ConstEntryPointer &entry ) = 0 ;
73
/** Returns a pointer to an opened istream for the specified
74
entry name. It is the callers responsibility to delete the stream
75
when he is done with it. Returns 0, if there is no entry with the specified
76
name in the FileCollection.
77
@param matchpath Speficy MATCH, if the path should match as well,
78
specify IGNORE, if the path should be ignored.
79
@return an open istream for the specified entry. The istream is allocated on
80
heap and it is the users responsibility to delete it when he is done with it.
81
@throw InvalidStateException Thrown if the collection is invalid. */
82
virtual istream *getInputStream( const string &entry_name,
83
MatchPath matchpath = MATCH ) = 0 ;
84
/** Returns the name of the FileCollection.
85
@return the name of the FileCollection.
86
@throw InvalidStateException Thrown if the collection is invalid. */
87
virtual string getName() const ;
88
/** Returns the number of entries in the FileCollection.
89
@return the number of entries in the FileCollection.
90
@throw InvalidStateException Thrown if the collection is invalid. */
91
virtual int size() const ;
93
/** The member function returns true if the collection is valid.
94
@return true if the collection is valid.
96
bool isValid() const { return _valid ; }
98
/** Create a heap allocated clone of the object this method is called for. The
99
caller is responsible for deallocating the clone when he is done with it.
100
@return A heap allocated copy of the object this method is called for.
102
virtual FileCollection *clone() const = 0 ;
105
/** FileCollection destructor. */
106
virtual ~FileCollection () ;
118
inline ostream & operator<< (ostream &os, const FileCollection& collection) {
119
os << "collection '" << collection.getName() << "' {" ;
120
ConstEntries entries = collection.entries();
121
ConstEntries::const_iterator it;
123
for (it=entries.begin(); it != entries.end(); ++it) {
127
os << (*it)->getName();
141
\image html zipios++.jpg
142
\image latex zipios++.eps width=10cm
144
\section intro Introduction
146
Zipios++ is a java.util.zip-like C++ library for reading and
147
writing Zip files. Access to individual entries is provided through
148
standard C++ iostreams. A simple read-only virtual file system that
149
mounts regular directories and zip files is also provided.
151
The source code is released under the <A
152
HREF="http://www.gnu.org/copyleft/lesser.html">GNU Lesser General Public
155
\section status Status
157
Spanned archives are not supported, and support is not planned.
160
The library has been tested and appears to be working with
162
<LI><A HREF="http://www.freebsd.org/ports/archivers.html#zipios++-0.1.5">FreeBSD stable and current / gcc 2.95.3</A></LI>
163
<LI>Red Hat Linux release 7.0 / gcc 2.96</LI>
164
<LI>Red Hat Linux release 6.2 (Zoot) / egcs-2.91.66</LI>
165
<LI>Linux Mandrake release 7.0 (Air) / gcc 2.95.2</LI>
166
<LI>SGI IRIX64 6.5 / gcc 2.95.2</LI>
167
<LI>SGI IRIX64 6.5 / MIPSpro Compilers: Version 7.30</LI>
170
If you are aware of any other platforms that Zipios++ works on,
171
please let me know (thomass@deltadata.dk).
173
\section documentation Documentation
174
This web page is the front page to the library documentation which
175
is generated from the source files using <A
176
HREF="http://www.stack.nl/~dimitri/doxygen/index.html">Doxygen</A>. Use
177
the links at the top of the page to browse the API
178
documentation. The documentation is also available in
179
a printer-friendly format <A HREF="refman.pdf">[pdf]</A>.
181
\subsection zipfiles Zip file access
182
The two most important classes are \ref zipfile_anchor "ZipFile" and
183
\ref ZipInputStream_anchor "ZipInputStream". ZipInputStream is an istream
184
for reading zipfiles. It can be instantiated directly, without the
185
use of ZipFile. A new ZipInputStream reads from the first entry, and
186
the user can skip to the next entry by calling
187
\ref ZipInputStream_getnextentry_anchor "ZipInputStream::getNextEntry()".
189
ZipFile scans the central directory of a zipfile and provides an
190
interface to access that directory. The user may search for entries
191
with a particular filename using \ref fcoll_getentry_anchor "ZipFile::getEntry()",
192
or simply get the complete list of entries
193
with \ref fcoll_entries_anchor "ZipFile::entries()". To get an
194
istream (ZipInputStream) to a particular entry simply use
195
\ref fcoll_getinputstream "ZipFile::getInputStream()".
197
\ref example_zip_anchor "example_zip.cpp" demonstrates the central
198
elements of Zipios++.
200
A Zip file appended to another file, e.g. a binary program, with the program
201
\ref appendzip_anchor "appendzip", can be read with
202
\ref zipfile_openembeddedzipfile "ZipFile::openEmbeddedZipFile()".
204
\subsection filecollections FileCollections
206
A ZipFile is actually just a special kind of
207
\ref fcoll_anchor "FileCollection" that
208
obtains its entries from a .zip Zip archive. Zipios++ also implements
209
a \ref dircol_anchor "DirectoryCollection" that obtains its entries
210
from a specified directory, and a \ref collcoll_anchor "CollectionCollection"
211
that obtains its entries from
212
other collections. Using a single CollectionCollection any number of
213
other FileCollections can be placed under its control and accessed
214
through the same single interface that is used to access a ZipFile or
215
a DirectoryCollection. A singleton (a unique global instance)
216
CollectionCollection can be obtained through
218
\ref collcoll_inst_anchor "CollectionCollection::inst()" ;
220
To save typing CollectionCollection has been typedef'ed to CColl. In
221
the initialization part of an application FileCollections can be
222
created, and placed under CColll::inst()'s control using
224
\ref collcoll_addcoll_anchor "CColl::inst().addCollection()"
226
and later an istream can be obtained using
228
\ref fcoll_getinputstream "CColl::inst().getInputStream()".
230
\section download Download
231
Go to Zipios++ project page on SourceForge for tar balls and ChangeLog.
232
<A HREF="http://sourceforge.net/project/?group_id=5418" >
233
http://sourceforge.net/project/?group_id=5418</A>
236
<A HREF="ftp://ftp.freesoftware.com/pub/infozip/zlib/zlib.html">zlib</A>.
237
The compression library that Zipios++ uses to perform the actual
240
<A HREF="http://java.sun.com/products/jdk/1.3/docs/api/index.html">
241
Java 2 Platform, Standard Edition, v 1.3 API Specification
242
</A>. Zipios++ is heavily inspired by the java.util.zip package.
245
HREF="http://www.geocities.com/SiliconValley/Lakes/2160/fformats/files/zip.txt">
247
</A>. A description of the zip file format.
250
Submit bug reports and patches to thomass@deltadata.dk
255
Project hosted by <A HREF="http://sourceforge.net">
256
<img src="http://sourceforge.net/sflogo.php?group_id=5418&type=1" >
258
Logo created with <A HREF="http://www.webgfx.ch/titlepic.htm">
259
<img src="webgfx.gif" >
265
Header file that defines FileCollection.
269
Zipios++ - a small C++ library that provides easy access to .zip files.
270
Copyright (C) 2000 Thomas S�ndergaard
272
This library is free software; you can redistribute it and/or
273
modify it under the terms of the GNU Lesser General Public
274
License as published by the Free Software Foundation; either
275
version 2 of the License, or (at your option) any later version.
277
This library is distributed in the hope that it will be useful,
278
but WITHOUT ANY WARRANTY; without even the implied warranty of
279
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
280
Lesser General Public License for more details.
282
You should have received a copy of the GNU Lesser General Public
283
License along with this library; if not, write to the Free Software
284
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA