From: Konrad Rosenbaum Date: Mon, 12 Aug 2013 19:55:35 +0000 (+0200) Subject: add docu for ZIP classes X-Git-Url: http://git.silmor.de/gitweb/?a=commitdiff_plain;h=3825a36577950bff03a32be9bb605bf469d55243;p=web%2Fkonrad%2Ftaurus.git add docu for ZIP classes --- diff --git a/zip/qtzipbase.h b/zip/qtzipbase.h index 441db75..2fc0168 100644 --- a/zip/qtzipbase.h +++ b/zip/qtzipbase.h @@ -35,14 +35,18 @@ THE SOFTWARE. */ #endif namespace QtZipHelper { - +///Base class of Zip and Unzip, see those for details class ZIPHLP_EXPORT ZipHlpBase:public QObject { public: + ///create Zip object with parent explicit ZipHlpBase(QObject* parent = 0); + ///delete the object virtual ~ZipHlpBase(); + ///abstract base function: return true if the ZIP file is open virtual bool isOpen()const =0; + ///abstract base function: close the ZIP file virtual void close()=0; protected: struct Private; diff --git a/zip/qtzipbase_p.h b/zip/qtzipbase_p.h index 2726c58..c16b3a1 100644 --- a/zip/qtzipbase_p.h +++ b/zip/qtzipbase_p.h @@ -30,6 +30,8 @@ THE SOFTWARE. */ #include class QIODevice; + +///\internal private data of ZipHlpBase struct QtZipHelper::ZipHlpBase::Private { QIODevice*device; zlib_filefunc_def ffunc; diff --git a/zip/qtziphlp.h b/zip/qtziphlp.h index f729a02..b953ced 100644 --- a/zip/qtziphlp.h +++ b/zip/qtziphlp.h @@ -34,26 +34,40 @@ namespace QtZipHelper { class Zip; class Unzip; + +///Helper class: reports information about a specific file entry in the ZIP archive. class ZIPHLP_EXPORT ZipFileInfo { public: + ///Empty/invalid info object. ZipFileInfo(); + ///Copy an info object. ZipFileInfo(const ZipFileInfo&); + ///Copy an info object. ZipFileInfo& operator=(const ZipFileInfo&); + ///returns true if this is a valid info object bool isValid()const{return !mName.isEmpty();} + ///returns true if this is a valid info object, so the info object + ///can be used in if-statements directly operator bool()const{return !mName.isEmpty();} + ///returns the file name of the stored file QString fileName()const{return mName;} + ///returns the creation time of the file stored in the ZIP QDateTime createTime()const{return mTime;} + ///returns the code of the compression method used with this file int rawCompressionMethod()const{return mMethod;} + ///returns the CRC32 stored for this file ulong fileCRC()const{return mCRC;} + ///returns the uncompressed file size stored for this file ulong uncompressedSize()const{return mUSize;} private: friend class Zip; friend class Unzip; + ///\internal instantiates an info object with actual info ZipFileInfo(const QString&,const QDateTime&,int,ulong,ulong); QDateTime mTime; @@ -61,52 +75,98 @@ class ZIPHLP_EXPORT ZipFileInfo int mMethod; ulong mCRC,mUSize; }; - + +///This class represents a ZIP file being assembled. class ZIPHLP_EXPORT Zip:public ZipHlpBase { Q_OBJECT friend class Unzip; public: + ///create a new ZIP object explicit Zip(QObject* parent = 0); + ///delete the ZIP object and implicitly close it virtual ~Zip(); + + ///Defines how the ZIP file is opened. enum OpenMode { + ///Creates a fresh ZIP archive, even if the file exists. OpenTruncate=0, + ///If the file is new: create it, if it exists: append more files to the existing archive. OpenAppend=1 }; + ///returns true if the ZIP file is open for adding files bool isOpen() const; public slots: + ///attached this ZIP object to the given device, does not take ownership of the device, + ///you are responsible for closing or reparenting it virtual bool open(QIODevice *d, OpenMode mode=OpenTruncate); + ///closes the ZIP object (writing headers, trailers, etc.), but does not close the + ///actual QIODevice virtual void close(); + ///stores the content of the given QIODevice in the ZIP archive, compressing + ///it at the same time, the method assumes that the device is at the correct + ///position to start reading (i.e. if it is a file: you are responsible for + ///seeking to the start first) virtual bool storeFile(const QString &name, QIODevice &file, const QDateTime &time = QDateTime::currentDateTime()); + ///stores the byte array as a file in the ZIP file, compressing it virtual bool storeFile(const QString&name, QByteArray content, const QDateTime &time = QDateTime::currentDateTime()); + ///assumes the file is properly compressed and the info object contains the + ///correct information - use this for copying from an Unzip object virtual bool storeRawFile(const ZipFileInfo&info, QIODevice &file); + ///assumes the file is properly compressed and the info object contains the + ///correct information - use this for copying from an Unzip object virtual bool storeRawFile(const ZipFileInfo&info, QByteArray content); }; +///This class represents a ZIP file being read. class ZIPHLP_EXPORT Unzip:public ZipHlpBase { Q_OBJECT public: + ///create a new ZIP object explicit Unzip(QObject*parent=0); + ///delete the ZIP object virtual ~Unzip(); + ///returns true if the ZIP file is currently open for reading virtual bool isOpen() const; public slots: + ///attaches a QIODevice to the ZIP object, does not take ownership of the device, + ///you are responsible for closing or reparenting it virtual bool open(QIODevice *d); + ///closes the ZIP object (abandoning internal state), but does not close the + ///actual QIODevice virtual void close(); + ///returns the amount of files stored in this ZIP file virtual int fileCount()const; + ///jumps to the first file stored in the ZIP file, returning its information virtual ZipFileInfo firstFile(); + ///moves to the next file in the ZIP file, returning its information virtual ZipFileInfo nextFile(); + ///tries to find a file with the given name, returning its information virtual ZipFileInfo locateFile(const QString &name, Qt::CaseSensitivity cs = Qt::CaseSensitive); + ///returns information about the file currently being unpacked virtual ZipFileInfo currentFile()const; + ///returns information about the file currently being unpacked + ///and stores its uncompressed content in the given QIODevice virtual ZipFileInfo currentFile(QIODevice &d)const; + ///returns information about the file currently being unpacked + ///and stores its uncompressed content in the given byte array virtual ZipFileInfo currentFile(QByteArray&)const; + ///returns the uncompressed content of the current file virtual QByteArray currentFileContent()const; + ///returns information about the file currently being unpacked + ///and stores its still compressed content in the given QIODevice virtual ZipFileInfo currentFileRaw(QIODevice &d)const; + ///returns information about the file currently being unpacked + ///and stores its still compressed content in the given byte array virtual ZipFileInfo currentFileRaw(QByteArray&)const; + ///returns the still compressed content of the current file virtual QByteArray currentFileRawContent()const; + ///returns the name of the file currently being uncompressed virtual QString currentFileName()const; + ///copies the current file to the given Zip object, returns true on success virtual bool copyCurrentFile(Zip&)const; };