A file inside ZIP archive. More...

#include <quazip/quazipfile.h>

Collaboration diagram for QuaZipFile:

Public Member Functions
	QuaZipFile ()
	Constructs a QuaZipFile instance.
	QuaZipFile (QObject *parent)
	Constructs a QuaZipFile instance.
	QuaZipFile (const QString &zipName, QObject *parent=NULL)
	Constructs a QuaZipFile instance.
	QuaZipFile (const QString &zipName, const QString &fileName, QuaZip::CaseSensitivity cs=QuaZip::csDefault, QObject *parent=NULL)
	Constructs a QuaZipFile instance.
	QuaZipFile (QuaZip zip, QObject parent=NULL)
	Constructs a QuaZipFile instance.
virtual	~QuaZipFile ()
	Destroys a QuaZipFile instance.
QString	getZipName () const
	Returns the ZIP archive file name.
QuaZip *	getZip () const
	Returns a pointer to the associated QuaZip object.
QString	getFileName () const
	Returns file name.
QuaZip::CaseSensitivity	getCaseSensitivity () const
	Returns case sensitivity of the file name.
QString	getActualFileName () const
	Returns the actual file name in the archive.
void	setZipName (const QString &zipName)
	Sets the ZIP archive file name.
bool	isRaw () const
	Returns `true` if the file was opened in raw mode.
void	setZip (QuaZip *zip)
	Binds to the existing QuaZip instance.
void	setFileName (const QString &fileName, QuaZip::CaseSensitivity cs=QuaZip::csDefault)
	Sets the file name.
virtual bool	open (OpenMode mode)
	Opens a file for reading.
bool	open (OpenMode mode, const char *password)
	Opens a file for reading.
bool	open (OpenMode mode, int method, int level, bool raw, const char *password=NULL)
	Opens a file for reading.
bool	open (OpenMode mode, const QuaZipNewInfo &info, const char *password=NULL, quint32 crc=0, int method=Z_DEFLATED, int level=Z_DEFAULT_COMPRESSION, bool raw=false, int windowBits=-MAX_WBITS, int memLevel=DEF_MEM_LEVEL, int strategy=Z_DEFAULT_STRATEGY)
	Opens a file for writing.
virtual bool	isSequential () const
	Returns `true`, but beware!
virtual qint64	pos () const
	Returns current position in the file.
virtual bool	atEnd () const
	Returns `true` if the end of file was reached.
virtual qint64	size () const
	Returns file size.
qint64	csize () const
	Returns compressed file size.
qint64	usize () const
	Returns uncompressed file size.
bool	getFileInfo (QuaZipFileInfo *info)
	Gets information about current file.
bool	getFileInfo (QuaZipFileInfo64 *info)
	Gets information about current file with zip64 support.
virtual void	close ()
	Closes the file.
int	getZipError () const
	Returns the error code returned by the last ZIP/UNZIP API call.
virtual qint64	bytesAvailable () const
	Returns the number of bytes available for reading.
Protected Member Functions
qint64	readData (char *data, qint64 maxSize)
	Implementation of the QIODevice::readData().
qint64	writeData (const char *data, qint64 maxSize)
	Implementation of the QIODevice::writeData().
Friends
class	QuaZipFilePrivate

Detailed Description

A file inside ZIP archive.

This is the most interesting class. Not only it provides C++ interface to the ZIP/UNZIP package, but also integrates it with Qt by subclassing QIODevice. This makes possible to access files inside ZIP archive using QTextStream or QDataStream, for example. Actually, this is the main purpose of the whole QuaZIP library.

You can either use existing QuaZip instance to create instance of this class or pass ZIP archive file name to this class, in which case it will create internal QuaZip object. See constructors' descriptions for details. Writing is only possible with the existing instance.

Note that due to the underlying library's limitation it is not possible to use multiple QuaZipFile instances to open several files in the same archive at the same time. If you need to write to multiple files in parallel, then you should write to temporary files first, then pack them all at once when you have finished writing. If you need to read multiple files inside the same archive in parallel, you should extract them all into a temporary directory first.

Sequential or random-access?

At the first thought, QuaZipFile has fixed size, the start and the end and should be therefore considered random-access device. But there is one major obstacle to making it random-access: ZIP/UNZIP API does not support seek() operation and the only way to implement it is through reopening the file and re-reading to the required position, but this is prohibitively slow.

Therefore, QuaZipFile is considered to be a sequential device. This has advantage of availability of the ungetChar() operation (QIODevice does not implement it properly for non-sequential devices unless they support seek()). Disadvantage is a somewhat strange behaviour of the size() and pos() functions. This should be kept in mind while using this class.

Constructor & Destructor Documentation

QuaZipFile::QuaZipFile ( )

Constructs a QuaZipFile instance.

You should use setZipName() and setFileName() or setZip() before trying to call open() on the constructed object.

QuaZipFile::QuaZipFile ( QObject * parent )

Constructs a QuaZipFile instance.

parent argument specifies this object's parent object.

You should use setZipName() and setFileName() or setZip() before trying to call open() on the constructed object.

QuaZipFile::QuaZipFile	(	const QString &	zipName,
		QObject *	parent = `NULL`
	)

Constructs a QuaZipFile instance.

parent argument specifies this object's parent object and zipName specifies ZIP archive file name.

You should use setFileName() before trying to call open() on the constructed object.

QuaZipFile constructed by this constructor can be used for read only access. Use QuaZipFile(QuaZip*,QObject*) for writing.

QuaZipFile::QuaZipFile	(	const QString &	zipName,
		const QString &	fileName,
		QuaZip::CaseSensitivity	cs = `QuaZip::csDefault`,
		QObject *	parent = `NULL`
	)

Constructs a QuaZipFile instance.

parent argument specifies this object's parent object, zipName specifies ZIP archive file name and fileName and cs specify a name of the file to open inside archive.

QuaZipFile constructed by this constructor can be used for read only access. Use QuaZipFile(QuaZip*,QObject*) for writing.

See also:: QuaZip::setCurrentFile()

QuaZipFile::QuaZipFile	(	QuaZip *	zip,
		QObject *	parent = `NULL`
	)

Constructs a QuaZipFile instance.

parent argument specifies this object's parent object.

zip is the pointer to the existing QuaZip object. This QuaZipFile object then can be used to read current file in the zip or to write to the file inside it.

Warning:

Using this constructor for reading current file can be tricky. Let's take the following example:

 QuaZip zip("archive.zip");
 zip.open(QuaZip::mdUnzip);
 zip.setCurrentFile("file-in-archive");
 QuaZipFile file(&zip);
 file.open(QIODevice::ReadOnly);
 // ok, now we can read from the file
 file.read(somewhere, some);
 zip.setCurrentFile("another-file-in-archive"); // oops...
 QuaZipFile anotherFile(&zip);
 anotherFile.open(QIODevice::ReadOnly);
 anotherFile.read(somewhere, some); // this is still ok...
 file.read(somewhere, some); // and this is NOT

So, what exactly happens here? When we change current file in the zip archive, file that references it becomes invalid (actually, as far as I understand ZIP/UNZIP sources, it becomes closed, but QuaZipFile has no means to detect it).

Summary: do not close zip object or change its current file as long as QuaZipFile is open. Even better - use another constructors which create internal QuaZip instances, one per object, and therefore do not cause unnecessary trouble. This constructor may be useful, though, if you already have a QuaZip instance and do not want to access several files at once. Good example:

 QuaZip zip("archive.zip");
 zip.open(QuaZip::mdUnzip);
 // first, we need some information about archive itself
 QByteArray comment=zip.getComment();
 // and now we are going to access files inside it
 QuaZipFile file(&zip);
 for(bool more=zip.goToFirstFile(); more; more=zip.goToNextFile()) {
   file.open(QIODevice::ReadOnly);
   // do something cool with file here
   file.close(); // do not forget to close!
 }
 zip.close();

QuaZipFile::~QuaZipFile ( ) [virtual]

Destroys a QuaZipFile instance.

Closes file if open, destructs internal QuaZip object (if it exists and is internal, of course).

References close().

Member Function Documentation

QString QuaZipFile::getZipName ( ) const

Returns the ZIP archive file name.

If this object was created by passing QuaZip pointer to the constructor, this function will return that QuaZip's file name (or null string if that object does not have file name yet).

Otherwise, returns associated ZIP archive file name or null string if there are no name set yet.

See also:: setZipName() getFileName()

References QuaZip::getZipName().

QuaZip * QuaZipFile::getZip ( ) const

Returns a pointer to the associated QuaZip object.

Returns NULL if there is no associated QuaZip or it is internal (so you will not mess with it).

QString QuaZipFile::getFileName ( ) const

Returns file name.

This function returns file name you passed to this object either by using QuaZipFile(const QString&,const QString&,QuaZip::CaseSensitivity,QObject*) or by calling setFileName(). Real name of the file may differ in case if you used case-insensitivity.

Returns null string if there is no file name set yet. This is the case when this QuaZipFile operates on the existing QuaZip object (constructor QuaZipFile(QuaZip*,QObject*) or setZip() was used).

See also:: getActualFileName

QuaZip::CaseSensitivity QuaZipFile::getCaseSensitivity ( ) const

Returns case sensitivity of the file name.

This function returns case sensitivity argument you passed to this object either by using QuaZipFile(const QString&,const QString&,QuaZip::CaseSensitivity,QObject*) or by calling setFileName().

Returns unpredictable value if getFileName() returns null string (this is the case when you did not used setFileName() or constructor above).

See also:: getFileName

QString QuaZipFile::getActualFileName ( ) const

Returns the actual file name in the archive.

This is not a ZIP archive file name, but a name of file inside archive. It is not necessary the same name that you have passed to the QuaZipFile(const QString&,const QString&,QuaZip::CaseSensitivity,QObject*), setFileName() or QuaZip::setCurrentFile() - this is the real file name inside archive, so it may differ in case if the file name search was case-insensitive.

Equivalent to calling getCurrentFileName() on the associated QuaZip object. Returns null string if there is no associated QuaZip object or if it does not have a current file yet. And this is the case if you called setFileName() but did not open the file yet. So this is perfectly fine:

 QuaZipFile file("somezip.zip");
 file.setFileName("somefile");
 QString name=file.getName(); // name=="somefile"
 QString actual=file.getActualFileName(); // actual is null string
 file.open(QIODevice::ReadOnly);
 QString actual=file.getActualFileName(); // actual can be "SoMeFiLe" on Windows

See also:: getZipName(), getFileName(), QuaZip::CaseSensitivity

References QuaZip::getCurrentFileName(), and QuaZip::getZipError().

void QuaZipFile::setZipName ( const QString & zipName )

Sets the ZIP archive file name.

Automatically creates internal QuaZip object and destroys previously created internal QuaZip object, if any.

Will do nothing if this file is already open. You must close() it first.

bool QuaZipFile::isRaw ( ) const

Returns true if the file was opened in raw mode.

If the file is not open, the returned value is undefined.

See also:: open(OpenMode,int*,int*,bool,const char*)

Referenced by close().

void QuaZipFile::setZip ( QuaZip * zip )

Binds to the existing QuaZip instance.

This function destroys internal QuaZip object, if any, and makes this QuaZipFile to use current file in the zip object for any further operations. See QuaZipFile(QuaZip*,QObject*) for the possible pitfalls.

Will do nothing if the file is currently open. You must close() it first.

void QuaZipFile::setFileName	(	const QString &	fileName,
		QuaZip::CaseSensitivity	cs = `QuaZip::csDefault`
	)

Sets the file name.

Will do nothing if at least one of the following conditions is met:

ZIP name has not been set yet (getZipName() returns null string).
This QuaZipFile is associated with external QuaZip. In this case you should call that QuaZip's setCurrentFile() function instead!
File is already open so setting the name is meaningless.

See also:: QuaZip::setCurrentFile

bool QuaZipFile::open ( OpenMode mode ) [virtual]

Opens a file for reading.

Returns true on success, false otherwise. Call getZipError() to get error code.

Note:: Since ZIP/UNZIP API provides buffered reading only, QuaZipFile does not support unbuffered reading. So do not pass QIODevice::Unbuffered flag in mode, or open will fail.

bool QuaZipFile::open	(	OpenMode	mode,
		const char *	password
	)		`[inline]`

Opens a file for reading.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Argument password specifies a password to decrypt the file. If it is NULL then this function behaves just like open(OpenMode).

References open().

Referenced by open().

bool QuaZipFile::open	(	OpenMode	mode,
		int *	method,
		int *	level,
		bool	raw,
		const char *	password = `NULL`
	)

Opens a file for reading.

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Argument password specifies a password to decrypt the file.

An integers pointed by method and level will receive codes of the compression method and level used. See unzip.h.

If raw is true then no decompression is performed.

method should not be NULL. level can be NULL if you don't want to know the compression level.

References QuaZip::close(), QuaZip::getMode(), QuaZip::getUnzFile(), QuaZip::getZipError(), QuaZip::hasCurrentFile(), QuaZip::mdUnzip, QuaZip::open(), and QuaZip::setCurrentFile().

bool QuaZipFile::open	(	OpenMode	mode,
		const QuaZipNewInfo &	info,
		const char *	password = `NULL`,
		quint32	crc = `0`,
		int	method = `Z_DEFLATED`,
		int	level = `Z_DEFAULT_COMPRESSION`,
		bool	raw = `false`,
		int	windowBits = `-MAX_WBITS`,
		int	memLevel = `DEF_MEM_LEVEL`,
		int	strategy = `Z_DEFAULT_STRATEGY`
	)

Opens a file for writing.

info argument specifies information about file. It should at least specify a correct file name. Also, it is a good idea to specify correct timestamp (by default, current time will be used). See QuaZipNewInfo.

The password argument specifies the password for crypting. Pass NULL if you don't need any crypting. The crc argument was supposed to be used for crypting too, but then it turned out that it's false information, so you need to set it to 0 unless you want to use the raw mode (see below).

Arguments method and level specify compression method and level. The only method supported is Z_DEFLATED, but you may also specify 0 for no compression. If all of the files in the archive use both method 0 and either level 0 is explicitly specified or data descriptor writing is disabled with QuaZip::setDataDescriptorWritingEnabled(), then the resulting archive is supposed to be compatible with the 1.0 ZIP format version, should you need that. Except for this, level has no other effects with method 0.

If raw is true, no compression is performed. In this case, crc and uncompressedSize field of the info are required.

Arguments windowBits, memLevel, strategy provide zlib algorithms tuning. See deflateInit2() in zlib.

References QuaZipNewInfo::comment, QuaZipNewInfo::dateTime, QuaZipNewInfo::externalAttr, QuaZipNewInfo::extraGlobal, QuaZipNewInfo::extraLocal, QuaZip::getCommentCodec(), QuaZip::getFileNameCodec(), QuaZip::getMode(), QuaZip::getZipFile(), QuaZipNewInfo::internalAttr, QuaZip::isDataDescriptorWritingEnabled(), QuaZip::isZip64Enabled(), QuaZip::mdAdd, QuaZip::mdAppend, QuaZip::mdCreate, QuaZipNewInfo::name, and QuaZipNewInfo::uncompressedSize.

qint64 QuaZipFile::pos ( ) const [virtual]

Returns current position in the file.

Implementation of the QIODevice::pos(). When reading, this function is a wrapper to the ZIP/UNZIP unztell(), therefore it is unable to keep track of the ungetChar() calls (which is non-virtual and therefore is dangerous to reimplement). So if you are using ungetChar() feature of the QIODevice, this function reports incorrect value until you get back characters which you ungot.

When writing, pos() returns number of bytes already written (uncompressed unless you use raw mode).

Note:: Although QuaZipFile is a sequential device and therefore pos() should always return zero, it does not, because it would be misguiding. Keep this in mind.

This function returns -1 if the file or archive is not open.

Error code returned by getZipError() is not affected by this function call.

References QuaZip::getUnzFile().

Referenced by bytesAvailable().

bool QuaZipFile::atEnd ( ) const [virtual]

Returns true if the end of file was reached.

This function returns false in the case of error. This means that you called this function on either not open file, or a file in the not open archive or even on a QuaZipFile instance that does not even have QuaZip instance associated. Do not do that because there is no means to determine whether false is returned because of error or because end of file was reached. Well, on the other side you may interpret false return value as "there is no file open to check for end of file and there is no end of file therefore".

When writing, this function always returns true (because you are always writing to the end of file).

Error code returned by getZipError() is not affected by this function call.

References bytesAvailable(), and QuaZip::getUnzFile().

qint64 QuaZipFile::size ( ) const [virtual]

Returns file size.

This function returns csize() if the file is open for reading in raw mode, usize() if it is open for reading in normal mode and pos() if it is open for writing.

Returns -1 on error, call getZipError() to get error code.

Note:: This function returns file size despite that QuaZipFile is considered to be sequential device, for which size() should return bytesAvailable() instead. But its name would be very misguiding otherwise, so just keep in mind this inconsistence.

References csize(), and usize().

Referenced by bytesAvailable().

qint64 QuaZipFile::csize ( ) const

Returns compressed file size.

Equivalent to calling getFileInfo() and then getting compressedSize field, but more convenient and faster.

File must be open for reading before calling this function.

Returns -1 on error, call getZipError() to get error code.

References QuaZip::getMode(), QuaZip::getUnzFile(), and QuaZip::mdUnzip.

Referenced by size().

qint64 QuaZipFile::usize ( ) const

Returns uncompressed file size.

Equivalent to calling getFileInfo() and then getting uncompressedSize field, but more convenient and faster. See getFileInfo() for a warning.

File must be open for reading before calling this function.

Returns -1 on error, call getZipError() to get error code.

References QuaZip::getMode(), QuaZip::getUnzFile(), and QuaZip::mdUnzip.

Referenced by size().

bool QuaZipFile::getFileInfo ( QuaZipFileInfo * info )

Gets information about current file.

This function does the same thing as calling QuaZip::getCurrentFileInfo() on the associated QuaZip object, but you can not call getCurrentFileInfo() if the associated QuaZip is internal (because you do not have access to it), while you still can call this function in that case.

File must be open for reading before calling this function.

Returns:: false in the case of an error.

This function doesn't support zip64, but will still work fine on zip64 archives if file sizes are below 4 GB, otherwise the values will be set as if converted using QuaZipFileInfo64::toQuaZipFileInfo().