zipios: Zipios

zipios  2.2.0
Zipios -- a small C++ library that provides easy access to .zip files.
Zipios
Introduction

Zipios is a java.util.zip-like C++ library for reading and writing Zip files (ZipFile). Access to individual entries is provided through a Zipios class (FileEntry) for the meta data of the and a standard C++ iostreams for the contents of the file.

A simple virtual file system that mounts regular directories and zip files is also provided (FileCollection).

The library is fully re-entrant. It is not otherwise thread safe.

The source code is released under the GNU Lesser General Public License.

Status

This was the status of version 1.x. At this point, 2.x has a brand new version out and we are waiting for good news about the current status. That being said, version 2.x comes a test suite which produces a 100% coverage of the library (except gzip which is not yet publicly available.)

Warning
There is a bug in the catch.hpp header file that generates a never ending loop (see https://github.com/philsquared/Catch/issues/271 for more information) when running the test suite under FreeBSD and an error occurs (although you should not have an error, if it happens, then the loop never ends.) I have noticed that problem with the following scenario, and it does not seem to be fixed yet (Apr 4, 2015):
  • "use Zipios to create zip archives with 1 or 3 files each"

Spanned archives are not supported, and support is not planned.

The library v1.x has been tested and appears to be working with:

  • FreeBSD stable and current / gcc 2.95.3
  • Red Hat Linux release 7.0 / gcc 2.96
  • Red Hat Linux release 6.2 (Zoot) / egcs-2.91.66
  • Linux Mandrake release 7.0 (Air) / gcc 2.95.2
  • SGI IRIX64 6.5 / gcc 2.95.2
  • SGI IRIX64 6.5 / MIPSpro Compilers: Version 7.30

The library v2.x has been compiled and appears to be working with:

  • Ubuntu (starting with 14.04) – full test suite working
  • Debian (starting with Stretch)
  • Fedora (starting with F25)
  • FreeBSD (starting with 10.01)
  • SunOS (starting with Open SunOS 11.2)
  • Cygwin (starting with 6.1)

If you make Zipios work on other platforms, let us know by posting an issue on GitHub:

https://github.com/Zipios/Zipios/issues

Documentation

This web page is the front page to the library documentation which is generated from the source files using Doxygen. Use the links at the top of the page to browse the API documentation. Your Doxygen installation may also be capable of generating other formats (Latex, PDF, etc.) if you would prefer such (we only offer the HTML documentation.)

Zip file access

The two most important classes are DirectoryCollection and ZipFile.

A ZipFile is also a FileCollection, only the collection is loaded from a Zip archive instead of a directory. A ZipFile is composed of ZipCentralDirectoryEntry objects. As far as you are concerned though, you can only use it as FileEntry objects.

Note that the ZipFile constructor immediately scans the Central Directory of the Zip archive so the entries are immediately accessible.

The DirectoryCollection can be created one file at a time, so it is possible to create a collection without having to include all the files from a directory. However, the files still have to exist on disk. The DirectoryCollection is composed of DirectoryEntry objects.

To access the entries in a collection, use the entries() function which returns a vector of FileEntry objects. If you know the exact filename of an entry, you may also use the getEntry() with that name. This is particularly useful if you want to use Zipios as a way to handle the resources of your executable (see the openEmbeddedZipFile() function and the appendzip.cpp tool). Finally, you want to use the getInputStream() function to read the data of a file defined in a collection.

// Resources global pointer
// Initialization of resources
g_resources = zipios::ZipFile::openEmbeddedZipFile("executable_filename");
// Anywhere else in your application
// 1. get the entry (to access meta data)
zipios::FileEntry::pointer_t entry(g_resources->getEntry("my/resource/file.xml"));
// 2. get the istream (to access the actual file data)
zipios::FileCollection::stream_pointer_t in_stream(g_resources->getInputStream("my/resource/file.xml"));

zipios_example.cpp demonstrates the central elements of Zipios when used in read mode.

FileCollection

A ZipFile is actually just a special kind of FileCollection that obtains its entries from a Zip archive. Zipios also implements a DirectoryCollection that obtains its entries from an on disk directory and a CollectionCollection that obtains its entries from other collections.

Using a single CollectionCollection, any number of other FileCollection's can be placed under its control and accessed through the same single interface that is used to access a ZipFile or a DirectoryCollection.

Warning
The CollectionCollection singleton in version 1.x was removed to make the entire library 100% re-entrant without the need to link against a thread library.
Download

Go to Zipios project page on SourceForge for tar balls, source code (CVS for v1.x and GIT for v2.x), and ChangeLog. https://sourceforge.net/projects/zipios/

Development

The Zipios project makes use of a few development tools and the tests require the zip utility, used to verify that an external tool can generate a zip file that Zipios can read.

Under a Debian or Ubuntu system, you can run apt-get install with the following list of packages:

# For source management (or download the .tar.gz file)
apt-get install git
# For development
apt-get install g++ cmake zlib1g-dev
# For documentation (or download the -doc.tar.gz file)
apt-get install doxygen graphviz
# For testing (optional, albeit recommended)
apt-get install catch zip

Under Fedora, you can use dnf (or yum for early versions):

# For source management (or download the .tar.gz file)
dnf install git
# For development
dnf install gcc-c++ cmake zlib-devel
# For documentation (or download the -doc.tar.gz file)
dnf install doxygen graphviz
# For testing (optional, albeit recommended)
dnf install catch-devel zip

Other systems use tools with pretty much the same naming convention so you should be able to make the correlation.

Links

zlib. The compression library that Zipios uses to perform the actual compression and decompression.

Java. Zipios version 1.0 is heavily inspired by the java.util.zip package. Version 2.0 is following the same philosophy without (1) attempting to follow the interface one to one and (2) without updating to the newer version, if there were changes...

You will find a text file in the doc directory named zip-format.txt with a complete description of the zip file format as of October 1, 2014.

Bugs

Submit bug reports and patches on:

http://sourceforge.net/projects/zipios/

Project hosted by

Syndicate content

Snap! Websites
An Open Source CMS System in C++

Contact Us Directly