1 /* This file is part of the KDE libraries
2 Copyright (C) 2002 Holger Schroeder <holger-kde@holgis.net>
4 This library is free software; you can redistribute it and/or
5 modify it under the terms of the GNU Library General Public
6 License version 2 as published by the Free Software Foundation.
8 This library is distributed in the hope that it will be useful,
9 but WITHOUT ANY WARRANTY; without even the implied warranty of
10 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
11 Library General Public License for more details.
13 You should have received a copy of the GNU Library General Public License
14 along with this library; see the file COPYING.LIB. If not, write to
15 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
16 Boston, MA 02110-1301, USA.
25 * This class implements a kioslave to access zip files from KDE.
26 * You can use it in QIODevice::ReadOnly or in QIODevice::WriteOnly mode, and it
27 * behaves just as expected.
28 * It can also be used in QIODevice::ReadWrite mode, in this case one can
29 * append files to an existing zip archive. When you append new files, which
30 * are not yet in the zip, it works as expected, i.e. the files are appended at the end.
31 * When you append a file, which is already in the file, the reference to the
32 * old file is dropped and the new one is added to the zip - but the
33 * old data from the file itself is not deleted, it is still in the
34 * zipfile. so when you want to have a small and garbage-free zipfile,
35 * just read the contents of the appended zip file and write it to a new one
36 * in QIODevice::WriteOnly mode. This is especially important when you don't want
37 * to leak information of how intermediate versions of files in the zip
39 * For more information on the zip fileformat go to
40 * http://www.pkware.com/products/enterprise/white_papers/appnote.html
41 * @short A class for reading/writing zip archives.
42 * @author Holger Schroeder <holger-kde@holgis.net>
44 class KIO_EXPORT KZip
: public KArchive
48 * Creates an instance that operates on the given filename.
49 * using the compression filter associated to given mimetype.
51 * @param filename is a local path (e.g. "/home/holger/myfile.zip")
53 KZip( const QString
& filename
);
56 * Creates an instance that operates on the given device.
57 * The device can be compressed (KFilterDev) or not (QFile, etc.).
58 * @warning Do not assume that giving a QFile here will decompress the file,
59 * in case it's compressed!
60 * @param dev the device to access
62 KZip( QIODevice
* dev
);
65 * If the zip file is still opened, then it will be
66 * closed automatically by the destructor.
71 * Describes the contents of the "extra field" for a given file in the Zip archive.
73 enum ExtraField
{ NoExtraField
= 0, ///< No extra field
74 ModificationTime
= 1, ///< Modification time ("extended timestamp" header)
79 * Call this before writeFile or prepareWriting, to define what the next
80 * file to be written should have in its extra field.
81 * @param ef the type of "extra field"
84 void setExtraField( ExtraField ef
);
87 * The current type of "extra field" that will be used for new files.
88 * @return the current type of "extra field"
89 * @see setExtraField()
91 ExtraField
extraField() const;
94 * Describes the compression type for a given file in the Zip archive.
96 enum Compression
{ NoCompression
= 0, ///< Uncompressed.
97 DeflateCompression
= 1 ///< Deflate compression method.
102 * Call this before writeFile or prepareWriting, to define whether the next
103 * files to be written should be compressed or not.
104 * @param c the new compression mode
107 void setCompression( Compression c
);
110 * The current compression mode that will be used for new files.
111 * @return the current compression mode
112 * @see setCompression()
114 Compression
compression() const;
117 * Write data to a file that has been created using prepareWriting().
118 * @param data a pointer to the data
119 * @param size the size of the chunk
120 * @return true if successful, false otherwise
122 virtual bool writeData( const char* data
, qint64 size
);
125 /// Reimplemented from KArchive
126 virtual bool doWriteSymLink(const QString
&name
, const QString
&target
,
127 const QString
&user
, const QString
&group
,
128 mode_t perm
, time_t atime
, time_t mtime
, time_t ctime
);
129 /// Reimplemented from KArchive
130 virtual bool doPrepareWriting( const QString
& name
, const QString
& user
,
131 const QString
& group
, qint64 size
, mode_t perm
,
132 time_t atime
, time_t mtime
, time_t ctime
);
135 * Write data to a file that has been created using prepareWriting().
136 * @param size the size of the file
137 * @return true if successful, false otherwise
139 virtual bool doFinishWriting( qint64 size
);
142 * Opens the archive for reading.
143 * Parses the directory listing of the archive
144 * and creates the KArchiveDirectory/KArchiveFile entries.
145 * @param mode the mode of the file
147 virtual bool openArchive( QIODevice::OpenMode mode
);
149 /// Closes the archive
150 virtual bool closeArchive();
153 * @internal Not needed for zip
155 virtual bool doWriteDir( const QString
& name
, const QString
& user
,
156 const QString
& group
, mode_t perm
, time_t atime
,
157 time_t mtime
, time_t ctime
);
160 virtual void virtual_hook( int id
, void* data
);
164 KZipPrivate
* const d
;
169 * A KZipFileEntry represents an file in a zip archive.
171 class KIO_EXPORT KZipFileEntry
: public KArchiveFile
175 * Creates a new zip file entry. Do not call this, KZip takes care of it.
177 KZipFileEntry( KZip
* zip
, const QString
& name
, int access
, int date
,
178 const QString
& user
, const QString
& group
, const QString
& symlink
,
179 const QString
& path
, qint64 start
, qint64 uncompressedSize
,
180 int encoding
, qint64 compressedSize
);
183 * Destructor. Do not call this.
187 int encoding() const;
188 qint64
compressedSize() const;
190 /// Only used when writing
191 void setCompressedSize(qint64 compressedSize
);
193 /// Header start: only used when writing
194 void setHeaderStart(qint64 headerstart
);
195 qint64
headerStart() const;
197 /// CRC: only used when writing
198 unsigned long crc32() const;
199 void setCRC32(unsigned long crc32
);
201 /// Name with complete path - KArchiveFile::name() is the filename only (no path)
202 const QString
&path() const;
205 * @return the content of this file.
206 * Call data() with care (only once per file), this data isn't cached.
208 virtual QByteArray
data() const;
211 * This method returns a QIODevice to read the file contents.
212 * This is obviously for reading only.
213 * Note that the ownership of the device is being transferred to the caller,
214 * who will have to delete it.
215 * The returned device auto-opens (in readonly mode), no need to open it.
217 virtual QIODevice
* createDevice() const;
220 class KZipFileEntryPrivate
;
221 KZipFileEntryPrivate
* const d
;