1/* This file is part of the KDE libraries
2 SPDX-FileCopyrightText: 2002 Holger Schroeder <holger-kde@holgis.net>
3
4 SPDX-License-Identifier: LGPL-2.0-or-later
5*/
6#ifndef KZIP_H
7#define KZIP_H
8
9#include <karchive.h>
10
11#include "kzipfileentry.h" // for source compat
12
13class KZipFileEntry;
14/*!
15 * \class KZip
16 * \inmodule KArchive
17 *
18 * \brief A class for reading / writing zip archives.
19 *
20 * You can use it in QIODevice::ReadOnly or in QIODevice::WriteOnly mode, and it
21 * behaves just as expected.
22 * It can also be used in QIODevice::ReadWrite mode, in this case one can
23 * append files to an existing zip archive. When you append new files, which
24 * are not yet in the zip, it works as expected, i.e. the files are appended at the end.
25 * When you append a file, which is already in the file, the reference to the
26 * old file is dropped and the new one is added to the zip - but the
27 * old data from the file itself is not deleted, it is still in the
28 * zipfile. So when you want to have a small and garbage-free zipfile,
29 * just read the contents of the appended zip file and write it to a new one
30 * in QIODevice::WriteOnly mode. This is especially important when you don't want
31 * to leak information of how intermediate versions of files in the zip
32 * were looking.
33 *
34 * For more information on the zip fileformat go to
35 * http://www.pkware.com/products/enterprise/white_papers/appnote.html
36 */
37class KARCHIVE_EXPORT KZip : public KArchive
38{
39 Q_DECLARE_TR_FUNCTIONS(KZip)
40
41public:
42 /*!
43 * Creates an instance that operates on the given filename.
44 * using the compression filter associated to given mimetype.
45 *
46 * \a filename is a local path (e.g. "/home/holger/myfile.zip")
47 */
48 explicit KZip(const QString &filename);
49
50 /*!
51 * Creates an instance that operates on the given device.
52 *
53 * The device can be compressed (KCompressionDevice) or not (QFile, etc.).
54 *
55 * \a dev the device to access
56 *
57 * \warning Do not assume that giving a QFile here will decompress the file,
58 * in case it's compressed!
59 */
60 explicit KZip(QIODevice *dev);
61
62 /*!
63 * If the zip file is still opened, then it will be
64 * closed automatically by the destructor.
65 */
66 ~KZip() override;
67
68 /*!
69 * Describes the contents of the "extra field" for a given file in the Zip archive.
70 *
71 * \value NoExtraField No extra field
72 * \value ModificationTime Modification time ("extended timestamp" header)
73 * \omitvalue DefaultExtraField
74 */
75 enum ExtraField {
76 NoExtraField = 0,
77 ModificationTime = 1,
78 DefaultExtraField = 1,
79 };
80
81 /*!
82 * Call this before writeFile or prepareWriting, to define what the next
83 * file to be written should have in its extra field.
84 *
85 * \a ef the type of "extra field"
86 * \sa extraField()
87 */
88 void setExtraField(ExtraField ef);
89
90 /*!
91 * The current type of "extra field" that will be used for new files.
92 *
93 * Returns the current type of "extra field"
94 * \sa setExtraField()
95 */
96 ExtraField extraField() const;
97
98 /*!
99 * Describes the compression type for a given file in the Zip archive.
100 *
101 * \value NoCompression Uncompressed
102 * \value DeflateCompression Deflate compression method
103 */
104 enum Compression {
105 NoCompression = 0,
106 DeflateCompression = 1,
107 };
108
109 /*!
110 * Call this before writeFile or prepareWriting, to define whether the next
111 * files to be written should be compressed or not.
112 *
113 * \a c the new compression mode
114 * \sa compression()
115 */
116 void setCompression(Compression c);
117
118 /*!
119 * The current compression mode that will be used for new files.
120 *
121 * Returns the current compression mode
122 * \sa setCompression()
123 */
124 Compression compression() const;
125
126protected:
127 /// Reimplemented from KArchive
128 bool doWriteSymLink(const QString &name,
129 const QString &target,
130 const QString &user,
131 const QString &group,
132 mode_t perm,
133 const QDateTime &atime,
134 const QDateTime &mtime,
135 const QDateTime &ctime) override;
136 /// Reimplemented from KArchive
137 bool doPrepareWriting(const QString &name,
138 const QString &user,
139 const QString &group,
140 qint64 size,
141 mode_t perm,
142 const QDateTime &atime,
143 const QDateTime &mtime,
144 const QDateTime &creationTime) override;
145
146 /*
147 * Write data to a file that has been created using prepareWriting().
148 * \a size the size of the file
149 * Returns true if successful, false otherwise
150 */
151 bool doFinishWriting(qint64 size) override;
152
153 /*
154 * Write data to a file that has been created using prepareWriting().
155 * \a data a pointer to the data
156 * \a size the size of the chunk
157 * Returns true if successful, false otherwise
158 */
159 bool doWriteData(const char *data, qint64 size) override;
160
161 /*
162 * Opens the archive for reading.
163 * Parses the directory listing of the archive
164 * and creates the KArchiveDirectory/KArchiveFile entries.
165 * \a mode the mode of the file
166 */
167 bool openArchive(QIODevice::OpenMode mode) override;
168
169 /// Closes the archive
170 bool closeArchive() override;
171
172 /// Reimplemented from KArchive
173 bool doWriteDir(const QString &name,
174 const QString &user,
175 const QString &group,
176 mode_t perm,
177 const QDateTime &atime,
178 const QDateTime &mtime,
179 const QDateTime &ctime) override;
180
181protected:
182 void virtual_hook(int id, void *data) override;
183
184private:
185 class KZipPrivate;
186 KZipPrivate *const d;
187};
188
189#endif
190

source code of karchive/src/kzip.h