QuaZIP 0.7.2文档翻译：QuaZipFile类参考,QuaZipFile Class Reference

ZIP 压缩 包中的一个文件。 详细说明……

#include < quazip/quazipfile.h >

详细说明

这是最有趣的那个类。 它不仅提供了针对ZIP/UNZIP 软件包的C++接口，还通过子类化 QIODevice 来与 Qt 整合了。 这就使得，妳可以利用 QTextStream 或 QDataStream 来访问到ZIP 压缩包中的文件。事实 上，这就是造出QuaZIP 库的主要目的。

妳可以使用已有的 QuaZip 实例来创建本类的实例，或者 向本类传递ZIP 压缩包文件名来进行创建，在第二种方法中，它会创建内部的 QuaZip 对象。阅读构造函数文档 以了解细节。只有使用已有实例 来创建时，才可以进行写入操作。

注意 ，由于底层库的限制， 同一时刻，对于同一个压缩包，无法使用多个 QuaZipFile 实例来打开多个文件。 如果妳需要同时向多个文件中写入内容的话，那么，应当首先写入 到临时文件中，在写入完毕之后再将它们一次性打包起来。如果 妳想同时读取同一个压缩包中的多个文件，那么，应当将它们提取到某个临时目录中。

顺序访问还是随机访问？

乍一想， QuaZipFile 本身拥有固定的尺寸，也拥有确定的开始位置和结束位置，因而 ，会认为它应当被当成随机访问的设备。但是 ，有一个较大的障碍使得它不能成为随机访问的设备： ZIP/UNZIP API 并不支持寻址（ seek() ）操作，因而 ，实现这个功能的唯一途径就是，重新打开文件 ，并重新读取直到预期的位置，可以想见，这样会狠慢。

因此 ， QuaZipFile 被当成是顺序访问设备。 这样带来另外一个好处，就是，可以进行退字（ ungetChar() ）操作(对于 非顺序访问的设备，除非它们支持 seek() ，否则， QIODevice 对于这个操作的实现是有问题的 )。坏处 就是， size() 和 pos() 函数的行为会有些怪异。 在使用这个类的时候，应当牢记此特征。

构造函数和析构函数文档

构造 一个 QuaZipFile 实例。

在对构造后的对象调用 open() 之前，应当使用 setZipName() 和 setFileName() 或 setZip() 。

构造 一个 QuaZipFile 实例。

parent 参数 ，指定的是这个对象的亲代对象。

在对构造后的对象调用 open() 之前，应当使用 setZipName() 和 setFileName() 或 setZip() 。

构造 一个 QuaZipFile 实例。

parent 参数 ，指定的是这个对象的亲代对象。 zipName 指定的是ZIP 压缩包的文件名。

在对构造后的对象调用 open() 之前，应当使用 setFileName() 。

利用 这个构造函数构造的 QuaZipFile 对象，可用于只读访问。使用 QuaZipFile(QuaZip*,QObject*) 来构造出可进行写入操作的对象。

构造 一个 QuaZipFile 实例。

parent参数 ，指定的是这个对象的亲代对象。 zipName 指定的是ZIP 压缩包的文件名。 fileName 和 cs 指定 的是压缩包中某个要打开的文件的文件名。

利用 这个构造函数构造的 QuaZipFile 对象，可用于只读访问。使用 QuaZipFile(QuaZip*,QObject*) 来构造出可进行写入操作的对象。

参考：

QuaZip::setCurrentFile()

构造 一个 QuaZipFile 实例。

parent参数 ，指定的是这个对象的亲代对象。

zip ，是指向某个已有 QuaZip 对象的指针。 这个 QuaZipFile 对象，就可以用来读取 zip 中的当前文件，或者向文件中写入内容。

警告：

利用这个构造函数来读取当前文件，会有些坑。参考以下示例：

QuaZip zip( "archive.zip" );

zip.open( QuaZip::mdUnzip );

zip.setCurrentFile( "file-in-archive" );

QuaZipFile file(&zip);

file.open(QIODevice::ReadOnly);

// 现在 可以读取文件内容了

file.read(somewhere, some);

zip.setCurrentFile( "another-file-in-archive" ); // 啊 ...

QuaZipFile anotherFile(&zip);

anotherFile.open(QIODevice::ReadOnly);

anotherFile.read(somewhere, some); // 仍然 可以读取 ...

file.read(somewhere, some); // 这一行就 不行 了

那么 ，到底发生了什么？ 当我们改变 了 zip 压缩包中的当前文件时，引用 到上一个当前文件的 file 对象变成无效的了（实际 上，按照我对 ZIP/UNZIP 源代码的理解， 它是被关闭了，但是 QuaZipFile 无法检测到这一点 ）。

总之 ：只要 QuaZipFile 还是处于打开状态，就不要关闭 zip 对象，或者改变它的当前文件。更好 的解决办法是 - 使用 另一个会创建内部 QuaZip 实例的构造函数，并且对于每个对象都用一次这样的构造函数，以避免不必要的麻烦。然而 ，如果妳已经拥有一个 QuaZip 实例，并且不需要同时访问多个文件的话，本个构造函数还是有用的。 正确的例子：

QuaZip zip( "archive.zip" );

zip.open( QuaZip::mdUnzip );

// 首先，需要获取 到某些关于压缩包本身的信息

QByteArray comment=zip.getComment();

// 现在关于访问其中 的文件

QuaZipFile file(&zip);

for ( bool more=zip.goToFirstFile(); more; more=zip.goToNextFile()) {

file.open(QIODevice::ReadOnly);

// 针对file 做某些有意思的操作

file.close(); // 别忘记关闭！

}

zip.close();

销毁 一个 QuaZipFile 实例。

文件处于打开状态 则关闭它，并且销毁内部的 QuaZip 对象(当然 ，前提是它存在并且是内部对象 )。

成员函数文档

如果 此对象是通过传入 QuaZip 指针的构造函数来创建的，那么，此函数会返回那个QuaZip 的文件名(或者 ，如果那个对象还没有文件名的话，则返回无效（ null ）字符串 )。

否则，返回所关联的ZIP 压缩包文件名，或者，尚未设置名字的话则返回无效（null）字符串。

参考：

setZipName() getFileName()

QuaZip  * QuaZipFile::getZip        (  )  const

返回 所关联的 QuaZip 对象的指针。

如果尚未关联 QuaZip ，或者是内部对象( 这种情况下要避免妳弄混淆 )，则返回 NULL 。

这个函数，返回的是，妳之前使用 QuaZipFile(const QString&,const QString&,QuaZip::CaseSensitivity,QObject*) 或 setFileName() 传递给本对象的文件名。如果 妳指定了大小写不敏感选项的话，那么，该文件的真正名字可能会与之前传递的不一样。

如果尚未设置文件 名，则返回无效（null）字符串。如果 这个 QuaZipFile 是针对某个已有 QuaZip 对象(使用 了 QuaZipFile(QuaZip*,QObject*) 或 setZip() )进行操作的，那么，就会出现这种情况。

参考：

getActualFileName

这并不是ZIP 压缩包的文件名，而是指压缩包中某个文件的文件名。 它并不一定 与妳通过 QuaZipFile(const QString&,const QString&,QuaZip::CaseSensitivity,QObject*) 、 setFileName() 或 QuaZip::setCurrentFile() 传递的文件名完全相同  - 它是压缩包中的真正文件名，所以 ，在文件名搜索过程中使用了大小写不敏感选项的情况下是会出现不相同的情况的。

等价于调用所关联的 QuaZip 对象的getCurrentFileName()方法。如果尚未关联 QuaZip 对象 ，或者关联的对象尚未指定当前文件，则返回无效（null）字符串。如果 妳调用了 setFileName() ，而尚未打开该文件，那么也会是这样的返回值。所以 以下代码中的结果是正常的：

QuaZipFile file( "somezip.zip" );

file.setFileName( "somefile" );

QString name=file.getName(); // name=="somefile"

QString actual=file.getActualFileName(); // 实际文件 名是一个无效（null）字符串

file.open(QIODevice::ReadOnly);

QString actual=file.getActualFileName();

参考：

getZipName() 、 getFileName() 、 QuaZip::CaseSensitivity

void QuaZipFile::setZipName (  const  QString  &  zipName        )

设置ZIP 压缩包文件名。

自动创建内部 的 QuaZip 对象，如果之前创建过内部的 QuaZip 对象的话，则销毁之。

如果 此文件已经打开，则什么都不会做。妳必须先关闭（ close() ）它。

void QuaZipFile::setZip ( QuaZip  *  zip        )

绑定 到已有的 QuaZip 实例。

如果已经存在内部 的 QuaZip 对象的话，则会销毁之，然后，使得 这个 QuaZipFile 对象使用 zip 对象中的当前文件，以进行后续的任何操作。参考 QuaZipFile(QuaZip*,QObject*) ，以了解可能存在的坑。

如果 此文件已经打开，则什么都不会做。妳必须先关闭（ close() ）它。

void QuaZipFile::setFileName (  const QString &  fileName,

QuaZip::CaseSensitivity cs = QuaZip::csDefault

 )

设置文件名。

如果存在以下任何一种情况，则什么都不会做：

• •. 尚未设置ZIP 文件 名( getZipName() 返回无效 （ null ） 字符串) 。

• •. 此 QuaZipFile 对象已经关联到某个外部的 QuaZip 。 在这种情况下，妳应当调用那个QuaZip 对象的setCurrentFile()函数！

• •.文件已经被打开，这样的话，设置文件名无意义。

参考：

QuaZip::setCurrentFile

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

打开文件，以便读取。

成功 则返回真（ true ），否则返回假（ false ）。调用 getZipError() 以获取错误码。

注意：

由于ZIP/UNZIP API 只提供了缓冲式读取功能，所以， QuaZipFile 不支持非缓冲式读取功能。所以， 不要在 mode 参数中传入QIODevice::Unbuffered 标志位，否则打开操作会失败。

覆盖 了 QIODevice 中的对应方法。

bool QuaZipFile::open ( OpenMode mode,

 const char *  password

 ) [inline]

打开文件，以便读取。

这是一个重载成员函数，出于便利性考虑而提供。它与上面那个函数的区别仅仅在于接受的参数不同。参数 password ，指定的是，用来解密该文件的密码。如果 该参数为NULL，则，此函数与 open(OpenMode) 的行为相同。

bool QuaZipFile::open ( OpenMode mode,

 int *  method,

 int *  level,

 bool  raw,

 const char *  password = NULL

 )

打开文件，以便读取。

这是一个重载成员函数，出于便利性考虑而提供。它与上面那个函数的区别仅仅在于接受的参数不同。参数 password ，指定的是，用来解密该文件的密码。

method 和 level 指向的 两个整数 ，分别用来接收实际 使用的压缩方法和压缩级别数值。参考unzip.h 。

如果raw 为真（ true ），则不会进行解压。

method 参数 不应当传入 NULL 。如果 妳 不需要知道压缩级别的话， level 可传入 NULL 。

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

 )

打开文件，以便写入。

info 参数 ，指定关于该文件的信息。 它应当最少指定正确的文件名。另外 ，指定一个正确的时间戳，也狠有必要 (默认情况 下，会使用当前时间 ) 。参考 QuaZipNewInfo 。

password 参数 ，指定的是，用于加密的密码。如果妳不需要加密功能，则传入NULL。 crc 参数 ，之前以为它也是用于加密的，但是后来 发现不是这么回事，所以，除非 妳需要使用原始（raw）模式（参考下文），否则应当将它设置为0。

method 和 level 两个参数，分别指定的是压缩方式和压缩级别。唯一支持 的方法就是Z_DEFLATED，当然妳也可以传入0 以表示不压缩。如果 该压缩包中的所有文件都使用方法0，并且，显式指定 了压缩级别0 或者使用 QuaZip::setDataDescriptorWritingEnabled() 禁止 了写入数据描述片断，则， 这样所产生的压缩包会兼容1.0 ZIP 格式版本 ，如果妳需要产生这种效果的话请注意。 除此之外，对于方法 （method） 值为 0 的情况， level 参数值无意义。

如果 raw 为真（ true ），则不会进行压缩。 在这种情况下，需要传入 crc 和 info 中的uncompressedSize 字段参数。

windowBits 、  memLevel 和 strategy 三个参数，提供了对于zlib 算法的微调功能。 参考zlib 中的deflateInit2()。

如果 该文件是在原始（raw）模式下为了读取而打开的，则返回 csize() ，如果是在普通模式下为了读取而打开的，则返回 usize() ，如果是为了写入而打开的，则返回 pos() 。

遇到错误 则返回-1，调用 getZipError() 以获取错误码。

注意：

本来 QuaZipFile 被认为是顺序存储设备 ，那么 size() 应当返回 bytesAvailable() ，但是，本函数实际上返回的是文件的尺寸。可是 ，如果换个其它的函数名字的话，就会令人误解，所以，妳需要记住 这里的冲突之处。

覆盖 掉了 QIODevice 中的同名函数。

等价 于，调用 getFileInfo() 之后获取其中的compressedSize 字段值，但是本方法更方便及快速。

在调用此函数之前，必须以读取模式打开文件。

遇到错误 则返回-1，调用 getZipError() 以获取错误码。

等价 于，调用 getFileInfo() 之后获取其中的uncompressedSize 字段值，但是本方法更方便及快速。参考 getFileInfo() 文档 以了解一个相关的警告。

在调用此函数之前，必须以读取模式打开文件。

遇到错误 则返回-1，调用 getZipError() 以获取错误码。

bool QuaZipFile::getFileInfo ( QuaZipFileInfo  *  info        )

获取当前文件的相关信息。

此函数，等价于针对所关联的 QuaZip 对象调用 QuaZip::getCurrentFileInfo() ，但是 ，如果所关联的 QuaZip 是内部的，那么妳无法调用它的getCurrentFileInfo()(因为 妳无法访问到它 )，却仍然可以调用本函数。

在调用此函数之前，必须以读取模式打开文件。

返回：

出错 则返回假（false）。

此函数不支持zip64，如果文件 的尺寸小于4 GB 的话仍然能够兼容zip64，否则 的话，各个相关 的数值会产生一种被 QuaZipFileInfo64::toQuaZipFileInfo() 转换过的效果。

参考：

getFileInfo(QuaZipFileInfo64*)

bool QuaZipFile::getFileInfo ( QuaZipFileInfo64  *  info        )

获取当前文件的信息，并且支持zip64。

这是一个重载成员函数，出于便利性考虑而提供。它与上面那个函数的区别仅仅在于接受的参数不同。

参考：

getFileInfo(QuaZipFileInfo*)

调用 getZipError() 以确认关闭操作是否成功。

覆盖 掉了 QIODevice 中的同名函数。

李晓阳

李晓阳

李晓阳