Zip::ZipArchive Class Reference [Zip Code]

#include <zipArchive.h>

Detailed Description

Class for accessing Zip files.

ZipArchive provides two interfaces for reading or writing zip files. The first is a stream based interface that should be familiar to anyone who's ever written code, and the other is an archiver interface that should be familiar to anyone who's ever used a standard Zip application.

The two interfaces are not mutually exclusive so you can use both if you wish. For example, you may want to use the stream interface to add a configuration file to a zip without having to create a temporary file and then add a number of existing files using the addFile() method.

Both interfaces have their advantages and disadvantages, which will be discussed below.

Accessing a Zip file

Before you can access any files in the zip, you first need to open the archive. This is the same regardless of which interface you use, and there are two ways to accomplish it.

Opening from a file on the file system

The simplest method of opening a zip file is to use openArchive(const char *, AccessMode) to open a file that is on the disk.

When opening a zip file on the file system, the filename is automatically set.

Opening a file from a stream

A more advanced way to open the zip file is from an arbitrary stream. The only requirements are that the stream supports seeking and was opened with the correct access mode. Use the openArchive(Stream *, AccessMode) method to do this.

Opening zip files from arbitrary streams is a very powerful feature and opens many interesting doors. For example, combined with some small changes to the resource manager and startup code, it was possible to implement a VFS that allows the entire game to run from a single executable with no external files.

Note that the filename is not automatically set when you open the zip file from a stream. The filename is used in error reporting and by the resource manager, so you may wish to set it to something meaningful.

Regardless of which method you use to open the file, the AccessMode controls what you can do with it. If you open the archive as ReadWrite, you can both write to and read from files in the zip. However, it is not possible to open files in the zip as ReadWrite.

Closing the zip file

When you are done with the zip file, call closeArchive() to free any resources and rebuild the zip file if it was open for Write.

Example

 Zip::ZipArchive za;
 if(za.openArchive("filename.zip", ZipArchive::Read))
 {
    // ... do stuff ...
    za.closeArchive();
 }

Archiver Interface

The archiver style interface allows you to add, extract and delete files in the zip in a way similar to that of an standard archiver application.

While the archiver interface is simple to use, it is blocking and thus difficult to use asynchronously. If you require zip file support and responsive UI then you should consider using the stream interface instead.

See the following method documentation for more information:

Example

 Zip::ZipArchive za;
 if(za.openArchive("filename.zip", ZipArchive::ReadWrite))
 {
    // Extract a file
    za.extractFile("test.txt", "test.txt");
    // Add a file
    za.addFile("test.txt", "test.txt");
    // Delete a file
    za.deleteFile("test.txt");

    za.closeArchive();
 }

Stream Interface

The stream based interface allows you to access files within the zip in a similar way to accessing the file system through the ResourceManager.

There are a few small caveats to the stream interface:

When writing files, the whole file must be written sequentially. You cannot seek in the stream.
It may or may not be possible to seek in streams opened for read. Files that were not compressed in the zip file support seeking with no penalty. In all cases where the file is compressed, if seeking is supported by the decompression and/or decryption filter then it carries with it an extreme performance penalty and should be avoided. All currently available decompression filters (Deflate and BZip2) and decryption filters (Zip 2.0 and AES) support seeking, but have to reset their state and re-decompress/decrypt the entire file up to the point you are seeking to. An extreme example would be that if you had a 20MB file and were currently at the end of the file, seeking back 1 byte of the file would cause the entire file to be decompressed again. This would be a blocking operation that would lock Torque up for an appreciable chunk of time.
Files can only be open as Read or Write, but not ReadWrite
Only one file can be open for read at a time, but multiple files can be open for write at a time. - [tom, 2/9/2007] Check this

See the following method documentation for more information:

CRC Checking

Unlike the archiver interface, there is no automatic CRC checking when reading from files using the stream interface. If you will only be reading files sequentially, see the documentation for ZipStatFilter for a useful trick to get easy CRC checking.

Example

 Zip::ZipArchive za;
 if(za.openArchive("filename.zip", ZipArchive::Write))
 {
    // Write to the file
    Stream *stream;
    if(stream = za.openFile("test.txt", ZipArchive::Write))
    {
       stream->writeLine((U8 *)"Hello, Zipped World!");
       za.closeFile(stream);
    }

    za.closeArchive();
 }

Compressed Files

The zip code included with stock Torque supports "stored" (uncompressed) files and deflate compressed files. The code is easily extensible to support any compression format that the Zip file format supports.

In addition to the deflate and stored formats, BZip2 is supported but not included with stock Torque. BZip2 support will be released as a resource in the future.

Encrypted Files

Preliminary support for Encrypted/Passworded files is included in TGB Pro only. Currently, only Zip 2.0 encryption is supported by the stock code. AES support exists and may be released as a resource in the future.

To set the password used for zips, you need to modify the DEFAULT_ZIP_PASSWORD define in core/zip/zipArchive.h. This password will be used for all zips that require a password. The default password is changeme. This may be used by TGB Binary users to test encrypted zips with their game. Shipping with the default password is not recommended for obvious reasons.

The intended use of encrypted zips is for preventing casual copying of your game's assets. Zip 2.0 encryption has known weaknesses that allow an attacker to decrypt the contents of the zip. AES encryption is significantly more secure, but as the password must be stored in the executable it will not stop a determined attacker.

A script accessible mechanism for setting the password does not currently exist. To use encrypted mod zips, if the password was in script then the password would be clearly visible to anyone that cared to poke around in your scripts.

Encrypted zip support will be improved in a future version. For now, a more secure method of storing the password is left as an exercise for the reader.

Accessing Zip files from script

ZipArchive is a C++ class and thus cannot be used from script. However, a wrapper is provided to allow script access to zips. See the documentation on ZipObject for more information.

More Examples

More in depth example code than that featured here can be found in the unit tests for the zip code (in the core/zip/unitTests directory) and the script code for the packaging utility.

Public Types

Read = Torque::FS::File::Read

Open a zip or file in a zip for reading.

Write = Torque::FS::File::Write

Open a zip or file in a zip for writing.

ReadWrite = Torque::FS::File::ReadWrite

Open a zip file for reading and writing. Note: Not valid for files in zips.

enum AccessMode {
  Read = Torque::FS::File::Read,
  Write = Torque::FS::File::Write,
  ReadWrite = Torque::FS::File::ReadWrite
}

Access modes for zip files and files within the zip. More...

Public Member Functions

ZipArchive ()

virtual ~ZipArchive ()

Miscellaneous Methods

void setFilename (const char *filename)

Set the filename of the zip file.

const char * getFilename ()

Get the filename of the zip file.

bool isVerbose ()

Determine if the Zip code is in verbose mode.

void setVerbose (bool verbose)

Turn verbose mode on or off.

Archive Access Methods

virtual bool openArchive (const char *filename, AccessMode mode=Read)

Open a zip archive from a file.

virtual bool openArchive (Stream *stream, AccessMode mode=Read)

Open a zip archive from a stream.

virtual void closeArchive ()

Close the zip archive and free any resources.

Stream Based File Access Methods

virtual Stream * openFile (const char *filename, AccessMode mode=Read)

Open a file within the zip file.

virtual void closeFile (Stream *stream)

Close a file opened through openFile().

Stream * openFileForRead (const CentralDir *fileCD)

Open a file within the zip file for read.

Archiver Style File Access Methods

bool addFile (const char *filename, const char *pathInZip, bool replace=true)

Add a file to the zip.

bool extractFile (const char *pathInZip, const char *filename, bool *crcFail=NULL)

Extract a file from the zip.

bool deleteFile (const char *filename)

Delete a file from the zip.

Enumeration Methods

U32 numEntries () const

Get number of entries in the central directory.

const CentralDir & operator[] (const U32 idx) const

Get a central directory entry.

CentralDir * findFileInfo (const char *filename)

Find a file in the zip.

Protected Member Functions

bool readCentralDirectory ()

void insertEntry (ZipEntry *ze)

void removeEntry (ZipEntry *ze)

ZipEntry * findZipEntry (const char *filename)

Stream * createNewFile (const char *filename, Compressor *method)

Stream * createNewFile (const char *filename, const char *method)

Stream * createNewFile (const char *filename, S32 method)

void updateFile (ZipTempStream *stream)

bool rebuildZip ()

bool copyFileToNewZip (CentralDir *cdir, Stream *newZipStream)

bool writeDirtyFileToNewZip (ZipTempStream *fileStream, Stream *zipStream)

U32 localTimeToDOSTime (const Platform::LocalTime &t)

U32 currentTimeToDOSTime ()

Protected Attributes

Stream * mStream

FileStream * mDiskStream

AccessMode mMode

EndOfCentralDir mEOCD

ZipEntry * mRoot

VectorPtr< ZipEntry * > mEntries

const char * mFilename

VectorPtr< ZipTempStream * > mTempFiles

Friends

class ::ZipTestWrite

class ::ZipTestRead

class ::ZipTestMisc

Classes

struct ZipEntry

Member Enumeration Documentation

enum Zip::ZipArchive::AccessMode

Access modes for zip files and files within the zip.

Enumerator:

Read	Open a zip or file in a zip for reading.
Write	Open a zip or file in a zip for writing.
ReadWrite	Open a zip file for reading and writing. Note: Not valid for files in zips.

Constructor & Destructor Documentation

Zip::ZipArchive::ZipArchive ( )

virtual Zip::ZipArchive::~ZipArchive ( ) [virtual]

Member Function Documentation

bool Zip::ZipArchive::readCentralDirectory ( ) [protected]

void Zip::ZipArchive::insertEntry ( ZipEntry * ze ) [protected]

void Zip::ZipArchive::removeEntry ( ZipEntry * ze ) [protected]

ZipEntry* Zip::ZipArchive::findZipEntry ( const char * filename ) [protected]

Stream* Zip::ZipArchive::createNewFile	(	const char *	filename,
		Compressor *	method
	)			`[protected]`

Stream* Zip::ZipArchive::createNewFile	(	const char *	filename,
		const char *	method
	)			`[inline, protected]`

Stream* Zip::ZipArchive::createNewFile	(	const char *	filename,
		S32	method
	)			`[inline, protected]`

void Zip::ZipArchive::updateFile ( ZipTempStream * stream ) [protected]

bool Zip::ZipArchive::rebuildZip ( ) [protected]

bool Zip::ZipArchive::copyFileToNewZip	(	CentralDir *	cdir,
		Stream *	newZipStream
	)			`[protected]`

bool Zip::ZipArchive::writeDirtyFileToNewZip	(	ZipTempStream *	fileStream,
		Stream *	zipStream
	)			`[protected]`

U32 Zip::ZipArchive::localTimeToDOSTime ( const Platform::LocalTime & t ) [protected]

U32 Zip::ZipArchive::currentTimeToDOSTime ( ) [protected]

void Zip::ZipArchive::setFilename ( const char * filename )

Set the filename of the zip file.

The zip filename is used by the resource manager and for error reporting.

Note: The filename is set automatically when you open the file.

Parameters:

filename

Filename of the zip file

const char* Zip::ZipArchive::getFilename ( ) [inline]

Get the filename of the zip file.

Returns:: Filename of the zip file, or NULL if none set

bool Zip::ZipArchive::isVerbose ( )

Determine if the Zip code is in verbose mode.

Verbose mode causes the Zip code to provide diagnostic error messages when things go wrong. It can be enabled or disabled through script by setting the $Pref::Zip::Verbose variable to true to enable it or false to disable it.

Verbose mode is mostly useful when tracking down issues with opening a zip file without having to resort to using a debugger.

Returns:: The value of $Pref::Zip::Verbose

See also:: ZipArchive::setVerbose()

void Zip::ZipArchive::setVerbose ( bool verbose )

Turn verbose mode on or off.

This sets the $Pref::Zip::Verbose variable.

See isVerbose() for a discussion on verbose mode.

Parameters:

verbose

True to enable verbose mode, false to disable

See also:: ZipArchive::isVerbose()

virtual bool Zip::ZipArchive::openArchive	(	const char *	filename,
		AccessMode	mode = `Read`
	)			`[virtual]`

Open a zip archive from a file.

The archive must be closed with closeArchive() when you are done with it.

Parameters:

	filename	Filename of zip file to open
	mode	Access mode. May be Read, Write or ReadWrite

Returns:: true for success, false for failure

See also:: ZipArchive::openArchive(Stream *, AccessMode), ZipArchive::closeArchive()

virtual bool Zip::ZipArchive::openArchive	(	Stream *	stream,
		AccessMode	mode = `Read`
	)			`[virtual]`

Open a zip archive from a stream.

The stream must support seeking and must support the specified access mode. For example, if the stream is opened for Read you cannot specify Write to openArchive(). However, if the stream is open for ReadWrite then you can specify any one of Read, Write or ReadWrite as the mode argument to openArchive().

The archive must be closed with closeArchive() when you are done with it.

Parameters:

	stream	Pointer to stream to open the zip archive from
	mode	Access mode. May be Read, Write or ReadWrite

Returns:: true for success, false for failure

See also:: ZipArchive::openArchive(const char *, AccessMode), ZipArchive::closeArchive()

virtual void Zip::ZipArchive::closeArchive ( ) [virtual]

Close the zip archive and free any resources.

See also:: ZipArchive::openArchive(Stream *, AccessMode), ZipArchive::openArchive(const char *, AccessMode)

virtual Stream* Zip::ZipArchive::openFile	(	const char *	filename,
		AccessMode	mode = `Read`
	)			`[virtual]`

Open a file within the zip file.

The access mode can only be Read or Write. It is not possible to open a file within the zip as ReadWrite.

The returned stream must be freed with closeFile(). Do not delete it directly.

In verbose mode, openFile() will display additional error information in the console when it fails.

Parameters:

	filename	Filename of the file in the zip
	mode	Access mode. May be Read or Write

Returns:: Pointer to stream or NULL for failure

See also:: ZipArchive::closeFile(), ZipArchive::isVerbose()

virtual void Zip::ZipArchive::closeFile ( Stream * stream ) [virtual]

Close a file opened through openFile().

Parameters:

stream

Stream to close

See also:: ZipArchive::openFile(const char *, AccessMode)

Stream* Zip::ZipArchive::openFileForRead ( const CentralDir * fileCD )

Open a file within the zip file for read.

This method exists mainly for the integration with the resource manager. Unless there is good reason to use this method, it is better to use the openFile() method instead.

Parameters:

fileCD

Pointer to central directory of the file to open

Returns:: Pointer to stream or NULL for failure

See also:: ZipArchive::openFile(const char *, AccessMode), ZipArchive::closeFile()

bool Zip::ZipArchive::addFile	(	const char *	filename,
		const char *	pathInZip,
		bool	replace = `true`
	)

Add a file to the zip.

If replace is false and the file already exists in the zip, this function will fail and return false. If replace is true, the existing file will be overwritten.

Parameters:

	filename	Filename on the local file system to add
	pathInZip	The path and filename in the zip file to give this file
	replace	true to replace existing files, false otherwise

Returns:: true for success, false for failure

See also:: ZipArchive::extractFile(), ZipArchive::deleteFile(), ZipArchive::isVerbose()

bool Zip::ZipArchive::extractFile	(	const char *	pathInZip,
		const char *	filename,
		bool *	crcFail = `NULL`
	)

Extract a file from the zip.

The file will be created through the resource manager and so must be in a location that is writable.

The file will be CRC checked during extraction and extractFile() will return false if the CRC check failed. The CRC check is just an advisory, the output file will still exist if the CRC check failed. It is up to the caller to decide what to do in the event of a CRC failure.

You can optionally pass a pointer to a bool to determine if a CRC check failed. If extractFile() returns false and crcFail is false then the failure was not CRC related. If crcFail is true and extractFile() returns false, then the CRC check failed but the file otherwise extracted OK. You can take your chances as to whether the data is valid or not, if you wish.

In verbose mode, extractFile() will display an error in the console when a file fails the CRC check.

Parameters:

	pathInZip	The path and filename in the zip file to extract
	filename	Filename on the local file system to extract to
	crcFail	Pointer to a boolean that receives the result of the CRC check