An implementation of the FileEntry for Zip archives. More...

#include <ziplocalentry.hpp>

Inheritance diagram for zipios::ZipLocalEntry:

Collaboration diagram for zipios::ZipLocalEntry:

Public Types
typedef std::vector< unsigned char >	buffer_t

typedef int	CompressionLevel
	The compression level to be used to save an entry. More...

typedef uint32_t	crc32_t

typedef uint32_t	dostime_t

typedef std::shared_ptr < FileEntry >	pointer_t

typedef std::vector< pointer_t >	vector_t

Public Member Functions
	ZipLocalEntry ()
	Create a default ZipLocalEntry objects. More...

	ZipLocalEntry (FileEntry const &src)
	Copy of the ZipLocalEntry from any kind of FileEntry object. More...

virtual	~ZipLocalEntry () override
	Clean up a ZipLocalEntry object. More...

virtual pointer_t	clone () const override
	Create a clone of a ZipLocalEntry object. More...

virtual std::string	getComment () const
	Retrieve the comment of the file entry. More...

virtual size_t	getCompressedSize () const override
	Retrive the size of the file when compressed. More...

virtual crc32_t	getCrc () const
	Return the CRC of the entry. More...

std::streampos	getEntryOffset () const
	Get the offset of this entry in a Zip archive. More...

virtual buffer_t	getExtra () const
	Some extra data to be stored along the entry. More...

virtual std::string	getFileName () const
	Return the basename of this entry. More...

virtual size_t	getHeaderSize () const override
	Retrieve the size of the header. More...

virtual CompressionLevel	getLevel () const
	Retrieve the compression level. More...

virtual StorageMethod	getMethod () const
	Return the method used to create this entry. More...

virtual std::string	getName () const
	Return the filename of the entry. More...

virtual size_t	getSize () const
	Retrieve the size of the file when uncompressed. More...

virtual dostime_t	getTime () const
	Get the MS-DOS date/time of this entry. More...

virtual std::time_t	getUnixTime () const
	Get the Unix date/time of this entry. More...

bool	hasCrc () const
	Check whether the CRC32 was defined. More...

bool	hasTrailingDataDescriptor () const
	Is there a trailing data descriptor? More...

virtual bool	isDirectory () const override
	Check whether the filename represents a directory. More...

virtual bool	isEqual (FileEntry const &file_entry) const override
	Compare two file entries for equality. More...

virtual bool	isValid () const
	Check whether this entry is valid. More...

virtual void	read (std::istream &is) override
	Read one local entry from `is`. More...

virtual void	setComment (std::string const &comment)
	Set the comment field for the FileEntry. More...

virtual void	setCompressedSize (size_t size) override
	Set the size when the file is compressed. More...

virtual void	setCrc (crc32_t crc) override
	Save the CRC of the entry. More...

void	setEntryOffset (std::streampos offset)
	Defines the position of the entry in a Zip archive. More...

virtual void	setExtra (buffer_t const &extra)
	Set the extra field buffer. More...

virtual void	setLevel (CompressionLevel level)
	Define the level of compression to use by this FileEntry. More...

virtual void	setMethod (StorageMethod method)
	Sets the storage method field for the entry. More...

virtual void	setSize (size_t size)
	Sets the size field for the entry. More...

virtual void	setTime (dostime_t time)
	Set the FileEntry time using a DOS time. More...

virtual void	setUnixTime (std::time_t time)
	Sets the time field in Unix time format for the entry. More...

virtual std::string	toString () const
	Returns a human-readable string representation of the entry. More...

virtual void	write (std::ostream &os) override
	Write a ZipLocalEntry to `os`. More...

Static Public Attributes
static CompressionLevel const	COMPRESSION_LEVEL_DEFAULT = -3

static CompressionLevel const	COMPRESSION_LEVEL_FASTEST = -1

static CompressionLevel const	COMPRESSION_LEVEL_MAXIMUM = 100

static CompressionLevel const	COMPRESSION_LEVEL_MINIMUM = 1

static CompressionLevel const	COMPRESSION_LEVEL_NONE = 0

static CompressionLevel const	COMPRESSION_LEVEL_SMALLEST = -2

static uint16_t const	g_zip_format_version = 20

Protected Attributes
std::string	m_comment

StorageMethod	m_compress_method = StorageMethod::STORED

size_t	m_compressed_size = 0

CompressionLevel	m_compression_level = COMPRESSION_LEVEL_DEFAULT

uint32_t	m_crc_32 = 0

std::streampos	m_entry_offset = 0

buffer_t	m_extra_field

uint16_t	m_extract_version = g_zip_format_version

FilePath	m_filename

uint16_t	m_general_purpose_bitfield = 0

bool	m_has_crc_32 = false

bool	m_is_directory = false

size_t	m_uncompressed_size = 0

time_t	m_unix_time = 0

bool	m_valid = false

Detailed Description

A concrete implementation of the abstract FileEntry base class for ZipFile entries, specifically for representing the information present in the local headers of file entries in a zip file.

Definition at line 42 of file ziplocalentry.hpp.

Member Typedef Documentation

typedef std::vector<unsigned char> zipios::FileEntry::buffer_t

inherited

Definition at line 79 of file fileentry.hpp.

int zipios::FileEntry::CompressionLevel

inherited

Values defined using this time represent the compression level to be used when compressing an entry.

If unchanged, use the DEFAULT_COMPRESSION value.

It is possible to change the compression level to NO_COMPRESSION or use the setMethod() with STORED to avoid any compression (i.e. create a zip file which awfully looks like a tarball).

Todo:: These values are one to one mapped to zlib compression values. This is likely to change once we start offering other compression scheme for a number defined between 0 and 100 instead.

Definition at line 85 of file fileentry.hpp.

typedef uint32_t zipios::FileEntry::crc32_t

inherited

Definition at line 80 of file fileentry.hpp.

typedef uint32_t zipios::FileEntry::dostime_t

inherited

Definition at line 81 of file fileentry.hpp.

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

inherited

Definition at line 77 of file fileentry.hpp.

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

inherited

Definition at line 78 of file fileentry.hpp.

Constructor & Destructor Documentation

zipios::ZipLocalEntry::ZipLocalEntry ( )

This constructor is used to create a default ZipLocalEntry object.

Definition at line 123 of file ziplocalentry.cpp.

Referenced by clone().

zipios::ZipLocalEntry::ZipLocalEntry ( FileEntry const & src )

This function is used when copying a DirectoryEntry to a ZipCentralDirectoryEntry object when creating a copy while saving a Zip archive.

Parameters

[in] src The source to copy in this new ZipLocalEntry.

Definition at line 141 of file ziplocalentry.cpp.

zipios::ZipLocalEntry::~ZipLocalEntry ( )

overridevirtual

This function ensures proper clean up of a ZipLocationEntry object.

Definition at line 172 of file ziplocalentry.cpp.

Member Function Documentation

FileEntry::pointer_t zipios::ZipLocalEntry::clone ( ) const

overridevirtual

This function allocates a new ZipLocalEntry on the heap and returns a copy of this ZipLocalEntry object in it.

Returns: A new ZipLocalEntry which is a clone of this ZipLocalEntry object.

Implements zipios::FileEntry.

Reimplemented in zipios::ZipCentralDirectoryEntry.

Definition at line 158 of file ziplocalentry.cpp.

References ZipLocalEntry().

std::string zipios::FileEntry::getComment ( ) const

virtualinherited

This function returns the comment of this entry.

If the entry was not assigned a comment, this function returns an empty string. All entries can be given a comment, although for most it will be ignored unless you save the file to a Zip archive.

Returns: The comment associated with this entry, if there is one.

Definition at line 150 of file fileentry.cpp.

References zipios::FileEntry::m_comment.

size_t zipios::ZipLocalEntry::getCompressedSize ( ) const

overridevirtual

This function returns the compressed size of the entry. If the entry is not stored in a compressed format, the uncompressed size is returned.

Returns: The compressed size of the entry.

Reimplemented from zipios::FileEntry.

Definition at line 231 of file ziplocalentry.cpp.

References m_compressed_size.

FileEntry::crc32_t zipios::FileEntry::getCrc ( ) const

virtualinherited

This function returns the CRC 32 of this entry, if it has one.

The CRC is set only after the file is compressed so it may not always be available. The hasCrc() function can be used to know whether it was set before.

Returns: The CRC32 for the entry, if it has one.

Todo:: Should we throw if m_has_crc_32 is false?

Definition at line 182 of file fileentry.cpp.

References zipios::FileEntry::m_crc_32.

std::streampos zipios::FileEntry::getEntryOffset ( ) const

inherited

This function retrieves the offset at which this FileEntry resides in the Zip archive it is attached to.

Note that in case of a Zip archive embedded in another file, the offset is virtual (relative to the start of the Zip archive in the larger file.)

Returns: The position in the Zip archive.

Definition at line 202 of file fileentry.cpp.

References zipios::FileEntry::m_entry_offset.

FileEntry::buffer_t zipios::FileEntry::getExtra ( ) const

virtualinherited

This function returns a copy of the vector of bytes of extra data that are stored with the entry.

This buffer should be generated using the still non-existant ZipExtra class. This includes definitions of additional meta data necessary on various operating systems. For example, Linux makes use of the "UT" (Universal Time) to save the atime, ctime, and mtime parameters, and "ux" (Unix) to save the Unix permissions and user identifier (uid) and group identifier (gid).

Returns: A buffer_t of extra bytes that are associated with this entry.

Definition at line 222 of file fileentry.cpp.

References zipios::FileEntry::m_extra_field.

std::string zipios::FileEntry::getFileName ( ) const

virtualinherited

This function returns the filename only of the entry.

Warning: The function returns the last segment of the filename whether it is a regular file or a directory so one can search for a directory with the MATCH or IGNORE search options.

Returns: The filename of the entry.

Definition at line 320 of file fileentry.cpp.

References zipios::FilePath::filename(), and zipios::FileEntry::m_filename.

size_t zipios::ZipLocalEntry::getHeaderSize ( ) const

overridevirtual

This function dynamically determines the size of the Zip archive header necessary for this FileEntry.

This function returns the size of the Zip archive header.

Returns: The size of the header in bytes.

Reimplemented from zipios::FileEntry.

Reimplemented in zipios::ZipCentralDirectoryEntry.

Definition at line 246 of file ziplocalentry.cpp.

References zipios::FilePath::length(), zipios::FileEntry::m_extra_field, zipios::FileEntry::m_filename, and m_is_directory.

Referenced by zipios::ZipOutputStreambuf::updateEntryHeaderInfo().

FileEntry::CompressionLevel zipios::FileEntry::getLevel ( ) const

virtualinherited

Use this function to read the compression level to use to compress a file.

Note that the compression level is rarely saved in the destination file, so after reading a file from a Zip archive this parameter is set to the default compression level which does not represent the level used to create the file.

The compression level is a number between 1 and 100 if compression is wanted. 0 for no compression. A few negative numbers represent various default compression levels.

Returns: The compression level to use to write this entry to a Zip archive.

See Also: CompressionLevel; setLevel()

Definition at line 262 of file fileentry.cpp.

References zipios::FileEntry::COMPRESSION_LEVEL_NONE, zipios::FileEntry::isDirectory(), and zipios::FileEntry::m_compression_level.

StorageMethod zipios::FileEntry::getMethod ( ) const

virtualinherited

This function returns the method used to store the entry data in the FileCollection it is attached to.

Returns: the storage method used to store the entry in a collection.

See Also: StorageMethod; setMethod()

Definition at line 282 of file fileentry.cpp.

References zipios::FileEntry::isDirectory(), zipios::FileEntry::m_compress_method, and zipios::STORED.

Referenced by zipios::ZipInputStreambuf::underflow(), and zipios::ZipInputStreambuf::ZipInputStreambuf().

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

virtualinherited

The function returns the full filename of the entry, including a path if the entry is stored in a sub-folder.

Returns: The filename of the entry including its path.

Definition at line 303 of file fileentry.cpp.

References zipios::FileEntry::m_filename.

size_t zipios::FileEntry::getSize ( ) const

virtualinherited

This function returns the uncompressed size of the entry data.

Returns: Returns the uncompressed size of the entry.

Definition at line 332 of file fileentry.cpp.

References zipios::FileEntry::m_uncompressed_size.

Referenced by zipios::FileEntry::getCompressedSize(), and zipios::ZipInputStreambuf::ZipInputStreambuf().

FileEntry::dostime_t zipios::FileEntry::getTime ( ) const

virtualinherited

This function returns the date and time of the entry in MSDOS date/time format.

Note: An MS-DOS date is limited to 127 years starting on 1980. So it will be over after Dec 31, 2107.

Returns: The date and time of the entry in MS-DOS format.

Definition at line 349 of file fileentry.cpp.

References zipios::FileEntry::m_unix_time, and unix2dostime().

std::time_t zipios::FileEntry::getUnixTime ( ) const

virtualinherited

This function returns the date and time of the entry in Unix date/time format (see time()).

Note: The FileEntry object saves the time as a Unix time_t value, however, the Zip file format uses the DOS time format. So for a Zip file, the precision of the date is to the next even second. Yet, this function may return a value which is odd when the time comes from a file on disk.; Unless you have an old 32 bit system that defines time_t as a 32 bit value, a Unix date can be considered infinite. Otherwise it is limited to some time in 2068.

Returns: The date and time of the entry as a time_t value.

Definition at line 374 of file fileentry.cpp.

References zipios::FileEntry::m_unix_time.

bool zipios::FileEntry::hasCrc ( ) const

inherited

This function returns true if the setCrc() function was called earlier with a valid CRC32 and the FileEntry implementation supports a CRC (i.e. a DirectoryEntry does not have a CRC).

Returns: true if a CRC32 is defined in this class.

Definition at line 388 of file fileentry.cpp.

References zipios::FileEntry::m_has_crc_32.

bool zipios::ZipLocalEntry::hasTrailingDataDescriptor ( ) const

This function checks the bit in the General Purpose Flags to know whether the local entry header includes the compressed and uncompressed sizes or whether these are defined after the compressed data.

The trailing data buffer looks like this:

signature (PK 8.7) -- OPTIONAL  -- 32 bit
CRC 32                          -- 32 bit
compressed size                 -- 32 or 64 bit
uncompressed size               -- 32 or 64 bit

When a trailing data buffer is defined, the header has the compressed and uncompressed sizes set to zero.

Note: Zipios++ does not support such a scheme.

Returns: true if this file makes use of a trailing data buffer.

Definition at line 312 of file ziplocalentry.cpp.

References zipios::anonymous_namespace{ziplocalentry.cpp}::g_trailing_data_descriptor, and m_general_purpose_bitfield.

Referenced by zipios::ZipInputStreambuf::ZipInputStreambuf().

bool zipios::ZipLocalEntry::isDirectory ( ) const

overridevirtual

This function checks the last character of the filename, if it is a separator ('/') then the function returns true meaning that the file represents a directory.

Returns: true if the entry represents a directory.

Reimplemented from zipios::FileEntry.

Definition at line 185 of file ziplocalentry.cpp.

References m_is_directory.

bool zipios::ZipLocalEntry::isEqual ( FileEntry const & file_entry ) const

overridevirtual

This function compares most of the fields between two file entries to see whether they are equal or not.

Note: This function calls the base class isEqual() and also verifies that the ZipLocalEntry fields are equal.; This function is also used to compare ZipCDirEntry since none of the additional field participate in the comparison.

Parameters

[in] file_entry The file entry to compare this against.

Returns: true if both FileEntry objects are considered equal.

Reimplemented from zipios::FileEntry.

Definition at line 208 of file ziplocalentry.cpp.

References zipios::FileEntry::isEqual(), m_extract_version, m_general_purpose_bitfield, and m_is_directory.

Referenced by zipios::ZipFile::ZipFile().

bool zipios::FileEntry::isValid ( ) const

virtualinherited

Any method or operator that initializes a FileEntry may set a flag that specifies whether the file entry is valid or not. If it is not this method returns false.

Returns: true if the FileEntry has been parsed succesfully.

Definition at line 447 of file fileentry.cpp.

References zipios::FileEntry::m_valid.

Referenced by zipios::ZipInputStreambuf::ZipInputStreambuf().

void zipios::ZipLocalEntry::read ( std::istream & is )

overridevirtual

This function verifies that the input stream starts with a local entry signature. If so, it reads the input stream for a complete local entry.

Calling this function first marks the FileEntry object as invalid. If the read succeeds in full, then the entry is again marked as valid.

If a read fails, the function throws an exception as defined in the various zipRead() functions.

Note: Some of the data found in the local entry on disk are not kept in this class because there is nothing we can do with it.

Parameters

[in] is The input stream to read from.

Todo:: add support for zip64, some of those parameters may be 0xFFFFF...FFFF in which case the 64 bit header should be read

Reimplemented from zipios::FileEntry.

Reimplemented in zipios::ZipCentralDirectoryEntry.

Definition at line 335 of file ziplocalentry.cpp.

References dos2unixtime(), dostime(), zipios::g_separator, zipios::anonymous_namespace{ziplocalentry.cpp}::g_signature, zipios::FileEntry::m_compress_method, m_compressed_size, zipios::FileEntry::m_crc_32, zipios::FileEntry::m_extra_field, m_extract_version, zipios::FileEntry::m_filename, m_general_purpose_bitfield, m_is_directory, zipios::FileEntry::m_uncompressed_size, zipios::FileEntry::m_unix_time, zipios::FileEntry::m_valid, and zipios::zipRead().

Referenced by zipios::ZipFile::ZipFile(), and zipios::ZipInputStreambuf::ZipInputStreambuf().

void zipios::FileEntry::setComment ( std::string const & comment )

virtualinherited

This function sets the comment of this FileEntry. Note that all implementations of the FileEntry may not include support for a comment. In that case this function does nothing.

Parameters

[in] comment A string with the new comment.

Definition at line 461 of file fileentry.cpp.

References zipios::FileEntry::m_comment.

void zipios::ZipLocalEntry::setCompressedSize ( size_t size )

overridevirtual

This function saves the compressed size of the entry in this object.

By default the compressed size is viewed as the same as the uncompressed size (i.e. as if STORED was used for the compression method.)

Parameters

[in] size Value to set the compressed size field of the entry to.

Reimplemented from zipios::FileEntry.

Definition at line 267 of file ziplocalentry.cpp.

References m_compressed_size.

void zipios::ZipLocalEntry::setCrc ( crc32_t crc )

overridevirtual

This funciton savees the CRC field in this FileEntry field.

This function has the side of setting the m_has_crc_32 flag to true meaning that the CRC was defined as expected.

Parameters

[in] crc Value to set the CRC field to.

Reimplemented from zipios::FileEntry.

Definition at line 282 of file ziplocalentry.cpp.

References zipios::FileEntry::m_crc_32, and zipios::FileEntry::m_has_crc_32.

void zipios::FileEntry::setEntryOffset ( std::streampos offset )

inherited

This function defines the position of the FileEntry in a Zip archive. By default the position is set to zero.

The offset is generally read from a Zip directory entry.

When used to seek in a file, the FileCollection will add the start offset defined in the VirtualSeeker. In other words this is the position in the Zip archive itself, not the final position in the file you are reading the archive from.

Parameters

[in] offset The new archive entry offset.

Definition at line 512 of file fileentry.cpp.

References zipios::FileEntry::m_entry_offset.

void zipios::FileEntry::setExtra ( buffer_t const & extra )

virtualinherited

This function is used to set the extra field.

Only one type of file entry supports an extra field buffer. The others do nothing when this function is called.

Parameters

[in] extra The extra field is set to this value.

Definition at line 527 of file fileentry.cpp.

References zipios::FileEntry::m_extra_field.

void zipios::FileEntry::setLevel ( CompressionLevel level )

virtualinherited

This function saves the level of compression the library should use to compress the file before saving it in the output file.

Note: If the StorageMethod is set to STORED, then the compression level is ignored, but it is left unchanged.

Exceptions

InvalidStateException This function raises this exception if the specified level is out of the allowed range.

Parameters

[in] level The compression level to use to compress the file data.

Definition at line 548 of file fileentry.cpp.

References zipios::FileEntry::COMPRESSION_LEVEL_MAXIMUM, zipios::FileEntry::COMPRESSION_LEVEL_MINIMUM, zipios::FileEntry::COMPRESSION_LEVEL_NONE, zipios::FileEntry::isDirectory(), and zipios::FileEntry::m_compression_level.

void zipios::FileEntry::setMethod ( StorageMethod method )

virtualinherited

This function sets the method with which the file data is to be compressed.

The method is ignored in a file entry which cannot be compressed. (or more precisly, the method is forced as STORED.)

Exceptions

InvalidStateException This exception is raised if the method parameter does not represent a supported method. At this time the library only supports STORED and DEFLATED. The getMethod() may return more types as read from a Zip archive, but it is not possible to set such types using this function.

Parameters

[in] method The method field is set to the specified value.

Definition at line 585 of file fileentry.cpp.

References zipios::DEFLATED, zipios::FileEntry::isDirectory(), zipios::FileEntry::m_compress_method, and zipios::STORED.

void zipios::FileEntry::setSize ( size_t size )

virtualinherited

This function is used to save the size of this file on disk when uncompressed.

Parameters

[in] size The size field is set to this value.

Definition at line 637 of file fileentry.cpp.

References zipios::FileEntry::m_uncompressed_size.

void zipios::FileEntry::setTime ( dostime_t dostime )

virtualinherited

This function saves the specified dostime value as the last modification date and time of this entry. This is generally used when reading that information from a Zip archive. Otherwise you probably want to use the setUnixTime() instead since it is one to one compatible with the value handle by time(), stat(), and other OS functions.

Parameters

[in] dostime Set time field as is using this MSDOS date/time value.

Definition at line 653 of file fileentry.cpp.

References dos2unixtime(), and zipios::FileEntry::setUnixTime().

void zipios::FileEntry::setUnixTime ( std::time_t time )

virtualinherited

This function is used to set the last modification time of this entry. In most cases this comes from the stat structure field named st_mtime. If you are creating a file directly in memory, you may use the return value of time(nullptr);.

Parameters

[in] time The time field is set to the specified value.

Definition at line 668 of file fileentry.cpp.

References zipios::FileEntry::m_unix_time.

Referenced by zipios::FileEntry::setTime().

std::string zipios::FileEntry::toString ( ) const

virtualinherited

This function transforms the basic information of the entry in a string. Note that most of the information is lost as the function is likely to only display the filename and the size of the file, nothing more.