The ZipFile class represents a collection of files. More...

#include <zipfile.hpp>

Inheritance diagram for zipios::ZipFile:

Collaboration diagram for zipios::ZipFile:

Public Types
enum	MatchPath : uint32_t { MatchPath::IGNORE, MatchPath::MATCH }

typedef std::shared_ptr < FileCollection >	pointer_t

typedef std::shared_ptr < std::istream >	stream_pointer_t
	A shared pointer to an input stream. More...

typedef std::vector< pointer_t >	vector_t

Public Member Functions
	ZipFile ()
	Initialize a ZipFile object. More...

	ZipFile (std::string const &filename, offset_t s_off=0, offset_t e_off=0)
	Initialize a ZipFile object from an input file. More...

virtual	~ZipFile () override
	Clean up the ZipFile object. More...

virtual void	addEntry (FileEntry const &entry)
	Add an entry to this collection. More...

virtual pointer_t	clone () const override
	Create a clone of this ZipFile. More...

virtual void	close ()
	Close the current FileEntry of this FileCollection. More...

virtual FileEntry::vector_t	entries () const
	Retrieve the array of entries. More...

virtual FileEntry::pointer_t	getEntry (std::string const &name, MatchPath matchpath=MatchPath::MATCH) const
	Get an entry from this collection. More...

virtual stream_pointer_t	getInputStream (std::string const &entry_name, MatchPath matchpath=MatchPath::MATCH) override
	Retrieve a pointer to a file in the Zip archive. More...

virtual std::string	getName () const
	Returns the name of the FileCollection. More...

bool	isValid () const
	Check whether the current collection is valid. More...

virtual void	mustBeValid () const
	Check whether the collection is valid. More...

void	setLevel (size_t limit, FileEntry::CompressionLevel small_compression_level, FileEntry::CompressionLevel large_compression_level)
	Change the compression level to the specified value. More...

void	setMethod (size_t limit, StorageMethod small_storage_method, StorageMethod large_storage_method)
	Change the storage method to the specified value. More...

virtual size_t	size () const
	Returns the number of entries in the FileCollection. More...

Static Public Member Functions
static pointer_t	openEmbeddedZipFile (std::string const &name)
	Open a zip archive that was previously appened to another file. More...

static void	saveCollectionToArchive (std::ostream &os, FileCollection &collection, std::string const &zip_comment="")
	Create a Zip archive from the specified FileCollection. More...

Protected Attributes
FileEntry::vector_t	m_entries

std::string	m_filename

bool	m_valid = true

Private Attributes
VirtualSeeker	m_vs

Detailed Description

ZipFile is a FileCollection, where the files are stored in a .zip file.

Definition at line 47 of file zipfile.hpp.

Member Typedef Documentation

typedef std::shared_ptr<FileCollection> zipios::FileCollection::pointer_t

inherited

Definition at line 43 of file filecollection.hpp.

std::shared_ptr< std::istream > zipios::FileCollection::stream_pointer_t

inherited

This type of pointer is used whenever you retrieve an input stream from a file collection such as the ZipFile class. Having shared pointers ensures that the pointers can be shared between various functions and it gets deleted in the end.

Definition at line 45 of file filecollection.hpp.

typedef std::vector<pointer_t> zipios::FileCollection::vector_t

inherited

Definition at line 44 of file filecollection.hpp.

Member Enumeration Documentation

enum zipios::FileCollection::MatchPath : uint32_t

stronginherited

Enumerator
IGNORE
MATCH

Definition at line 47 of file filecollection.hpp.

Constructor & Destructor Documentation

zipios::ZipFile::ZipFile ( )

This is the default constructor of the ZipFile object.

Note that an empty ZipFile is marked as invalid. More or less, such an object is useless although it is useful to have this constructor if you want to work with maps or vectors of ZipFile objects.

Definition at line 283 of file zipfile.cpp.

Referenced by clone(), and openEmbeddedZipFile().

zipios::ZipFile::ZipFile	(	std::string const &	filename,
		offset_t	s_off = `0`,
		offset_t	e_off = `0`
	)

This constructor opens the named zip file. If the zip "file" is embedded in a file that contains other data, e.g. a binary program, the offset of the zip file start and end must be specified.

If the file cannot be opened or the Zip directory cannot be read, then the constructor throws an exception.

Parameters

[in]	filename	The filename of the zip file to open.
[in]	s_off	Offset relative to the start of the file, that indicates the beginning of the zip data in the file.
[in]	e_off	Offset relative to the end of the file, that indicates the end of the zip data in the file. The offset is a positive number, even though the offset is towards the beginning of the file.

Todo:: Make sure the entry offset is properly defined by ZipCentralDirectoryEntry. Also the isEqual() is a quite advance test here!

Definition at line 307 of file zipfile.cpp.

References zipios::ZipEndOfCentralDirectory::getCentralDirectorySize(), zipios::ZipEndOfCentralDirectory::getCount(), zipios::ZipEndOfCentralDirectory::getOffset(), zipios::ZipLocalEntry::isEqual(), zipios::FileCollection::m_entries, zipios::FileCollection::m_filename, zipios::FileCollection::m_valid, m_vs, zipios::ZipEndOfCentralDirectory::read(), zipios::ZipLocalEntry::read(), zipios::BackBuffer::readChunk(), zipios::VirtualSeeker::vseekg(), and zipios::VirtualSeeker::vtellg().

zipios::ZipFile::~ZipFile ( )

overridevirtual

The destructor ensures that any ZipFile data gets flushed out before returning.

Definition at line 408 of file zipfile.cpp.

References zipios::FileCollection::close().

Member Function Documentation

void zipios::FileCollection::addEntry ( FileEntry const & entry )

virtualinherited

This function adds an entry to the file collection allowing you to create a FileCollection from the exact files you want to have in the collection instead of having to read an entire directory as the DirectoryCollection offers by default.

Warning: This function creates a clone of the entry to make sure that the caller's entry can be modified without affecting the FileCollection.

Parameters

[in] entry The entry to add to the FileCollection.

Definition at line 368 of file filecollection.cpp.

References zipios::FileEntry::clone(), and zipios::FileCollection::m_entries.

FileCollection::pointer_t zipios::ZipFile::clone ( ) const

overridevirtual

This function creates a heap allocated clone of the ZipFile object.

Returns: A shared pointer to a copy of this ZipFile object.

Implements zipios::FileCollection.

Definition at line 397 of file zipfile.cpp.

References ZipFile().

void zipios::FileCollection::close ( )

virtualinherited

This function closes the current file entry.

Reimplemented in zipios::CollectionCollection, and zipios::DirectoryCollection.

Definition at line 378 of file filecollection.cpp.

References zipios::anonymous_namespace{filecollection.cpp}::g_default_filename, zipios::FileCollection::m_entries, zipios::FileCollection::m_filename, and zipios::FileCollection::m_valid.

Referenced by zipios::DirectoryCollection::close(), zipios::CollectionCollection::close(), and ~ZipFile().

FileEntry::vector_t zipios::FileCollection::entries ( ) const

virtualinherited

This function returns a copy of the file collection vector of entries. Note that the vector is copied but not the entries, so modifications to the entries will be reflected in this FileCollection entries. However, adding and removing entries to the collection is not reflected in the copy.

Returns: A vector containing the entries of this FileCollection.

Reimplemented in zipios::CollectionCollection, and zipios::DirectoryCollection.

Definition at line 396 of file filecollection.cpp.

References zipios::FileCollection::m_entries, and zipios::FileCollection::mustBeValid().

Referenced by zipios::DirectoryCollection::entries(), zipios::FileCollection::getEntry(), main(), zipios::operator<<(), saveCollectionToArchive(), zipios::FileCollection::setLevel(), zipios::FileCollection::setMethod(), and zipios::FileCollection::size().

FileEntry::pointer_t zipios::FileCollection::getEntry	(	std::string const &	name,
		MatchPath	matchpath = `MatchPath::MATCH`
	)		const

virtualinherited

This function returns a shared pointer to a FileEntry object for the entry with the specified name. To ignore the path part of the filename while searching for a match, specify FileCollection::IGNORE as the second argument.

Note: The collection must be valid or the function raises an exception.

Parameters

[in]	name	A string containing the name of the entry to get.
[in]	matchpath	Speficy MatchPath::MATCH, if the path should match as well, specify MatchPath::IGNORE, if the path should be ignored.

Returns: A shared pointer to the found entry. The returned pointer is null if no entry is found.

See Also: mustBeValid()

Reimplemented in zipios::CollectionCollection, and zipios::DirectoryCollection.

Definition at line 424 of file filecollection.cpp.

References zipios::FileCollection::entries(), zipios::FileCollection::m_entries, zipios::FileCollection::MATCH, and zipios::FileCollection::mustBeValid().

Referenced by zipios::DirectoryCollection::getEntry(), getInputStream(), and main().

ZipFile::stream_pointer_t zipios::ZipFile::getInputStream	(	std::string const &	entry_name,
		MatchPath	matchpath = `MatchPath::MATCH`
	)

overridevirtual

This function returns a shared pointer to an istream defined from the named entry, which gives you access to the corresponding file defined in the Zip archive.

The function returns nullptr if there is no entry with the specified name in this ZipFile.

Note that the function returns a smart pointer to an istream. The ZipFile class does not hold that pointer meaning that if you call getInputStream() multiple times with the same entry_name parameter, you get different istream instance each time.

By default the entry_name parameter is expected to match the full path and filename (MatchPath::MATCH). If you are looking for a file and want to ignore the path, set the matchpath parameter to MatchPath::IGNORE.

Note: If the file is compressed inside the Zip archive, this input stream returns the uncompressed data transparently to you (outside of the time it takes to decompress the data, of course.)

Parameters

[in]	entry_name	The name of the file to search in the collection.
[in]	matchpath	Whether the full path or just the filename is matched.

Returns: A shared pointer to an open istream for the specified entry.

See Also: CollectionCollection; DirectoryCollection; FileCollection

Implements zipios::FileCollection.

Definition at line 448 of file zipfile.cpp.

References zipios::FileCollection::getEntry(), zipios::FileCollection::m_filename, m_vs, zipios::FileCollection::mustBeValid(), and zipios::VirtualSeeker::startOffset().

Referenced by main().

std::string zipios::FileCollection::getName ( ) const

virtualinherited

This function returns the filename of the collection as a whole.

Note: The collection my be valid.

Returns: The name of the FileCollection.

See Also: mustBeValid()

Definition at line 456 of file filecollection.cpp.

References zipios::FileCollection::m_filename, and zipios::FileCollection::mustBeValid().

Referenced by zipios::operator<<().

bool zipios::FileCollection::isValid ( ) const

inherited

This function returns true if the collection is valid.

Note that by default (just after a new) a collection is not considered valid.

Returns: true if the collection is valid.

Definition at line 493 of file filecollection.cpp.

References zipios::FileCollection::m_valid.

Referenced by zipios::CollectionCollection::addCollection().

void zipios::FileCollection::mustBeValid ( ) const

virtualinherited

This function verifies that the collection is valid. If not, an exception is raised. Many other functions from the various collection functions are calling this function before accessing data.

Exceptions

InvalidStateException This exception is raised if the m_valid field is currently false and thus most of the collection data is considered invalid.

Reimplemented in zipios::CollectionCollection.

Definition at line 509 of file filecollection.cpp.

References zipios::FileCollection::m_valid.

Referenced by zipios::FileCollection::entries(), zipios::FileCollection::getEntry(), getInputStream(), zipios::FileCollection::getName(), zipios::DirectoryCollection::loadEntries(), zipios::CollectionCollection::mustBeValid(), zipios::FileCollection::setLevel(), zipios::FileCollection::setMethod(), and zipios::FileCollection::size().

ZipFile::pointer_t zipios::ZipFile::openEmbeddedZipFile ( std::string const & name )

static

Opens a Zip archive embedded in another file, by writing the zip archive to the end of the file followed by the start offset of the zip file on 4 bytes. The offset must be written in zip-file byte-order (little endian).

The program appendzip, which is part of the Zipios++ distribution can be used to append a Zip archive to a file, e.g. a binary program.

The function may throw various exception if the named file does not seem to include a valid zip archive attached.

Note: Only one file can be appended and opened in this way. Although the appendzip tool can be used to append any number of files, only the last one is accessible.

Returns: A ZipFile that one can use to read compressed data.

Definition at line 260 of file zipfile.cpp.

References ZipFile(), and zipios::zipRead().

void zipios::ZipFile::saveCollectionToArchive	(	std::ostream &	os,
		FileCollection &	collection,
		std::string const &	zip_comment = `""`
	)

static

This function is expected to be used with a DirectoryCollection that you created to save the collection in an archive.

Parameters

[in,out]	os	The output stream where the Zip archive is saed.
[in]	collection	The collection to save in this output stream.
[in]	zip_comment	The global comment of the Zip archive.

Definition at line 473 of file zipfile.cpp.

References zipios::ZipOutputStream::close(), zipios::ZipOutputStream::closeEntry(), zipios::FileCollection::entries(), zipios::ZipOutputStream::finish(), zipios::FileCollection::getInputStream(), zipios::ZipOutputStream::putNextEntry(), and zipios::ZipOutputStream::setComment().

void zipios::FileCollection::setLevel	(	size_t	limit,
		FileEntry::CompressionLevel	small_compression_level,
		FileEntry::CompressionLevel	large_compression_level
	)

inherited

This function changes the compression level of all the entries in this collection to the specified value.

The size limit is used to know which compression level to use: small_compression_level for any file that has a size smaller or equal to the specified limit and large_compression_level for the others.

Parameters

[in]	limit	The threshold to use to define the compression level.
[in]	small_compression_level	The compression level for smaller files.
[in]	large_compression_level	The compression level for larger files.

Definition at line 567 of file filecollection.cpp.

References zipios::FileCollection::entries(), zipios::FileCollection::m_entries, and zipios::FileCollection::mustBeValid().

void zipios::FileCollection::setMethod	(	size_t	limit,
		StorageMethod	small_storage_method,
		StorageMethod	large_storage_method
	)

inherited

This function changes the storage method of all the entries in this collection to the specified value.

The size limit is used to know which storage method to use: small_storage_method for any file that has a size smaller or equal to the specified limit and large_storage_method for the others.

Parameters

[in]	limit	The threshold to use to define the compression level.
[in]	small_storage_method	The storage method for smaller files.
[in]	large_storage_method	The storage method for larger files.

Definition at line 532 of file filecollection.cpp.

References zipios::FileCollection::entries(), zipios::FileCollection::m_entries, and zipios::FileCollection::mustBeValid().

size_t zipios::FileCollection::size ( ) const

virtualinherited

This function returns the number of entries in the collection.