A virtual class used to see in a file embedded in another. More...

#include <virtualseeker.hpp>

Public Member Functions
	VirtualSeeker (offset_t start_offset=0, offset_t end_offset=0)
	Create a virtual seeker. More...

offset_t	endOffset () const
	Return the end offset. More...

void	getOffsets (offset_t &start_offset, offset_t &end_offset) const
	Retrieve the current offsets. More...

void	setOffsets (offset_t start_offset, offset_t end_offset)
	Set the offsets of the virtual seeker. More...

offset_t	startOffset () const
	Return the start offset. More...

void	vseekg (std::istream &is, offset_t offset, std::ios::seekdir sd) const
	Seek within the embedded file. More...

std::streampos	vtellg (std::istream &is) const
	Current position within the sub-file. More...

Private Attributes
offset_t	m_end_offset = 0

offset_t	m_start_offset = 0

Detailed Description

The virtual seeker class is a simple definition of an object that keeps track of a set of specified (virtual) file pointers that mark start and end of a file inside another.

An example of its use (and its reason for existence) is to keep track of the file endings of a Zip file embedded in another file (see the appendzip tool and the ZipFile::openEmbeddedZipFile() function).

Bug:: The class is not linked to an input stream when created or the offsets get modified. This means the seek and tell functions cannot be sure that the offsets are valid of the specified input buffer.

Definition at line 46 of file virtualseeker.hpp.

Constructor & Destructor Documentation

zipios::VirtualSeeker::VirtualSeeker	(	offset_t	start_offset = `0`,
		offset_t	end_offset = `0`
	)

This constructor defines a virtual seeker start and end offsets on initialization. By default it is initialized to a transparent seeker since the start and end are set to zero.

Note: If the offsets are left undefined (both set to zero) then the virtual seeker is viewed as a transparent seeker, meaning that it seeks in the input streams as if it did not exist.

Warning: The virtual seek end offset is quite peculiar in that it is defined as a POSITIVE number from the end of the file, going backward. The normal seekg() command expects a negative number of an offset to be applied from the end of the file.; The class is not attached to one specific input stream so there is no way to verify that the offsets are valid (i.e. not representing an empty virtual file or having offsets completely outside of the available range.)

Exceptions

InvalidException The two offsets must be positive.

Parameters

[in]	start_offset	The start offset of the embedded file.
[in]	end_offset	The end offset of the embedded file.

Definition at line 92 of file virtualseeker.cpp.

References m_end_offset, and m_start_offset.

Member Function Documentation

offset_t zipios::VirtualSeeker::endOffset ( ) const

This function returns a copy of the end offset.

Returns: The end offset.

Definition at line 161 of file virtualseeker.cpp.

References m_end_offset.

void zipios::VirtualSeeker::getOffsets	(	offset_t &	start_offset,
		offset_t &	end_offset
	)		const

This function retrieves the start and end offsets from the virtual seeker object.

Parameters

[out]	start_offset	Returns the start offset.
[out]	end_offset	Returns the end offset.

Definition at line 136 of file virtualseeker.cpp.

References m_end_offset, and m_start_offset.

void zipios::VirtualSeeker::setOffsets	(	offset_t	start_offset,
		offset_t	end_offset
	)

This function can be used to change the virtual seeker offsets.

Exceptions

InvalidException The start offset must be before or equal to the end offset or this exception is raised.

Parameters

[in]	start_offset	The new start offset.
[in]	end_offset	The new end offset.

Definition at line 115 of file virtualseeker.cpp.

References m_end_offset, and m_start_offset.

offset_t zipios::VirtualSeeker::startOffset ( ) const

This function returns a copy of the start offset.

Returns: The start offset.

Definition at line 149 of file virtualseeker.cpp.

References m_start_offset.

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

void zipios::VirtualSeeker::vseekg	(	std::istream &	is,
		offset_t	offset,
		std::ios::seekdir	sd
	)		const

This function changes the file pointer in is to the position specified in offset.

The direction can be indicated by sd.

Parameters

[in,out]	is	The stream which pointer is to be changed.
[in]	offset	Relative position to set the input pointer to.
[in]	sd	The stream direction to use to apply offset.

Definition at line 178 of file virtualseeker.cpp.

References m_end_offset, and m_start_offset.

Referenced by zipios::BackBuffer::BackBuffer(), zipios::BackBuffer::readChunk(), and zipios::ZipFile::ZipFile().

std::streampos zipios::VirtualSeeker::vtellg ( std::istream & is ) const

This function calculates the position (file current pointer) within the embedded file in the specified stream.

If the position in the existing file is too large or too small, then the function returns -1.

Parameters

[in] is The stream to get the position from.

Returns: The stream offset within the embedded file.

Todo:: We may want to get the size of the file and verify that the resulting position is valid. The m_end_offset does not really mean anything at this point that we could use to verify the position boundaries (since it is a positive size from the end of the file.)

Definition at line 218 of file virtualseeker.cpp.

References m_start_offset.

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