StupidBeauty
??Read times:440????Posted at:Sat Jan 7 11:00:43 2017?? - no title specified

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

ZIP 压缩包。 详细说明……

#include < quazip/quazip.h >

详细说明

ZIP压缩包。

这个类,实现了针对ZIP 压缩包的基本接口。它可用来读取ZIP 压缩包中的列表信息,以及获取其中文件的信息。

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

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

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

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

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

成员枚举文档

enum  QuaZip::Mode

ZIP 文件的打开模式。

枚举值:

mdNotOpen

ZIP文件尚未打开。这是初始模式。

mdUnzip

ZIP文件已打开,用于读取其中的文件。

mdCreate

ZIP文件 已在对 open() 的调用中创建。

mdAppend

ZIP文件 已打开为追加模式。 这对应的是ZIP/UNZIP 软件包中的 APPEND_STATUS_CREATEAFTER 模式,表示 的是, 这个zip 被追加到某个已有的文件中。 当那个文件中包含有自解压代码时,这种模式 狠有用。 当妳想要向某个已有的ZIP 压缩包中加入文件时,显然 不应当 使用这种模式。

mdAdd

ZIP文件被打开,用于向压缩包中添加文件。

构造函数和析构函数文档

QuaZip::QuaZip

(

)

构造 QuaZip 对象

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

QuaZip::QuaZip

(

QIODevice  * 

ioDevice

)

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

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

成员函数文档

bool QuaZip::open ( Mode mode,

 zlib_filefunc_def *  ioApi = NULL

 )

打开ZIP 文件

参数 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 参数 ,世界 将会重新变得美好。

void QuaZip::close (  )

关闭ZIP文件

调用 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::setFileNameCodec (  const char *  fileNameCodecName        )

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

这是出于便利性考虑而增加的重载成员函数。它与上面那个函数的区别仅仅在于参数不同。等价于调用setFileNameCodec(QTextCodec::codecForName(codecName));。

void QuaZip::setCommentCodec ( QTextCodec  *  commentCodec        )

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

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

void QuaZip::setCommentCodec (  const char *  commentCodecName        )

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

这是出于便利性考虑而增加的重载成员函数。它与上面那个函数的区别仅仅在于参数不同。等价于调用setCommentCodec(QTextCodec::codecForName(codecName));。

void QuaZip::setZipName (  const  QString  &  zipName        )

设置ZIP 文件的名字。

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

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

参考

setIoDevice() getIoDevice() getZipName()

void QuaZip::setIoDevice ( QIODevice  *  ioDevice        )

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

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

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

参考

getIoDevice() getZipName() setZipName()

int QuaZip::getZipError (  )  const

返回最后一次操作的错误码。

如果最后 一次操作是成功了,那么返回 UNZ_OK

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

int QuaZip::getEntriesCount (  )  const

返回ZIP 中心目录中的条目个数。

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

void QuaZip::setComment (  const  QString  &  comment        )

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

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

参考

open()

bool QuaZip::goToFirstFile (  )

将当前文件设置成压缩包中的第一个文件。

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

bool QuaZip::goToNextFile (  )

将当前文件设置成压缩包中的下一个文件。

成功 则返回真( 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)等同。

QString  QuaZip::getCurrentFileName

(

)

const

返回当前文件名。

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

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

QStringList  QuaZip::getFileNameList

(

)

const

返回压缩包中的文件名列表。

返回

文件 名列表。如果出错或者压缩 包为空(调用 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()

bool QuaZip::isAutoClose (  )  const

返回自动关闭(auto-close)选项值。

参考

setAutoClose()

void QuaZip::setAutoClose (  bool  autoClose        )  const

设置或清除自动关闭(auto-close)选项值。

默认情况 下,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() 使用。

参数

codec

要默认使用的编解码器。如果值为NULL,则重置为默认值。

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

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

佐佐木希

未知美人

未知美人

李晓阳