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

source code of karchive/src/kzip.h