ZipArchive

class ZipArchive

Bases: ReferenceCount

A file that contains a set of files.

Inheritance diagram

ZipArchive(void)

bool add_jar_signature(Filename const &certificate, Filename const &pkey, std::string const &password = "", std::string const &alias = "cert")

Adds a new JAR-style signature to the .zip file. The file must have been opened in read/write mode.

This implicitly causes a repack() operation if one is needed. Returns true on success, false on failure.

This flavor of add_jar_signature() reads the certificate and private key from a PEM-formatted file, for instance as generated by the openssl command. If the private key file is password-encrypted, the third parameter will be used as the password to decrypt it.

It’s possible to add multiple signatures, by providing multiple unique aliases. Note that aliases are considered case-insensitively and only the first 8 characters are considered.

There is no separate parameter to pass a certificate chain. Instead, any necessary certificates are expected to be in the certificate file.

Adds a new JAR-style signature to the .zip file. The file must have been opened in read/write mode.

This implicitly causes a repack() operation if one is needed. Returns true on success, false on failure.

It’s possible to add multiple signatures, by providing multiple unique aliases. Note that aliases are considered case-insensitively and only the first 8 characters are considered.

The private key is expected to match the first certificate in the chain.

std::string add_subfile(std::string const &subfile_name, Filename const &filename, int compression_level)

std::string add_subfile(std::string const &subfile_name, std::istream *subfile_data, int compression_level)

Adds a file on disk as a subfile to the ZipArchive. The file named by filename will be read and added to the ZipArchive immediately, but the index will not be updated until you call flush(). If there already exists a subfile with the indicated name, it is replaced without examining its contents (but see also update_subfile).

Returns the subfile name on success (it might have been modified slightly), or empty string on failure.

Adds a file from a stream as a subfile to the ZipArchive. The indicated istream will be read and its contents added to the end of the current ZIP file immediately.

Note that the istream must remain untouched and unused by any other code until flush() is called. At that time, the index of the ZIP archive will be rewritten to the end of the file.

Returns the subfile name on success (it might have been modified slightly), or empty string on failure.

void close(void)

Closes the ZipArchive if it is open. All changes are flushed to disk, and the file becomes invalid for further operations until the next call to open().

static void close_read_subfile(std::istream *stream)

Closes a file opened by a previous call to open_read_subfile(). This really just deletes the istream pointer, but it is recommended to use this interface instead of deleting it explicitly, to help work around compiler issues.

bool compare_subfile(int index, Filename const &filename)

Performs a byte-for-byte comparison of the indicated file on disk with the nth subfile. Returns true if the files are equivalent, or false if they are different (or the file is missing).

If Filename::set_binary() or set_text() has already been called, it specifies the nature of the source file. If this is different from the text flag of the subfile, the comparison will always return false. If this has not been specified, it will be set from the text flag of the subfile.

bool extract_subfile(int index, Filename const &filename)

Extracts the nth subfile into a file with the given name.

bool extract_subfile_to(int index, std::ostream &out)

Extracts the nth subfile to the indicated ostream.

int find_subfile(std::string const &subfile_name) const

Returns the index of the subfile with the indicated name, or -1 if the named subfile is not within the ZipArchive.

bool flush(void)

Ensures that any changes made to the ZIP archive have been synchronized to disk. In particular, this causes the central directory to be rewritten at the end of the file.

This may result in a suboptimal packing in the ZIP file, especially if existing files were changed or files were removed. To guarantee that the file is as compact as it can be, call repack() instead of flush().

It is not necessary to call flush() explicitly unless you are concerned about reading the recently-added subfiles immediately.

Returns true on success, false on failure.

std::string const &get_comment(void) const

Returns the comment string that was at the end of the ZIP end-of-directory record, if any. See set_comment().

Filename const &get_filename(void) const

Returns the filename of the ZipArchive, if it is available.

int get_num_subfiles(void) const

Returns the number of subfiles within the ZipArchive. The subfiles may be accessed in alphabetical order by iterating through [0 .. get_num_subfiles()).

bool get_record_timestamp(void) const

Returns the flag indicating whether timestamps should be recorded within the ZipArchive or not. See set_record_timestamp().

std::size_t get_subfile_internal_length(int index) const

Returns the number of bytes the indicated subfile consumes within the archive. For compressed subfiles, this will generally be smaller than get_subfile_length(); for encrypted (but noncompressed) subfiles, it may be slightly different, for noncompressed and nonencrypted subfiles, it will be equal.

std::streamoff get_subfile_internal_start(int index) const

Returns the starting byte position within the ZipArchive at which the indicated subfile begins. This may be used, with get_subfile_internal_length(), for low-level access to the subfile, but usually it is better to use open_read_subfile() instead (which automatically decrypts and/or uncompresses the subfile data).

std::size_t get_subfile_length(int index) const

Returns the uncompressed data length of the nth subfile.

std::string const &get_subfile_name(int index) const

Returns the name of the nth subfile.

time_t get_subfile_timestamp(int index) const

Returns the modification time of the nth subfile. If this is called on an older .zip file, which did not store individual timestamps in the file (or if get_record_timestamp() is false), this will return the modification time of the overall ZIP file.

bool has_directory(std::string const &subfile_name) const

Returns true if the indicated subfile name is the directory prefix to one or more files within the ZipArchive. That is, the ZipArchive contains at least one file named “subfile_name/…”.

bool is_read_valid(void) const

Returns true if the ZipArchive has been opened for read mode and there have been no errors, and individual Subfile contents may be extracted.

bool is_subfile_compressed(int index) const

Returns true if the indicated subfile has been compressed when stored within the archive, false otherwise.

bool is_subfile_encrypted(int index) const

Returns true if the indicated subfile has been encrypted when stored within the archive, false otherwise.

bool is_write_valid(void) const

Returns true if the ZipArchive has been opened for write mode and there have been no errors, and Subfiles may be added or removed from the ZipArchive.

void ls(std::ostream &out = ::std::cout) const

Shows a list of all subfiles within the ZipArchive.

bool needs_repack(void) const

Returns true if the ZipArchive index is suboptimal and should be repacked. Call repack() to achieve this. It is not done automatically.

bool open_read(Filename const &filename)

bool open_read(IStreamWrapper *stream, bool owns_pointer = false)

Opens the named ZipArchive on disk for reading. The ZipArchive index is read in, and the list of subfiles becomes available; individual subfiles may then be extracted or read, but the list of subfiles may not be modified.

Also see the version of open_read() which accepts an istream. Returns true on success, false on failure.

Opens an anonymous ZipArchive for reading using an istream. There must be seek functionality via seekg() and tellg() on the istream.

If owns_pointer is true, then the ZipArchive assumes ownership of the stream pointer and will delete it when the ZIP file is closed, including if this function returns false.

The given stream must be seekable.

std::istream *open_read_subfile(int index)

Returns an istream that may be used to read the indicated subfile. You may seek() within this istream to your heart’s content; even though it will be a reference to the already-opened pfstream of the ZipArchive itself, byte 0 appears to be the beginning of the subfile and EOF appears to be the end of the subfile.

The returned istream will have been allocated via new; you should pass the pointer to close_read_subfile() when you are finished with it to delete it and release its resources.

Any future calls to repack() or close() (or the ZipArchive destructor) will invalidate all currently open subfile pointers.

The return value will be NULL if the stream cannot be opened for some reason.

This variant of open_read_subfile() is used internally only, and accepts a pointer to the internal Subfile object, which is assumed to be valid and written to the multifile.

bool open_read_write(Filename const &filename)

bool open_read_write(std::iostream *stream, bool owns_pointer = false)

Opens the named ZipArchive on disk for reading and writing. If there already exists a file by that name, its index is read. Subfiles may be added or removed, and the resulting changes will be written to the named file.

Also see the version of open_read_write() which accepts an iostream. Returns true on success, false on failure.

Opens an anonymous ZipArchive for reading and writing using an iostream. There must be seek functionality via seekg()/seekp() and tellg()/tellp() on the iostream.

If owns_pointer is true, then the ZipArchive assumes ownership of the stream pointer and will delete it when the ZIP file is closed, including if this function returns false.

bool open_write(Filename const &filename)

bool open_write(std::ostream *stream, bool owns_pointer = false)

Opens the named ZipArchive on disk for writing. If there already exists a file by that name, it is truncated. The ZipArchive is then prepared for accepting a brand new set of subfiles, which will be written to the indicated filename. Individual subfiles may not be extracted or read.

Also see the version of open_write() which accepts an ostream. Returns true on success, false on failure.

Opens an anonymous ZipArchive for writing using an ostream.

If owns_pointer is true, then the ZipArchive assumes ownership of the stream pointer and will delete it when the ZIP file is closed, including if this function returns false.

void output(std::ostream &out) const

vector_uchar read_subfile(int index)

Returns a vector_uchar that contains the entire contents of the indicated subfile.

Fills a string with the entire contents of the indicated subfile.

Fills a pvector with the entire contents of the indicated subfile.

void remove_subfile(int index)

bool remove_subfile(std::string const &subfile_name)

Removes the named subfile from the ZipArchive, if it exists; returns true if successfully removed, or false if it did not exist in the first place. The file will not actually be removed from the disk until the next call to flush().

Note that this does not actually remove the data from the indicated subfile; it simply removes it from the index. The ZipArchive will not be reduced in size after this operation, until the next call to repack().

Removes the nth subfile from the ZipArchive. This will cause all subsequent index numbers to decrease by one. The file will not actually be removed from the disk until the next call to flush().

Note that this does not actually remove the data from the indicated subfile; it simply removes it from the index. The ZipArchive will not be reduced in size after this operation, until the next call to repack().

bool repack(void)

Forces a complete rewrite of the ZipArchive and all of its contents, so that the files are tightly packed in the file without any gaps. This is useful to do after removing files, to ensure that the file size is minimized.

It is only valid to call this if the ZipArchive was opened using open_read_write() and an explicit filename, rather than an iostream. Also, we must have write permission to the directory containing the ZipArchive.

Returns true on success, false on failure.

bool scan_directory(vector_string &contents, std::string const &subfile_name) const

Considers subfile_name to be the name of a subdirectory within the ZipArchive, but not a file itself; fills the given vector up with the sorted list of subdirectories or files within the named directory.

Note that directories do not exist explicitly within a ZipArchive; this just checks for the existence of files with the given initial prefix.

Returns true if successful, false otherwise.

void set_comment(std::string const &comment)

Sets the string which is appended to the very end of the ZIP archive. This string may not be longer than 65535 characters.

void set_filename(Filename const &filename)

Replaces the filename of the ZipArchive. This is primarily used for documentation purposes only; changing this name does not open the indicated file. See open_read() or open_write() for that.

void set_record_timestamp(bool record_timestamp)

Sets the flag indicating whether timestamps should be recorded within the ZipArchive or not. The default is true, indicating the ZipArchive will record timestamps for each subfile that is added.

If this is false, the ZipArchive will not record timestamps internally. In this case, the return value from get_subfile_timestamp() will be zero.

You may want to set this false to minimize the bitwise difference between independently-generated ZipArchives.

std::string update_subfile(std::string const &subfile_name, Filename const &filename, int compression_level)

Adds a file on disk to the subfile. If a subfile already exists with the same name, its contents are compared byte-for-byte to the disk file, and it is replaced only if it is different; otherwise, the ZIP file is left unchanged.

Either Filename:::set_binary() or set_text() must have been called previously to specify the nature of the source file. If set_text() was called, the text flag will be set on the subfile.

bool verify(void)

Verifies the integrity of the contents of the ZIP archive.