zipios_VirtualSeeker man page

zipios::VirtualSeeker — A virtual class used to see in a file embedded in another.

Synopsis

#include <virtualseeker.hpp>

Public Member Functions

VirtualSeeker (offset_t start_offset=0, offset_t end_offset=0)
Create a virtual seeker.
offset_t endOffset () const
Return the end offset.
void getOffsets (offset_t &start_offset, offset_t &end_offset) const
Retrieve the current offsets.
void setOffsets (offset_t start_offset, offset_t end_offset)
Set the offsets of the virtual seeker.
offset_t startOffset () const
Return the start offset.
void vseekg (std::istream &is, offset_t offset, std::ios::seekdir sd) const
Seek within the embedded file.
std::streampos vtellg (std::istream &is) const
Current position within the sub-file.

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:

start_offset The start offset of the embedded file.
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:

start_offset Returns the start offset.
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:

start_offset The new start offset.
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:

is The stream which pointer is to be changed.
offset Relative position to set the input pointer to.
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:

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().

Member Data Documentation

offset_t zipios::VirtualSeeker::m_end_offset = 0 [private]

Definition at line 60 of file virtualseeker.hpp.

Referenced by endOffset(), getOffsets(), setOffsets(), VirtualSeeker(), and vseekg().

offset_t zipios::VirtualSeeker::m_start_offset = 0 [private]

Definition at line 59 of file virtualseeker.hpp.

Referenced by getOffsets(), setOffsets(), startOffset(), VirtualSeeker(), vseekg(), and vtellg().

Author

Generated automatically by Doxygen for zipios from the source code.

Info

Mon Apr 11 2016 Version 2.1.1 zipios