zipios++  2.0.2
Zipios++ – a small C++ library that provides easy access to .zip files.
Public Member Functions | Private Attributes | List of all members
zipios::VirtualSeeker Class Reference

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
InvalidExceptionThe two offsets must be positive.
Parameters
[in]start_offsetThe start offset of the embedded file.
[in]end_offsetThe 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_offsetReturns the start offset.
[out]end_offsetReturns 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
InvalidExceptionThe start offset must be before or equal to the end offset or this exception is raised.
Parameters
[in]start_offsetThe new start offset.
[in]end_offsetThe 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]isThe stream which pointer is to be changed.
[in]offsetRelative position to set the input pointer to.
[in]sdThe 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]isThe 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().


The documentation for this class was generated from the following files: