Public Member Functions | List of all members
Zipper Class Reference

Transactional modification of entries in a new or existing zip archive. More...

#include <Zip.hpp>

Inheritance diagram for Zipper:
[legend]
Collaboration diagram for Zipper:
[legend]

Public Member Functions

void close () override
 Rollback the transaction and close the archive. More...
 
void commit ()
 Commit the transaction and close the archive. More...
 
void deleteComment ()
 Deletes the comment in the archive. More...
 
void deleteEntry (const std::string &name)
 Delete an existing entry in the original archive. More...
 
void open (const Resource::File &path_, bool verify) override
 Begin a transaction to write to the specified archive. More...
 
void open (const Resource::File &path_, bool verify, const std::string &pw) override
 Begin a transaction to write to the specified archive. More...
 
void putArchiveComment (const std::string &text)
 Set the comment in the archive, overwriting any existing comment. More...
 
void putDirectory (const std::string &name)
 Ensure that the specified directory exists. More...
 
void putEntry (const std::string &name, const Resource::File &bytes)
 Create or overwrite an entry from the data in the supplied file. More...
 
void putEntry (const std::string &name, const std::vector< char > &bytes)
 Create or overwrite an entry from the supplied std::vector<char>. More...
 
void putEntry (const std::string &name, const std::string &bytes)
 Create or overwrite an entry from the supplied string. More...
 
void renameEntry (const std::string &name, const std::string &newName)
 Rename an existing entry in the original archive. More...
 
- Public Member Functions inherited from Unzipper
virtual ~Unzipper ()
 Destroy the unzipper, closing the archive if it is open. More...
 
long long entryCount () const
 Get the number of entries in the original archive if one exists. More...
 
std::vector< std::string > entryNames () const
 Get the entry names in the original archive if one exists. More...
 
long long getEntryIndex (const std::string &name) const
 Get the index of the entry that corresponds to the supplied name. More...
 
void getEntryInfo (const std::string &name, ZipEntryInfo &info) const
 Get information on the entry with the specified name. More...
 
void getEntryInfo (long long index, ZipEntryInfo &info) const
 Get information on the entry with the specified index. More...
 
std::string getEntryName (long long index) const
 Get the name of the entry that corresponds to the supplied index. More...
 
Resource::File getPath () const
 Get the file URI that this unzipper accesses. More...
 
bool hasEntry (const std::string &name) const
 Does the original archive have an entry with the specified name? More...
 
bool isOpen () const
 Is an archive currently open? More...
 
std::string readArchiveComment () const
 Get the comment on the archive if one exists. More...
 
std::vector< char > readEntryAsBytes (const std::string &name) const
 Get the contents of the specified entry in the original archive if one exists. More...
 
std::vector< char > readEntryAsBytes (long long index) const
 Get the contents of the specified entry in the original archive if one exists. More...
 
std::string readEntryAsString (const std::string &name) const
 Get the contents of the specified entry in the original archive if one exists. More...
 
std::string readEntryAsString (long long index) const
 Get the contents of the specified entry in the original archive if one exists. More...
 
std::string readEntryComment (const std::string &name) const
 Get the comment on the entry if one exists. More...
 
std::string readEntryComment (long long index) const
 Get the comment on the entry if one exists. More...
 

Detailed Description

Transactional modification of entries in a new or existing zip archive.

No mutation is performed on the existing archive if the zipper is acting on an existing file. When commit() is called, the existing archive will be replaced with a revised file containing original unmodified data from the original file, plus data for new or revised entries added during the transaction.

In addition to transactional zipping, an initialised zipper instance provides random access to the original zip archive if there is one. All read calls will return data from the original archive only.

Zipper instances are not thread safe and thus must be used in a single thread.

Member Function Documentation

◆ close()

void close ( )
overridevirtual

Rollback the transaction and close the archive.

If the transaction is working on an existing archive, the file will be left untouched. If the transaction is working on a new archive, no file will be created.

In order to continue using the instance, a subsequent call to open() is necessary.

If close is called without a corresponding previous call to open(), the result will be a NOP.

Reimplemented from Unzipper.

◆ commit()

void commit ( )

Commit the transaction and close the archive.

If the transaction is working on an existing archive, the file will be replaced with the revised file. If the transaction is working on a new archive, the file will be created.

In order to continue using the instance, a subsequent call to open() is necessary.

If commit is called without a corresponding previous call to open(), the result will be a NOP.

If this call fails, a ZipException will be thrown and the zipper instance will still contain the pending changes. In this case, a subsequent call to close() will be necessary in order to abandon the changes and close the archive.

◆ deleteComment()

void deleteComment ( )

Deletes the comment in the archive.

Exceptions
ZipExceptionif the archive comment could not be deleted
ZipExceptionif the archive is not open

◆ deleteEntry()

void deleteEntry ( const std::string &  name)

Delete an existing entry in the original archive.

If the entry is a directory, all files under that directory will also be deleted.

Parameters
namethe name of the existing entry in the original archive
Exceptions
ZipExceptionif the entry could not be deleted
ZipExceptionif the archive is not open

◆ open() [1/2]

void open ( const Resource::File path_,
bool  verify 
)
overridevirtual

Begin a transaction to write to the specified archive.

If the archive does not exist, it is created and written to when commit() is called.

If the archive does exist, a new archive is created from the original one when commit() is called, with the modifications made in the transaction.

Parameters
path_the path to the archive
verifyif true, the implementation will first verify the archive
Exceptions
InvalidArchiveExceptionif verify is true and the archive is deemed to be invalid

Reimplemented from Unzipper.

◆ open() [2/2]

void open ( const Resource::File path_,
bool  verify,
const std::string &  pw 
)
overridevirtual

Begin a transaction to write to the specified archive.

If the archive does not exist, it is created and written to when commit() is called.

If the archive does exist, a new archive is created from the original one when commit() is called, with the modifications made in the transaction.

Parameters
path_the path to the archive
verifyif true, the implementation will first verify the archive
pwthe archive's password if encryption was used when writing
Exceptions
InvalidArchiveExceptionif verify is true and the archive is deemed to be invalid

Reimplemented from Unzipper.

◆ putArchiveComment()

void putArchiveComment ( const std::string &  text)

Set the comment in the archive, overwriting any existing comment.

Parameters
textthe text content to set the comment to
Exceptions
ZipExceptionif the archive comment could not be set
ZipExceptionif the archive is not open

◆ putDirectory()

void putDirectory ( const std::string &  name)

Ensure that the specified directory exists.

All parent directories will also be created if not present.

Parameters
namethe directory name
Exceptions
ZipExceptionif a directory could not be created
ZipExceptionif the archive is not open

◆ putEntry() [1/3]

void putEntry ( const std::string &  name,
const Resource::File bytes 
)

Create or overwrite an entry from the data in the supplied file.

Parameters
namethe name of the entry to create or overwrite
bytesthe file from which the data to create the entry with will be sourced
Exceptions
ZipExceptionif the entry could not be created
ZipExceptionif the archive is not open

◆ putEntry() [2/3]

void putEntry ( const std::string &  name,
const std::vector< char > &  bytes 
)

Create or overwrite an entry from the supplied std::vector<char>.

Note that all in memory supplied data will be copied before committing, so files should be used if the data is very large.

Parameters
namethe name of the entry to create or overwrite
bytesthe data to create the entry with
Exceptions
ZipExceptionif the entry could not be created
ZipExceptionif the archive is not open

◆ putEntry() [3/3]

void putEntry ( const std::string &  name,
const std::string &  bytes 
)

Create or overwrite an entry from the supplied string.

Note that all in memory supplied data will be copied before committing, so files should be used if the data is very large.

Parameters
namethe name of the entry to create or overwrite
bytesthe data to create the entry with
Exceptions
ZipExceptionif the entry could not be created
ZipExceptionif the archive is not open

◆ renameEntry()

void renameEntry ( const std::string &  name,
const std::string &  newName 
)

Rename an existing entry in the original archive.

If the entry is a directory, all files under that directory will also be renamed.

Parameters
namethe name of the existing entry in the original archive
newNamethe new name to give to the entry
Exceptions
ZipExceptionif the entry could not be renamed
ZipExceptionif the archive is not open

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