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

ZIP 压缩包。 详细说明……

#include < quazip/quazip.h >

详细说明

妳还可以使用这个类来打开压缩包中的文件，具体做法 就是， 在调用 QuaZipFile 类的构造函数时，传入本个类某个实例的指针。注意阅读 QuaZipFile::QuaZipFile(QuaZip*, QObject*) 的文档，以了解其中的某些坑。

这个类，原意是要为ZIP/UNZIP 软件包中的ZIP 子包和UNZIP 子包分别提供对应的接口。不过目前它仅支持UNZIP。

这个类的用法狠简单：使用构造函数 来创建一个实例； (如果 妳没有在构造函数中传入文件名的话 ) 然后使用setFile()函数 来设置ZIP 压缩包文件名；然后打开 （ open() ）；然后使用各个函数 来对它进行操作！当然 ，如果妳是个强迫症患者，那么， 在销毁实例之前，妳还可以调用关闭函数（close）来关闭压缩包文件，并且检查错误码。

妳还可以使用 getUnzFile() 和 getZipFile() 函数来获取ZIP 压缩包把柄 （handle），并在ZIP/UNZIP 软件包接口中直接使用这些把柄。

这个类，支持在ZIP 压缩包中使用本地化文件名，但是 妳需要使用setCodec()函数来设置正确的解码器。默认情况 下，会使用本机区域设置所对应的解码器。 我觉得，仅仅调用一个函数并不是什么大问题，但是，为了实现平台无关 性， 我们需要利用语系设置信息来实现某种文件 名编码自动探测机制。 不知谁有做这件事的好点子？

成员枚举文档

构造函数和析构函数文档

构造 QuaZip 对象 。

在打开所构造的对象之前，要调用setName()。

构造 QuaZip 对象 ，与 ioDevice 所表示的ZIP 文件关联。

对应的输入输出设备必须是可寻址的（seekable），否则，在做打开操作时，会出错。

成员函数文档

bool QuaZip::open ( Mode mode,

 zlib_filefunc_def *  ioApi = NULL

 )

参数 mode ，指定ZIP 压缩包的打开模式。参考 Mode 文档， 以了解细节。注意 ，在ZIP/UNZIP API 中，还有一个zipOpen2()函数， 它接受一个 globalcomment 参数， 但却没有在任何地方使用该参数，因此，此处的 open() 函数并未加入这个参数。如果 妳想设置全局说明文字，则参考 setComment() 文档。

如果 是通过显式设置 QIODevice 的方式来访问ZIP 文件的，那么，对应的设备会以必要的方式打开。如果 该设备已经被通过其它方式打开了，那么， QuaZIP 会检查它当前的打开模式是否 与所请求的操作对应的模式相兼容 。必要 的情况下，会进行寻址（seeking）操作， 以定位到设备中正确的位置。

返回：

成功 则返回真（true），否则返回假（false）。

注意：

ZIP/UNZIP API 中的打开操作不会返回错误码 - 它们只会通过返回 NULL 来表明出错。 为了简化问题 ， quazip.h 头文件中定义了一个额外的错误码 UNZ_ERROROPEN ，如果调用ZIP/UNZIP API 中的打开操作时返回 NULL ，则 getZipError() 会返回这个额外的错误码。

参数 ioApi ，指定 的是，要传递给ZIP/UNZIP 软件包的输入输出函数。参考unzip.h 、zip.h 和ioapi.h 以了解细节。注意 ， QuaZip 中的IO API 与原始软件包中对应的东西有所区别。文件路径参数 被修改为类型 voidpf ， 而 QuaZip 会对应地传入一个 QIODevice 指针。此处 所说的 QIODevice ， 可以通过 setIoDevice() 或构造函数 QuaZip(QIODevice*) 来显式设置，或者 ，通过文件 名来打开压缩包的情况下， 会在内部自动创建一个。默认 的接口 (qioapi.cpp) 会将所有的调用都传递给 QIODevice 中对应的接口。 这样做，不仅仅使得妳可以使用 QIODevice 来替换掉文件名参数，还带来了另一个美妙的副作用， 它会将文件尺寸的限制从2G提升到 4G(对于 非 zip64格式 的压缩包来说是如此 ) 。

注意：

如果需要支持zip64 ，那么， ioApi参数必须 是 NULL 。原因是，出于某种 后向兼容性方面的要求， 在提供这个参数时，仅用来支持 32 位接口。

如果使用了 no-auto-close 特性，那么， ioApi 参数 也应当保持为 NULL ，因为 旧的接口不支持“假关闭”（ 'fake close' ）操作， 这样会导致轻微的内存泄露及其它的问题 (例如 ，在进行打开操作时发生了某个错误则会将输出设备关闭 ) 。

总之 ：忘掉 ioApi 参数 ，世界 将会重新变得美好。

调用 getZipError() 以检查关闭操作是否成功。

如果 该文件是通过文件名打开的，那么，底层的 QIODevice 会被关闭且删除。

如果底层 的 QIODevice 是通过 setIoDevice() 或对应的构造函数显式设置的，那么， 在设置了自动关闭（auto-close）选项（默认 会被设置 ）的情况下，它也会 被 关闭。如果 妳不希望这样的话，那么，调用 setAutoClose() 来清除这个自动关闭选项。

从 Qt  5.1开始，引入了 QSaveFile 。 它打破了 QIODevice 的接口，具体就是，将 close() 变成私有方法，因而导致 ， 在通过基类中对应的公有方法 对其进行 调用时，会引起程序崩溃。 这是对于差劲设计的一个绝佳例子， 它展示了，妳永远不应当打破基类和子类之间的“是一个”（is-a）关系。 QuaZIP 会绕过这个问题，具体做法就是利用qobject_cast<>来检查当前的 QIODevice 是否是一个 QSaveFile 实例，如果是的话，则调用 QSaveFile::commit() ，而不是 close() 。 这种做法不太优雅，但是，最起码它使得妳的程序能够工作而不会崩溃。注意 ，如果 妳清除了自动关闭（auto-close）选项，那么也不会有这个问题，同时commit()也不会被调用。

void QuaZip::setFileNameCodec ( QTextCodec  *  fileNameCodec        )

设置将要用于编码/解码压缩包中的文件名的编解码器。

void QuaZip::setCommentCodec ( QTextCodec  *  commentCodec        )

设置将要用于编码/解码压缩包中的说明文字的编解码器。

这个编解码器，默认对应于系统中的本地语系设置，大部分情况下是比较合理的。

void QuaZip::setZipName (  const  QString  &  zipName        )

设置ZIP 文件的名字。

如果ZIP 文件已经打开，则什么也不做。

不会重置由 getZipError() 返回的错误码。

参考：

setIoDevice() 、 getIoDevice() 、 getZipName()

void QuaZip::setIoDevice ( QIODevice  *  ioDevice        )

设置代表着ZIP 文件的设备。

如果ZIP 文件已经打开，则什么也不做。

不会重置由 getZipError() 返回的错误码。

参考 ：

getIoDevice() 、 getZipName() 、 setZipName()

每当 妳调用任何一个会访问到ZIP 压缩包中内容的函数时，错误码都会被重置为 UNZ_OK ，即使该函数是常量函数（ const ）(例如 getEntriesCount() )也是如此。 open() 和 close() 也会重置错误码。阅读对应函数 的文档，以了解错误码相关的细节。

如果出错 ，则返回负数的错误码。后续调用 getZipError() 的话也会返回同样的错误码。

void QuaZip::setComment (  const  QString  &  comment        )

设置ZIP 文件中的全局说明文字。

说明文字 会在进行关闭操作时被写入到压缩包中。 QuaZip 通过 QuaZip::mdAdd 模式 来区分无效的 （null）QByteArray() 说明文字和空白的""说明文字。无效 的（null）说明文字，是默认值，它的意思是“不要改变说明文字内容”。 而空白的说明文字，会导致删除原有的说明文字内容。

参考：

open()

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

成功 则返回真（ true ），否则返回假（ false ）。调用 getZipError() 以判断 是否出错 。

只能 在 QuaZip::mdUnzip 模式下使用。

注意：

如果遇到 了文件末尾， getZipError() 会返回 UNZ_OK ，而不是 UNZ_END_OF_LIST_OF_FILE 。 主要目的是为了让以下代码写起来更轻松：

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

// 做某种处理

}

if (zip.getZipError()==UNZ_OK) {

// 狠好，没有出错

}

bool QuaZip::setCurrentFile (  const QString &  fileName,

CaseSensitivity cs = csDefault

 )

按照名字设置当前文件。

成功 则返回真（ true ），否则返回假（ false ）。 cs 指定 的是文件名的大小写敏感性。 若遇到错误，则调用 getZipError() 以获取具体的错误码。

本函数并不是对unzLocateFile()函数的封装。这是因为，我需要实现与语系相关的大小写不敏感的字符串比较。

以下是本函数与原有实现之间的区别：

• •. 如果 未找到文件，错误码将是 UNZ_OK ，而不是 UNZ_END_OF_LIST_OF_FILE  (参考 goToNextFile() )。

• •.如果此函数执行失败，那么，它会取消设置当前文件，而不是将当前文件恢复到调用之前的状态。

如果 fileName 是一个无效（null）字符串，那么，本函数会取消设置当前文件，并且返回真（ true ）。注意 ，如果文件本身处于打开状态，那么妳需要先关闭它！ 参考 QuaZipFile::QuaZipFile(QuaZip*,QObject*) 以了解细节。

只应当在 QuaZip::mdUnzip 模式下使用。

参考：

setFileNameCodec() 、 CaseSensitivity

bool QuaZip::getCurrentFileInfo ( QuaZipFileInfo  *  info        )  const

获取当前文件的信息。

将信息填充到由 info 指向的数据结构中。成功 则返回真（ true ），否则返回假（ false ）。失败 的情况下， info 所指向的数据结构不会被改变。如果出错 了，则 getZipError() 会返回对应的错误码。

只应当在 QuaZip::mdUnzip 模式下使用。

在以下情况下，不会做任何事，并且会返回假（ false ）。

• •.ZIP尚未打开；

• •.ZIP中不包含当前文件。

在这两种情况下， getZipError() 都会返回 UNZ_OK ，因为根本未进行ZIP/UNZIP API 调用。

这个重载函数不支持zip64，但是，遇到zip64 压缩包时仍然能正确处理，只有一个例外：如果某个尺寸(压缩后或压缩前)大于0xFFFFFFFFu，那么，它会被记录成0xFFFFFFFFu。

参考：

getCurrentFileInfo(QuaZipFileInfo64* info)const

QuaZipFileInfo64::toQuaZipFileInfo(QuaZipFileInfo&)const

bool QuaZip::getCurrentFileInfo ( QuaZipFileInfo64  *  info        )  const

获取当前文件的信息。

这是一个重载成员函数，出于便利性考虑而提供。它与上面那个函数的区别仅仅在于接受的参数不同。这个函数支持zip64。如果压缩包本身未使用zip64，那么，除了参数类型不同之外，本函数与getCurrentFileInfo(QuaZipFileInfo* info)等同。

等价 于，调用 getCurrentFileInfo() 之后再获取 QuaZipFileInfo 结构的文件名字段值，不过本函数执行得更快且更方便。

只应当在 QuaZip::mdUnzip 模式下使用。

文件 名列表。如果出错或者压缩 包为空（调用 getZipError() 以确认到底是哪种情况 ），则返回空白列表。

参考：

getFileInfoList()

QList <  QuaZipFileInfo  > QuaZip::getFileInfoList        (  )  const

返回压缩包中所有文件的信息列表。

返回：

由 QuaZipFileInfo 对象组成的 列表。如果出错或者压缩 包为空（调用 getZipError() 以确认到底是哪种情况 ），则返回空白列表。

本函数不支持zip64，但是能够处理zip64 压缩 包，其结果会通过 QuaZipFileInfo64::toQuaZipFileInfo() 进行转换。如果文件尺寸 都小于4 GB，那么，仍然 是正常工作。

参考：

getFileNameList()

getFileInfoList64()

QList <  QuaZipFileInfo64  > QuaZip::getFileInfoList64        (  )  const

返回压缩包中所有文件的信息列表。

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

参考：

getFileNameList()

getFileInfoList()

setAutoClose()

默认情况 下，QuaZIP 会在 open() 被调用时打开底层的 QIODevice ， 在 close() 被调用时关闭底层的 QIODevice 。 在某些情况下，如果该设备是显式通过 setIoDevice() 设置的，那么，可能需要保持 该设备处于打开状态。如果通过 本方法清除了自动关闭（auto-close）选项，那么， 在设备是显式设置的情况下， 该设备不会被自动关闭。

如果 妳需要清除这个选项值的话，那么，建议在打开压缩 包之前就做这个动作。 不然的话，QuaZIP 在 open() 调用期间发现打开设备之后出现某种错误的话，可能会关闭该设备。

如果该设备不是显式设置的，而是通过 setZipName() 或对应的构造函数设置了ZIP 文件名，那么，自动关闭（auto-close）选项将不起作用，内部设备 一定会被关闭，因为没有其它手段来关闭它了。

参考：

isAutoClose()

setIoDevice()

void QuaZip::setDefaultFileNameCodec ( QTextCodec  *  codec        ) [static]

设置默认使用的文件名编解码器。

默认 编解码器会被构造函数所使用，因为，调用 本函数并不会影响到当时已经创建好的 QuaZip 实例。

此处设置 的编解码器可通过调用 setFileNameCodec() 来覆盖掉。如果两个函数 都未被调用过，则，会使用 QTextCodec::codecForLocale() 来解码及编码文件名。如果 妳的应用程序中还有别的库也依赖QuaZIP 的话，那么，要小心使用本函数。那些 库可能会自行调用本函数，因而覆盖掉妳的设置。或者，它们可能 会依赖于默认编码才能正常工作，因而在妳改变了编码之后可能会奇怪地出错。出于 这个原因，我建议，当妳在开发一个库，而不是开发应用程序时，不要使用这个函数。应当 喊妳的库的用户，在需要使用特殊编码时调用这个函数。

大部分情况下，应当使用 setFileNameCodec() ，而不是本函数。然而 ，如果妳用到了某个使用了QuaZIP 的第三方代码的话，那么 ，以上说明的那些原因就可能成为妳真正需要使用本函数的原因了，因为第三代码 可能并不能理解妳所使用的编码，且又未提供手段来指定要使用的编码。对 于 JlCompress 类，就是这样的情况， 它是第三方贡献出来的，尚不支持显式地指定编码参数。

简而言之 ： 尽可能地使用 setFileNameCodec() ，如果 妳无法访问到底层的 QuaZip 实例，那么可以 setDefaultFileNameCodec() 使用。

参数：

void QuaZip::setDefaultFileNameCodec (  const char *  codecName        ) [static]

这是一个重载成员函数，出于便利性考虑而提供。它与上面那个函数的区别仅仅在于接受的参数不同。等价于调用setDefaultFileNameCodec(QTextCodec::codecForName(codecName))。

佐佐木希

未知美人

未知美人

李晓阳