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 | |
13 | class 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 | */ |
37 | class KARCHIVE_EXPORT KZip : public KArchive |
38 | { |
39 | Q_DECLARE_TR_FUNCTIONS(KZip) |
40 | |
41 | public: |
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 { |
76 | = 0, |
77 | ModificationTime = 1, |
78 | = 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 (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 () 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 | |
126 | protected: |
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 | |
181 | protected: |
182 | void virtual_hook(int id, void *data) override; |
183 | |
184 | private: |
185 | class KZipPrivate; |
186 | KZipPrivate *const d; |
187 | }; |
188 | |
189 | #endif |
190 | |